AI 이벤트 계측 가이드

요약

이 가이드는 AI 및 GitLab Duo Agentic Platform(DAP) 이벤트를 계측할 때 필요한 모든 필드를 설명합니다. AI 이벤트를 계측할 때는 Standard context 필드에 더해 DAP 전용 필드를 포함해야 합니다.

이 가이드는 AI 및 GitLab Duo Agentic Platform(DAP) 이벤트를 계측할 때 필요한 모든 필드를 설명합니다. AI 이벤트는 두 가지 컨텍스트 스키마를 사용합니다.

Standard Context - 모든 GitLab 이벤트에서 공통으로 사용하는 일반 필드를 담고 있습니다. Standard context 필드 문서를 참고합니다.
AI Context - 워크플로 및 세션 관리, 모델 정보, 토큰 추적을 위한 DAP 전용 필드를 담고 있습니다

개요#

AI 이벤트를 계측할 때는 Standard context 필드에 더해 DAP 전용 필드를 포함해야 합니다. 이 필드들은 AI Context 스키마의 일부이며 DAP(Duo Agentic Platform)와 AI Gateway 이벤트에만 해당합니다.

이 가이드를 사용하는 경우#

다음과 같은 경우에 이 가이드를 사용합니다.

GitLab Duo 기능(Duo Chat, Duo Workflow, AI 기반 제안)을 계측하는 경우
DAP(Duo Agentic Platform) 이벤트를 추적하는 경우
AI 모델 상호작용과 토큰 사용량을 기록하는 경우
AI 세션과 워크플로 실행을 모니터링하는 경우
이벤트 정의에 classification: duo가 있는 경우

AI Context 필드#

세션 및 워크플로 식별자#

필드	유형	설명	예시
`session_id`	string, null	인스턴스의 세션 식별자입니다(전역적으로 고유하지 않음).	`"session_abc123"`
`workflow_id`	string, null	전역적으로 고유한 세션 식별자입니다.	`"workflow_xyz789"`

워크플로 및 에이전트 정보#

필드	유형	설명	예시
`item_type`	string, null	실행 또는 추적 중인 항목의 유형입니다(최대 길이: 32자).	다음 중 하나: `"foundational_flow"`, `"foundational_agent"`, `"foundational_external_agent"`, `"custom_flow"`, `"custom_agent"`, `"custom_external_agent"`
`item_version`	string, null	기본 또는 커스텀 항목의 시맨틱 버전입니다(최대 길이: 32자).	`"1.0.0"`, `"1.1.0"`
`item_schema_version`	string, null	항목을 빌드하는 데 사용된 Flow Registry 프레임워크 버전입니다(최대 길이: 32자).	`"experimental"`, `"v1"`
`flow_name`	string, null	플로의 이름입니다(최대 길이: 64자).	`"chat"`, `"software_development"`, `"convert_to_gitlab_ci"`
`component_name`	string, null	플로 내 개별 구성 요소의 이름입니다(최대 길이: 64자).	에이전트 구성 요소의 이름입니다.
`agent_name`	string, null	플로 내에서 실행 중인 에이전트입니다.	`"duo_chat"`, `"code_agent"`, `"planning_agent"`
`custom_item_id`	integer, null	커스텀 항목 ID 입니다(커스텀 항목에만 채워짐)	`123`
`flow_registry_version`	string, null	플로를 빌드하는 데 사용된 Flow Registry 프레임워크 버전입니다(최대 길이: 64자). `item_schema_version`으로 대체되어 더 이상 사용되지 않습니다.	`"experimental"`, `"v1"`
`flow_type`	string, null	DAP 플로의 유형입니다(향후 더 많은 커스텀 플로가 포함될 예정). `flow_name`으로 대체되어 더 이상 사용되지 않습니다.	`"chat"`, `"software_development"`, `"convert_to_gitlab_ci"`
`flow_version`	string, null	플로에 대한 AI 기능 구현 버전입니다(최대 길이: 64자). `item_version`으로 대체되어 더 이상 사용되지 않습니다.	`"2.1.0"`, `"3.0.1"`
`agent_type`	string, null	플로 내에서 실행 중인 에이전트 유형입니다. `item_type`으로 대체되어 더 이상 사용되지 않습니다.	`"foundational"`, `"custom"`

모델 정보#

