InfoGrab Docs

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"

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

필드 유형 설명 예시
flow_type string, null DAP 플로우 유형 (향후 더 많은 커스텀 플로우가 포함될 예정). "chat", "software_development", "convert_to_gitlab_ci"
flow_version string, null 플로우에 대한 AI 기능 구현 버전 (최대 길이: 64자). "2.1.0", "3.0.1"
flow_registry_version string, null 플로우를 빌드하는 데 사용된 Flow Registry 프레임워크 버전 (최대 길이: 64자). "1.0.0", "1.1.0"
agent_name string, null 플로우 내에서 실행 중인 에이전트. "duo_chat", "code_agent", "planning_agent"
agent_type string, null 플로우 내에서 실행 중인 에이전트 유형. "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
    flow_type: "software_development",
    flow_version: "2.1.0",
    flow_registry_version: "1.0.0",
    agent_name: "code_generator",
    agent_type: "code_agent",

    # 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에서 토큰 사용량을 추적할 때:

  1. AI 모델 상호작용 추적 시 total_tokens를 항상 포함하세요
  2. 정확한 청구를 위해 입력 및 출력 토큰을 개별적으로 추적하세요
  3. 캐시 효율성을 모니터링하기 위해 캐시 사용량을 기록하세요 (cache_read, ephemeral_5m_input_tokens, ephemeral_1h_input_tokens)
  4. 모델별 분석을 가능하게 하려면 AI Context에 모델 정보를 포함하세요 (model_provider, model_engine, model_name)

청구 및 귀속#

적절한 청구 및 고객 귀속을 위해:

  1. correlation_id 포함 (Standard Context) - DAP 이벤트를 청구 가능한 이벤트와 연결하는 데 중요합니다
  2. billing_event_id 포함 (Standard Context) - 청구 가능한 사용 이벤트에 연결합니다
  3. ultimate_parent_namespace_id 포함 (Standard Context) - 고객 귀속이 사용량 청구와 일치하도록 합니다
  4. feature_enabled_by_namespace_ids 포함 (Standard Context) - AI 데이터 모델에서 고객 귀속을 위한 현재 방법

AI Context에 필드 추가#

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

AI Context에 새 필드를 추가하려면:

  1. iglu 저장소에서 스키마를 업데이트하기 위한 머지 리퀘스트를 만듭니다.
  2. 새 필드를 가명 처리해야 하는 경우, snowplow-pseudonymization 프로젝트의 적절한 가명 처리 구성에 추가합니다.
  3. GitLab 코드베이스에서 새 필드를 지원하도록 AI Context 구현을 업데이트합니다.
  4. AI Context에 새 필드를 포함하는 이벤트 전송을 시작합니다.
  5. 새 필드를 설명하도록 이 설명서를 업데이트합니다.

관련 설명서#

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"

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

필드 유형 설명 예시
flow_type string, null DAP 플로우 유형 (향후 더 많은 커스텀 플로우가 포함될 예정). "chat", "software_development", "convert_to_gitlab_ci"
flow_version string, null 플로우에 대한 AI 기능 구현 버전 (최대 길이: 64자). "2.1.0", "3.0.1"
flow_registry_version string, null 플로우를 빌드하는 데 사용된 Flow Registry 프레임워크 버전 (최대 길이: 64자). "1.0.0", "1.1.0"
agent_name string, null 플로우 내에서 실행 중인 에이전트. "duo_chat", "code_agent", "planning_agent"
agent_type string, null 플로우 내에서 실행 중인 에이전트 유형. "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
    flow_type: "software_development",
    flow_version: "2.1.0",
    flow_registry_version: "1.0.0",
    agent_name: "code_generator",
    agent_type: "code_agent",

    # 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에서 토큰 사용량을 추적할 때:

  1. AI 모델 상호작용 추적 시 total_tokens를 항상 포함하세요
  2. 정확한 청구를 위해 입력 및 출력 토큰을 개별적으로 추적하세요
  3. 캐시 효율성을 모니터링하기 위해 캐시 사용량을 기록하세요 (cache_read, ephemeral_5m_input_tokens, ephemeral_1h_input_tokens)
  4. 모델별 분석을 가능하게 하려면 AI Context에 모델 정보를 포함하세요 (model_provider, model_engine, model_name)

청구 및 귀속#

적절한 청구 및 고객 귀속을 위해:

  1. correlation_id 포함 (Standard Context) - DAP 이벤트를 청구 가능한 이벤트와 연결하는 데 중요합니다
  2. billing_event_id 포함 (Standard Context) - 청구 가능한 사용 이벤트에 연결합니다
  3. ultimate_parent_namespace_id 포함 (Standard Context) - 고객 귀속이 사용량 청구와 일치하도록 합니다
  4. feature_enabled_by_namespace_ids 포함 (Standard Context) - AI 데이터 모델에서 고객 귀속을 위한 현재 방법

AI Context에 필드 추가#

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

AI Context에 새 필드를 추가하려면:

  1. iglu 저장소에서 스키마를 업데이트하기 위한 머지 리퀘스트를 만듭니다.
  2. 새 필드를 가명 처리해야 하는 경우, snowplow-pseudonymization 프로젝트의 적절한 가명 처리 구성에 추가합니다.
  3. GitLab 코드베이스에서 새 필드를 지원하도록 AI Context 구현을 업데이트합니다.
  4. AI Context에 새 필드를 포함하는 이벤트 전송을 시작합니다.
  5. 새 필드를 설명하도록 이 설명서를 업데이트합니다.

관련 설명서#