백엔드 이벤트의 클라이언트 식별

요약

클라이언트 식별(client identity)은 요청을 보낸 애플리케이션의 종류(브라우저, IDE, CLI, 모바일 앱, 스크립트)를 나타냅니다. Rails는 선언된 값을 허용 목록과 대조하고, 인식하지 못하는 값은 클라이언트가 보낸 임의의 텍스트를 저장하는 대신 버립니다.

클라이언트 식별(client identity)은 요청을 보낸 애플리케이션의 종류(브라우저, IDE, CLI, 모바일 앱, 스크립트)를 나타냅니다. GitLab Rails는 모든 요청에 대해 HTTP 헤더 X-Gitlab-Client-Type과 X-Gitlab-Client-Name으로 이를 확인합니다. 이 헤더는 IDE 확장, Duo CLI, AI Gateway, Duo Workflow Service가 이미 사용하고 있으며, 클라이언트의 릴리스는 X-Gitlab-Client-Version에서 읽어 함께 기록합니다.

Rails는 선언된 값을 허용 목록과 대조하고, 인식하지 못하는 값은 클라이언트가 보낸 임의의 텍스트를 저장하는 대신 버립니다. 허용 목록은 Gitlab::Tracking::ClientIdentity에 있습니다.

클라이언트 유형 값#

유형	의미
`browser`	웹 IDE를 포함한 웹 브라우저
`ide`	코드 에디터 또는 IDE 확장
`cli`	명령줄 도구
`mobile`	모바일 앱
`integration`	MCP 서버나 Slack 같은 통합을 통해 이루어진 요청
`system`	GitLab 자체: cron job, 러너, HTTP 기반 Git, Workhorse
`api`	스크립트 같은 식별되지 않은 API 호출자

클라이언트 이름 슬러그#

클라이언트 이름	유형
`chrome`, `firefox`, `safari`, `edge`, `opera`, `electron`	`browser`
`vscode`, `jetbrains`, `jetbrains-bundled`, `visual-studio`, `neovim`, `zed`, `kiro`	`ide`
`duo-cli`, `glab`	`cli`
`gitlab-mobile-ios`, `gitlab-mobile-android`	`mobile`
`slack`, `mcp`	`integration`
`gitlab-rails`	`system`

browser의 경우 Rails는 X-Gitlab-Client-Name 헤더에 chrome, firefox, safari, edge, opera, electron이 있으면 이를 받아들입니다. Workhorse는 브라우저 세션을 위해 에이전트의 HTTP 작업을 실행할 때 이 헤더를 보내며, 웹소켓이 열릴 때 Rails가 확인한 계열을 전달합니다. 그렇지 않으면 Rails는 User-Agent에서 계열을 읽습니다. 웹 프론트엔드는 X-Gitlab-Client-Type 헤더만 보냅니다. 그 밖의 브라우저는 이름 없이 browser 유형을 유지합니다.

클라이언트 버전#

X-Gitlab-Client-Version은 IDE 확장의 6.21.0이나 모바일 앱의 1.2.0처럼 클라이언트 자체의 릴리스를 담습니다. 릴리스는 값으로 허용 목록에 올릴 수 없으므로 Rails는 버전 형태일 때만 이를 유지합니다. 형태는 선택적 v, 선행 숫자, 그리고 숫자, 문자, ., -, +, _ 문자가 최대 62개 이어지는 것이며, 이는 gitlab_standard 스키마의 client_version 필드에 맞습니다. 그 외의 값은 버리며, 버전은 헤더에서 유형이나 이름을 선언한 클라이언트에 대해서만 유지합니다.

확인 우선순위#

X-Gitlab-Client-Type 헤더를 별칭 표로 정규화합니다. web과 web_browser는 browser를, duo_cli는 cli를 의미합니다.
X-Gitlab-Client-Name 헤더. 유효한 유형 헤더가 없으면 이 헤더가 유형도 결정합니다. Visual Studio Code, IntelliJ IDEA, Duo CLI 같은 제품 이름은 슬러그에 대응시킵니다. 선언된 유형과 다른 유형에 속하는 이름은 버립니다.
User-Agent: 기존 IDE 및 glab 패턴. gitlab-runner, git/, GitLab-Shell, gitlab-workhorse, Agent-Flow-via-GitLab-Workhorse는 system을, Mozilla/ User-Agent는 browser를 의미합니다.
그 외에는 이름 없는 api입니다.

허용 목록에 있는 이름이 없는 browser 식별은 User-Agent의 브라우저 계열에서 이름을 가져옵니다.

백그라운드 job으로 전파#

요청 미들웨어는 식별 정보를 Gitlab::ApplicationContext에 저장합니다. Labkit은 그 컨텍스트를 요청이 큐에 넣는 모든 Sidekiq job에 복사하고 워커에서 복원합니다. 따라서 사용자가 Duo를 리뷰어로 지정하거나 노트에서 Duo를 멘션해서 백그라운드 job이 만든 세션은 그 사용자의 클라이언트를 상속합니다. cron job처럼 요청 계보가 없는 job은 system으로 확인됩니다.

값이 나타나는 위치#

gitlab_standard Snowplow 컨텍스트의 client_type, client_name, client_version 필드. client_type과 client_name은 Snowflake의 PROD.COMMON.FCT_BEHAVIOR_STRUCTURED_EVENT에 있는 CLIENT_TYPE 및 CLIENT_NAME 칼럼입니다.
execute_llm_method 및 perform_completion_worker Duo Chat 이벤트의 client 속성. 이전 값이 있는 클라이언트는 그 값을 유지하고(web, web_ide, vscode, jetbrains, jetbrains_bundled, visual_studio, neovim, gitlab_cli), Duo CLI는 duo_cli를 보고하며, 그 밖의 모든 클라이언트는 mobile, ide, cli, integration, system, api를 더해 클라이언트 유형을 보고합니다.
요청 계보가 있는 경우 AI 사용량 이벤트의 extras.
Rails 및 Sidekiq 구조화 로그의 meta.client_type, meta.client_name, meta.client_version 필드.

클라이언트 추가#

Gitlab::Tracking::ClientIdentity의 허용 목록에 슬러그와 그 유형을 추가하고, 이 페이지의 표에도 슬러그를 추가합니다.
AI 호출만이 아니라 웹소켓 업그레이드를 포함한 모든 요청에 X-Gitlab-Client-Name을 보냅니다. 허용 목록에 있는 이름이면 유형을 확인하는 데 충분하므로 X-Gitlab-Client-Type은 선택 사항입니다. 분석에서 빌드를 구분할 수 있도록 클라이언트의 릴리스를 담은 X-Gitlab-Client-Version도 보냅니다. 요청이 유발한 백그라운드 작업은 요청이 담은 정보만 상속할 수 있습니다.