필드	유형	설명	예시
`model_provider`	string, null	AI 요청에 사용된 모델 제공업체입니다(최대 길이: 64자).	`"anthropic"`, `"vertex-ai"`
`model_engine`	string, null	AI 요청에 사용된 모델 엔진입니다(최대 길이: 64자).	`"claude-3-5"`, `"gemini-2.0"`
`model_name`	string, null	AI 요청에 사용된 모델 이름입니다(최대 길이: 64자).	`"claude-3-5-sonnet-20241022"`, `"gemini-2.0-flash-exp"`

토큰 추적#

토큰 추적 필드는 비용과 성능을 모니터링하기 위해 AI 모델 토큰의 사용량을 기록합니다.

필드	유형	설명	예시
`input_tokens`	integer, null	사용자 입력에서 발생한 토큰입니다.	`1500`, `3200`
`output_tokens`	integer, null	시스템이 생성한 토큰입니다.	`500`, `1200`
`total_tokens`	integer, null	입력 토큰과 출력 토큰의 합계입니다.	`2000`, `4400`
`ephemeral_5m_input_tokens`	integer, null	5분 동안 캐시된 입력 토큰입니다.	`100`, `250`
`ephemeral_1h_input_tokens`	integer, null	1시간 동안 캐시된 입력 토큰입니다.	`500`, `1000`
`cache_read`	integer, null	캐시 읽기 작업입니다.	`2`, `5`

완전한 계측 예시#

다음은 Standard Context 필드와 AI Context 필드를 모두 사용해 DAP 이벤트를 계측하는 전체 예시입니다.

track_internal_event(
  "request_duo_workflow_success",
  user: user,
  project: project,
  namespace: namespace,

  additional_properties: {
    # AI Context fields
    # Session and workflow identifiers
    session_id: session.id,
    workflow_id: session.id + instance.id,

    # Flow and agent information
    agent_name: "code_generator",
    flow_name: "chat",
    component_name: "AgentComponent",
    custom_item_id: nil,
    item_type: "foundational_agent",
    item_version: "2.1.0",
    item_schema_version: "v1",

    # Deprecated flow and agent information
    agent_type: "foundational",
    flow_type: "chat",
    flow_registry_version: "v1",
    flow_version: "2.1.0",

    # Model information (AI Context)
    model_provider: "anthropic",
    model_engine: "claude-3-5",
    model_name: "claude-3-5-sonnet-20241022",
    # Token tracking (AI Context)
    input_tokens: 1500,
    output_tokens: 800,
    total_tokens: 2300,
    ephemeral_5m_input_tokens: 500,
    ephemeral_1h_input_tokens: 1000,
    cache_read: 200
  }
)

AI Gateway 트리거 이벤트와 계측 패턴에 대한 추가 정보는 AI Gateway 계측 문서를 참고합니다.

세션 수준 이벤트#

다음 이벤트는 DAP 세션의 수명 주기를 보여 주며, 대부분의 플로에서 추적해야 합니다.

이벤트 액션	목적	실행 시점	필요한 컨텍스트
`request_duo_workflow` AND `receive_start_duo_workflow`	세션 시작	사용자가 새 플로 세션을 시작할 때	Standard + AI Context
`request_duo_workflow_success`	성공적 완료	플로가 성공적으로 완료될 때	Standard + AI Context
`request_duo_workflow_failure`	치명적 오류	시스템 장애가 발생할 때	Standard + AI Context
`request_duo_workflow_aborted`	연결 실패	연결 문제가 발생할 때	Standard + AI Context
`cleanup_stuck_agent_platform_session`	멈춘 세션 정리	세션 정리가 필요할 때	Standard + AI Context
`pause_duo_workflow`	플로 일시 중지	입력을 위해 일시 중지될 때	Standard + AI Context
`resume_duo_workflow`	플로 재개	승인이나 입력 후 일시 중지된 플로가 재개될 때	Standard + AI Context
`duo_workflow_tool_success`	도구 실행 성공	개별 도구가 완료될 때	Standard + AI Context
`duo_workflow_tool_failure`	도구 실행 실패	개별 도구가 실패할 때	Standard + AI Context
`token_usage_*`	토큰 소비	LLM 상호작용이 발생할 때	AI Context (token fields)
`request_'unit_primitive'`	사용자 접근 관리	사용자가 AI 서비스 접근 권한을 얻을 때	Standard Context

필드 세부 사항 및 모범 사례#

세션 및 워크플로 식별자#

session_id

특정 GitLab 인스턴스 안에서 사용자 세션을 식별하는 로컬 식별자입니다
인스턴스가 생성합니다
서로 다른 인스턴스 사이에서 전역적으로 고유하지 않습니다
로컬 세션 추적과 상관 분석에 사용합니다

토큰 추적 모범 사례#

AI Context에서 토큰 사용량을 추적할 때는 다음을 따릅니다.

AI 모델 상호작용을 추적할 때는 항상 total_tokens를 포함합니다
정확한 청구를 위해 입력 토큰과 출력 토큰을 따로 추적합니다
캐시 효과를 모니터링하기 위해 캐시 사용량(cache_read, ephemeral_5m_input_tokens, ephemeral_1h_input_tokens)을 기록합니다
모델별 분석이 가능하도록 AI Context에 모델 정보(model_provider, model_engine, model_name)를 포함합니다

청구 및 귀속#

올바른 청구와 고객 귀속을 위해 다음을 따릅니다.

correlation_id(Standard Context)를 포함합니다 - DAP 이벤트를 청구 대상 이벤트와 결합하는 데 반드시 필요합니다
ultimate_parent_namespace_id(Standard Context)를 포함합니다 - 고객 귀속이 사용량 청구와 일치하도록 보장합니다
feature_enabled_by_namespace_ids(Standard Context)를 포함합니다 - AI 데이터 모델에서 현재 사용하는 고객 귀속 방법입니다

AI Context에 필드 추가#

대부분의 AI 이벤트가 공통으로 가지는 새 속성을 추적하려면 AI Context에 새 필드를 추가할 수 있습니다.

AI Context에 새 필드를 추가하려면 다음과 같이 합니다.

iglu 리포지터리에 스키마를 업데이트하는 머지 리퀘스트를 생성합니다.
새 필드를 가명 처리해야 한다면 snowplow-pseudonymization 프로젝트의 적절한 가명 처리 구성에 추가합니다.
새 필드를 지원하도록 GitLab 코드베이스의 AI Context 구현을 업데이트합니다.
AI Context에 새 필드를 포함한 이벤트 전송을 시작합니다.
새 필드를 설명하도록 이 문서를 업데이트합니다.

AI 이벤트 계측 가이드

GitLab v19.5

원문 보기

번역일: 2026-09-18

요약

이 가이드는 AI 및 GitLab Duo Agentic Platform(DAP) 이벤트를 계측할 때 필요한 모든 필드를 설명합니다. AI 이벤트는 두 가지 컨텍스트 스키마를 사용합니다.

Standard Context - 모든 GitLab 이벤트에서 공통으로 사용하는 일반 필드를 담고 있습니다. Standard context 필드 문서를 참고합니다.
AI Context - 워크플로 및 세션 관리, 모델 정보, 토큰 추적을 위한 DAP 전용 필드를 담고 있습니다

개요#

이 가이드를 사용하는 경우#

다음과 같은 경우에 이 가이드를 사용합니다.

GitLab Duo 기능(Duo Chat, Duo Workflow, AI 기반 제안)을 계측하는 경우
DAP(Duo Agentic Platform) 이벤트를 추적하는 경우
AI 모델 상호작용과 토큰 사용량을 기록하는 경우
AI 세션과 워크플로 실행을 모니터링하는 경우
이벤트 정의에 classification: duo가 있는 경우

AI Context 필드#

세션 및 워크플로 식별자#

필드	유형	설명	예시
`session_id`	string, null	인스턴스의 세션 식별자입니다(전역적으로 고유하지 않음).	`"session_abc123"`
`workflow_id`	string, null	전역적으로 고유한 세션 식별자입니다.	`"workflow_xyz789"`

워크플로 및 에이전트 정보#

필드	유형	설명	예시
`item_type`	string, null	실행 또는 추적 중인 항목의 유형입니다(최대 길이: 32자).	다음 중 하나: `"foundational_flow"`, `"foundational_agent"`, `"foundational_external_agent"`, `"custom_flow"`, `"custom_agent"`, `"custom_external_agent"`
`item_version`	string, null	기본 또는 커스텀 항목의 시맨틱 버전입니다(최대 길이: 32자).	`"1.0.0"`, `"1.1.0"`
`item_schema_version`	string, null	항목을 빌드하는 데 사용된 Flow Registry 프레임워크 버전입니다(최대 길이: 32자).	`"experimental"`, `"v1"`
`flow_name`	string, null	플로의 이름입니다(최대 길이: 64자).	`"chat"`, `"software_development"`, `"convert_to_gitlab_ci"`
`component_name`	string, null	플로 내 개별 구성 요소의 이름입니다(최대 길이: 64자).	에이전트 구성 요소의 이름입니다.
`agent_name`	string, null	플로 내에서 실행 중인 에이전트입니다.	`"duo_chat"`, `"code_agent"`, `"planning_agent"`
`custom_item_id`	integer, null	커스텀 항목 ID 입니다(커스텀 항목에만 채워짐)	`123`
`flow_registry_version`	string, null	플로를 빌드하는 데 사용된 Flow Registry 프레임워크 버전입니다(최대 길이: 64자). `item_schema_version`으로 대체되어 더 이상 사용되지 않습니다.	`"experimental"`, `"v1"`
`flow_type`	string, null	DAP 플로의 유형입니다(향후 더 많은 커스텀 플로가 포함될 예정). `flow_name`으로 대체되어 더 이상 사용되지 않습니다.	`"chat"`, `"software_development"`, `"convert_to_gitlab_ci"`
`flow_version`	string, null	플로에 대한 AI 기능 구현 버전입니다(최대 길이: 64자). `item_version`으로 대체되어 더 이상 사용되지 않습니다.	`"2.1.0"`, `"3.0.1"`
`agent_type`	string, null	플로 내에서 실행 중인 에이전트 유형입니다. `item_type`으로 대체되어 더 이상 사용되지 않습니다.	`"foundational"`, `"custom"`

모델 정보#

필드	유형	설명	예시
`model_provider`	string, null	AI 요청에 사용된 모델 제공업체입니다(최대 길이: 64자).	`"anthropic"`, `"vertex-ai"`
`model_engine`	string, null	AI 요청에 사용된 모델 엔진입니다(최대 길이: 64자).	`"claude-3-5"`, `"gemini-2.0"`
`model_name`	string, null	AI 요청에 사용된 모델 이름입니다(최대 길이: 64자).	`"claude-3-5-sonnet-20241022"`, `"gemini-2.0-flash-exp"`

토큰 추적#

토큰 추적 필드는 비용과 성능을 모니터링하기 위해 AI 모델 토큰의 사용량을 기록합니다.

필드	유형	설명	예시
`input_tokens`	integer, null	사용자 입력에서 발생한 토큰입니다.	`1500`, `3200`
`output_tokens`	integer, null	시스템이 생성한 토큰입니다.	`500`, `1200`
`total_tokens`	integer, null	입력 토큰과 출력 토큰의 합계입니다.	`2000`, `4400`
`ephemeral_5m_input_tokens`	integer, null	5분 동안 캐시된 입력 토큰입니다.	`100`, `250`
`ephemeral_1h_input_tokens`	integer, null	1시간 동안 캐시된 입력 토큰입니다.	`500`, `1000`
`cache_read`	integer, null	캐시 읽기 작업입니다.	`2`, `5`

완전한 계측 예시#

다음은 Standard Context 필드와 AI Context 필드를 모두 사용해 DAP 이벤트를 계측하는 전체 예시입니다.

track_internal_event(
  "request_duo_workflow_success",
  user: user,
  project: project,
  namespace: namespace,

  additional_properties: {
    # AI Context fields
    # Session and workflow identifiers
    session_id: session.id,
    workflow_id: session.id + instance.id,

    # Flow and agent information
    agent_name: "code_generator",
    flow_name: "chat",
    component_name: "AgentComponent",
    custom_item_id: nil,
    item_type: "foundational_agent",
    item_version: "2.1.0",
    item_schema_version: "v1",

    # Deprecated flow and agent information
    agent_type: "foundational",
    flow_type: "chat",
    flow_registry_version: "v1",
    flow_version: "2.1.0",

    # Model information (AI Context)
    model_provider: "anthropic",
    model_engine: "claude-3-5",
    model_name: "claude-3-5-sonnet-20241022",
    # Token tracking (AI Context)
    input_tokens: 1500,
    output_tokens: 800,
    total_tokens: 2300,
    ephemeral_5m_input_tokens: 500,
    ephemeral_1h_input_tokens: 1000,
    cache_read: 200
  }
)

AI Gateway 트리거 이벤트와 계측 패턴에 대한 추가 정보는 AI Gateway 계측 문서를 참고합니다.

세션 수준 이벤트#

다음 이벤트는 DAP 세션의 수명 주기를 보여 주며, 대부분의 플로에서 추적해야 합니다.

이벤트 액션	목적	실행 시점	필요한 컨텍스트
`request_duo_workflow` AND `receive_start_duo_workflow`	세션 시작	사용자가 새 플로 세션을 시작할 때	Standard + AI Context
`request_duo_workflow_success`	성공적 완료	플로가 성공적으로 완료될 때	Standard + AI Context
`request_duo_workflow_failure`	치명적 오류	시스템 장애가 발생할 때	Standard + AI Context
`request_duo_workflow_aborted`	연결 실패	연결 문제가 발생할 때	Standard + AI Context
`cleanup_stuck_agent_platform_session`	멈춘 세션 정리	세션 정리가 필요할 때	Standard + AI Context
`pause_duo_workflow`	플로 일시 중지	입력을 위해 일시 중지될 때	Standard + AI Context
`resume_duo_workflow`	플로 재개	승인이나 입력 후 일시 중지된 플로가 재개될 때	Standard + AI Context
`duo_workflow_tool_success`	도구 실행 성공	개별 도구가 완료될 때	Standard + AI Context
`duo_workflow_tool_failure`	도구 실행 실패	개별 도구가 실패할 때	Standard + AI Context
`token_usage_*`	토큰 소비	LLM 상호작용이 발생할 때	AI Context (token fields)
`request_'unit_primitive'`	사용자 접근 관리	사용자가 AI 서비스 접근 권한을 얻을 때	Standard Context

필드 세부 사항 및 모범 사례#

세션 및 워크플로 식별자#

session_id

특정 GitLab 인스턴스 안에서 사용자 세션을 식별하는 로컬 식별자입니다
인스턴스가 생성합니다
서로 다른 인스턴스 사이에서 전역적으로 고유하지 않습니다
로컬 세션 추적과 상관 분석에 사용합니다

토큰 추적 모범 사례#

AI Context에서 토큰 사용량을 추적할 때는 다음을 따릅니다.

AI 모델 상호작용을 추적할 때는 항상 total_tokens를 포함합니다
정확한 청구를 위해 입력 토큰과 출력 토큰을 따로 추적합니다
캐시 효과를 모니터링하기 위해 캐시 사용량(cache_read, ephemeral_5m_input_tokens, ephemeral_1h_input_tokens)을 기록합니다
모델별 분석이 가능하도록 AI Context에 모델 정보(model_provider, model_engine, model_name)를 포함합니다

청구 및 귀속#

올바른 청구와 고객 귀속을 위해 다음을 따릅니다.

correlation_id(Standard Context)를 포함합니다 - DAP 이벤트를 청구 대상 이벤트와 결합하는 데 반드시 필요합니다
ultimate_parent_namespace_id(Standard Context)를 포함합니다 - 고객 귀속이 사용량 청구와 일치하도록 보장합니다
feature_enabled_by_namespace_ids(Standard Context)를 포함합니다 - AI 데이터 모델에서 현재 사용하는 고객 귀속 방법입니다

AI Context에 필드 추가#

대부분의 AI 이벤트가 공통으로 가지는 새 속성을 추적하려면 AI Context에 새 필드를 추가할 수 있습니다.

AI Context에 새 필드를 추가하려면 다음과 같이 합니다.

iglu 리포지터리에 스키마를 업데이트하는 머지 리퀘스트를 생성합니다.
새 필드를 가명 처리해야 한다면 snowplow-pseudonymization 프로젝트의 적절한 가명 처리 구성에 추가합니다.
새 필드를 지원하도록 GitLab 코드베이스의 AI Context 구현을 업데이트합니다.
AI Context에 새 필드를 포함한 이벤트 전송을 시작합니다.
새 필드를 설명하도록 이 문서를 업데이트합니다.

AI 이벤트 계측 가이드

개요#

이 가이드를 사용하는 경우#

AI Context 필드#

세션 및 워크플로 식별자#

워크플로 및 에이전트 정보#

모델 정보#

토큰 추적#

완전한 계측 예시#

세션 수준 이벤트#

필드 세부 사항 및 모범 사례#

세션 및 워크플로 식별자#

토큰 추적 모범 사례#

청구 및 귀속#

AI Context에 필드 추가#

관련 문서#

AI 이벤트 계측 가이드

개요#

이 가이드를 사용하는 경우#

AI Context 필드#

세션 및 워크플로 식별자#

워크플로 및 에이전트 정보#

모델 정보#

토큰 추적#

완전한 계측 예시#

세션 수준 이벤트#

필드 세부 사항 및 모범 사례#

세션 및 워크플로 식별자#

토큰 추적 모범 사례#

청구 및 귀속#

AI Context에 필드 추가#

관련 문서#