GitLab Duo Agent Platform 관측 가능성(Rails)
GitLab v19.6요약
GitLab Duo Agent Platform(이전 명칭 GitLab Duo Workflow Service)은 GitLab Rails 모놀리스에서 다음 모니터링 및 관측 가능성 계측을 사용합니다. 세 메트릭은 모두 AuditEvents::AiAuditEvents::WriteService (ee/app/services/audit_events/ai_audit_events/write_service.rb)에 있으며 AI 감사 이벤트 저장만 추적합니다.
GitLab Duo Agent Platform(이전 명칭 GitLab Duo Workflow Service)은 GitLab Rails 모놀리스에서 다음 모니터링 및 관측 가능성 계측을 사용합니다. Workhorse 측 계측은 다루지 않습니다.
Prometheus 메트릭#
기존 메트릭#
세 메트릭은 모두 AuditEvents::AiAuditEvents::WriteService
(ee/app/services/audit_events/ai_audit_events/write_service.rb)에 있으며
AI 감사 이벤트 저장만 추적합니다.
| 메트릭 이름 | 유형 | 레이블 | 추적 대상 |
|---|---|---|---|
gitlab_ai_audit_events_buffered_total |
Counter | 없음 | ClickHouse Redis 쓰기 버퍼에 큐잉된 AI 감사 이벤트 |
gitlab_ai_audit_events_pg_fallback_total |
Counter | 없음 | ClickHouse를 사용할 수 없을 때 PostgreSQL에 저장된 AI 감사 이벤트 |
gitlab_ai_audit_events_stored_total |
Counter | store: :postgresql |
PostgreSQL에 영구적으로 기록된 AI 감사 이벤트 |
누락된 메트릭(해결할 격차)#
다음은 Prometheus가 다루지 않는 중요한 신호입니다. 일부 신호에는 내부 이벤트가 있지만, 이는 알림이나 대시보드가 아니라 분석 파이프라인에 사용됩니다.
| 신호 | 제안하는 메트릭 이름 | 유형 | 제안하는 레이블 |
|---|---|---|---|
| 세션 수명 주기 전환(생성, 시작, 완료, 중지, 중단, 재개) | gitlab_duo_agent_platform_sessions_total |
Counter | status |
| 크론이 정리한 멈춘 세션 | gitlab_duo_agent_platform_stuck_sessions_total |
Counter | 없음 |
| 워크플로 실행 시작, 완료, 재시도 | gitlab_duo_agent_platform_workflow_executions_total |
Counter | event (start, finish, retry) |
| CI 워크로드 파이프라인 완료 | gitlab_duo_agent_platform_workload_pipelines_total |
Counter | status, workflow_definition |
| CI 워크로드 파이프라인 소요 시간 | gitlab_duo_agent_platform_workload_pipeline_duration_seconds |
Histogram | status, workflow_definition |
| Model Context Protocol(MCP) 도구 호출 시작 및 완료 | gitlab_duo_agent_platform_mcp_tool_calls_total |
Counter | tool_name, success |
| MCP 도구 호출 소요 시간 | gitlab_duo_agent_platform_mcp_tool_call_duration_seconds |
Histogram | tool_name |
| GitLab Duo Workflow Service에 대한 gRPC 호출(지연 시간 및 오류) | gitlab_duo_workflow_service_grpc_requests_total 및 gitlab_duo_workflow_service_grpc_request_duration_seconds |
Counter 및 Histogram | method, status |
POST /ai/duo_workflows/direct_access 속도 제한 도달 |
gitlab_duo_agent_platform_rate_limit_hits_total |
Counter | endpoint |
| 취약점 워크플로 트리거 | gitlab_duo_agent_platform_vulnerability_workflow_triggers_total |
Counter | workflow_definition |
GraphQL duoWorkflowWorkflows 쿼리 호출(실행기 폴링) |
gitlab_duo_agent_platform_graphql_workflow_queries_total |
Counter | status (success, error) |
GraphQL toolCallApproved 필드 해석 |
gitlab_duo_agent_platform_tool_call_approved_checks_total |
Counter | approved (true/false) |
GraphQL WorkflowEventsUpdated 구독 연결 |
gitlab_duo_agent_platform_graphql_subscriptions_total |
Counter | event (subscribe, unsubscribe) |
GraphQL 뮤테이션(create, deleteWorkflow, updateAgentPrivileges, updateToolCallApprovals) |
gitlab_duo_agent_platform_graphql_mutations_total |
Counter | mutation, status |
내부 이벤트(GitLab Analytics / Snowplow)#
이 이벤트는 제품 분석에 사용되며 알림이나 서비스 수준 목표(SLO)에는 적합하지 않습니다.
모든 이벤트 정의는 ee/config/events/ 아래에 있습니다.
세션 수명 주기#
모두 label(플로 유형, 예: chat), property(환경, 예: web),
value(세션 ID)를 가집니다. 식별자는 user, project, namespace입니다.
| 이벤트 | 트리거 위치 | 추적 대상 |
|---|---|---|
agent_platform_session_created |
WorkflowEventTracking concern |
세션 레코드 생성 |
agent_platform_session_started |
WorkflowEventTracking concern |
실행기가 세션 시작 |
agent_platform_session_finished |
WorkflowEventTracking concern |
세션이 정상적으로 완료됨 |
agent_platform_session_stopped |
WorkflowEventTracking concern |
사용자가 세션 중지 |
agent_platform_session_dropped |
WorkflowEventTracking concern |
오류로 세션 중단 |
agent_platform_session_resumed |
WorkflowEventTracking concern |
일시 중지 후 세션 재개 |
agent_platform_session_input_required |
WorkflowEventTracking concern |
사용자 입력을 기다리기 위해 세션 일시 중지. 채팅 또는 대화형 Duo CLI 세션(ACP 포함)에는 전송되지 않음 |
cleanup_stuck_agent_platform_session |
CleanStuckWorkflowsService |
크론이 멈춘 세션 정리. property = 새 상태 |
워크플로 실행#
label(워크플로 유형), property(요청 ID), workflow_id를 가집니다. 식별자는 user입니다.
| 이벤트 | 트리거 위치 | 추적 대상 |
|---|---|---|
start_duo_workflow_execution |
WorkflowEventTracking concern |
워크플로 실행 시작 |
finish_duo_workflow_execution |
WorkflowEventTracking concern |
워크플로 실행 완료 |
retry_duo_workflow_execution |
WorkflowEventTracking concern |
워크플로 재시도 |
CI 워크로드 완료#
WorkloadMetrics concern
(ee/app/services/ai/duo_workflows/concerns/workload_metrics.rb)에서 발생하며
UpdateWorkflowStatusEventWorker가 트리거합니다. 추가 트래커
(Gitlab::Tracking::AiTracking)도 있습니다.
| 이벤트 | 추가 속성 | 추적 대상 |
|---|---|---|
duo_workflow_workload_completed |
label = 파이프라인 상태, property = 빌드 실패 사유, value = 파이프라인 소요 시간(초), workflow_id, workflow_definition |
워크로드의 CI 파이프라인 완료(성공 또는 실패) |
MCP 도구 호출#
tool_name, request_id, mcp_client_name, mcp_client_version을 가집니다. 식별자는 user, namespace입니다.
추가 트래커(Gitlab::Tracking::AiTracking)도 있으며, 이 트래커는 MCP 클라이언트 필드를 저장하지 않습니다.
| 이벤트 | 추가 속성 | 추적 대상 |
|---|---|---|
start_mcp_tool_call |
없음 | MCP 도구 호출 시작 |
finish_mcp_tool_call |
has_tool_call_success, failure_reason, error_status, dispatched_tool_name |
MCP 도구 호출 완료. dispatched_tool_name은 집계된 도구에만 설정됩니다. |
MCP 연결 실패#
요청이 도구 디스패치에 도달하기 전에 발생하므로 실패한 연결이 도구 호출 옆에 나타납니다.
두 이벤트 모두 mcp_client_name과 mcp_client_version을 가지며, 알려진 경우 oauth_application_id도 가집니다.
| 이벤트 | 식별자 | 추가 속성 | 추적 대상 |
|---|---|---|---|
register_oauth_dynamic_application |
없음 | response_status |
성공과 실패 모두에서 OAuth 동적 클라이언트 등록(POST /oauth/register). 클라이언트 필드는 User-Agent에서 가져옵니다. |
deny_mcp_server_access |
user |
denial_reason |
MCP 서버를 사용자가 사용할 수 없어 MCP 요청이 거부됨. mcp.log의 permission_denied 줄과 일치합니다. |
취약점 워크플로 트리거#
워크플로 정의가 알려진 취약점 워크플로와 일치할 때만
Workflows#track_event
(ee/lib/api/ai/duo_workflows/workflows.rb)에서 발생합니다.
| 이벤트 | 워크플로 정의 | 추적 대상 |
|---|---|---|
trigger_sast_vulnerability_fp_detection_workflow |
정적 애플리케이션 보안 테스트(SAST) FP 탐지 | SAST 오탐 탐지 워크플로 트리거됨 |
trigger_sast_vulnerability_resolution_workflow |
SAST 해결 | SAST 해결 워크플로 트리거됨 |
trigger_secret_detection_vulnerability_fp_detection_workflow |
시크릿 탐지 FP | 시크릿 탐지 오탐 워크플로 트리거됨 |
GraphQL API#
duoWorkflowWorkflows 필드는 루트 쿼리 유형과
ProjectType 모두에 노출됩니다.
duoWorkflowWorkflows 필드는 GitLab Duo Workflow Service 실행기가 매 실행 주기마다 세션 상태를 폴링하는 데 사용하는 기본 인터페이스입니다.
GraphQL 계층에는 관측 가능성 계측이 없습니다. 이 영역의 리졸버, 유형, 뮤테이션, 구독 어디에도 Prometheus 메트릭, 내부 이벤트, 오류 추적, 구조화된 로깅이 없습니다.
쿼리#
| 필드 | 노출 위치 | 반환 값 |
|---|---|---|
duoWorkflowWorkflows |
루트 쿼리 및 ProjectType |
workflowId, projectPath, projectId, type, environment, statusGroup 등으로 필터링한 세션 목록 |
실행기가 각 폴링 주기에 가져오는 주요 필드는 다음과 같습니다. statusName, projectId,
project(언어, URL, 컨텍스트 제외 설정), namespaceId,
namespace(promptInjectionProtectionLevel을 포함한 AI 설정),
agentPrivilegesNames, preApprovedAgentPrivilegesNames, mcpEnabled,
allowAgentToRequestUser, latestCheckpoint(GitLab 19.0에서
compressedCheckpoint 사용 가능), archived, stalled.
필드 리졸버#
| 필드 | 기능 |
|---|---|
toolCallApproved(toolName, toolCallArgs) |
특정 도구 호출이 세션에서 승인되었는지 확인합니다. 모든 도구 호출 시 호출됩니다 |
auditEvents |
세션의 AI 감사 이벤트를 반환합니다. read_agent_artifacts 권한(GitLab 19.0 이상)으로 제어됩니다 |
뮤테이션#
| 뮤테이션 | 기능 |
|---|---|
duoWorkflowsCreate |
새 워크플로 세션을 생성합니다 |
duoWorkflowsDeleteWorkflow |
워크플로 세션을 삭제합니다 |
duoWorkflowsUpdateAgentPrivileges |
세션의 에이전트 권한 부여를 업데이트합니다 |
duoWorkflowsUpdateToolCallApprovals |
세션별 도구 호출 승인 정책을 업데이트합니다 |
구독#
| 구독 | 기능 |
|---|---|
duoWorkflowsWorkflowEventsUpdated |
워크플로 소유자에게 실시간 체크포인트 이벤트를 스트리밍합니다. 세션 소유자로 제한됩니다(컴플라이언스 검토자는 제외) |
오류 추적(Sentry)#
Gitlab::ErrorTracking.track_exception은 다음에서 워크플로 컨텍스트와 함께 호출됩니다.
CreateWorkflowService: 워크플로 생성 실패DestroyWorkflowService: 워크플로 삭제 실패GenerateWorkflowTitleService: 제목 생성 실패(workflow_id첨부)SummarizeWorkflowService: 요약 생성 실패(workflow_id첨부)UpdateToolCallApprovalsService: 도구 호출 승인 업데이트 실패(workflow_id첨부)Otel::CreateWorkflowService: OpenTelemetry(OTel) 워크플로 생성 실패(workflow_id첨부)CodeReview::ReviewMergeRequestService: 코드 리뷰 시작 실패(unit_primitive첨부)CancelAssociatedPipelinesWorker: 파이프라인 취소 실패
속도 제한#
두 엔드포인트는 같은 리미터 키를 공유합니다.
| 엔드포인트 | 리미터 키 | 임계값 | 범위 |
|---|---|---|---|
POST /api/v4/ai/duo_workflows/direct_access |
duo_workflow_direct_access |
50 req/min | 사용자별 |
GET /api/v4/ai/duo_workflows/list_tools |
duo_workflow_direct_access |
50 req/min | 사용자별 |
제한을 위반하면 Retry-After 헤더와 함께 HTTP 429가 반환됩니다.
속도 제한 도달을 추적하는 전용 Prometheus 카운터는 없습니다(위의 격차 섹션 참고).
감사 이벤트#
IngestAuditEventsService는 gRPC를 사용해 GitLab Duo Workflow Service에서
이벤트를 받아 일괄 처리하고 ProcessAuditEventsWorker를 큐에 추가합니다.
프로젝트나 네임스페이스에서 AI 감사 이벤트 저장이 꺼져 있고 조직에서 스트리밍이 꺼져 있으면
서비스는 워커를 큐에 추가하지 않습니다. 워커는
AuditEvents::AiAuditEvents::WriteService를 호출하며, 이 서비스는 다음을 수행합니다.
- Redis 쓰기 버퍼를 사용해 ClickHouse에 씁니다(우선 경로).
- ClickHouse를 사용할 수 없으면 PostgreSQL 대량 삽입으로 대체합니다.
- 구성된 감사 이벤트 대상으로 각 이벤트를 스트리밍합니다.
- 각 이벤트를
Gitlab::AuditJsonLogger에 기록합니다.
(cloud_event_id, created_at)의 고유 인덱스가 멱등성을 보장합니다.
주요 소스 파일#
| 파일 | 역할 |
|---|---|
ee/app/services/audit_events/ai_audit_events/write_service.rb |
Prometheus 카운터가 있는 유일한 파일 |
ee/app/services/ai/duo_workflows/concerns/workload_metrics.rb |
duo_workflow_workload_completed 내부 이벤트 |
ee/app/services/ai/duo_workflows/concerns/workflow_event_tracking.rb |
세션 및 실행 내부 이벤트 |
ee/app/services/ai/duo_workflows/code_review/observability.rb |
코드 리뷰 오류 추적 및 조건부 로깅 |
ee/app/workers/ai/duo_workflows/update_workflow_status_event_worker.rb |
CI 파이프라인 완료 시 워크로드 메트릭을 트리거합니다 |
ee/lib/api/ai/duo_workflows/workflows.rb |
공개 API. 속도 제한 및 취약점 워크플로 이벤트 추적 |
ee/lib/api/ai/duo_workflows/workflows_internal.rb |
GitLab Duo Workflow Service와 실행기가 사용하는 내부 API |
ee/lib/ee/gitlab/application_rate_limiter.rb |
duo_workflow_direct_access 속도 제한 정의(50 req/min) |
ee/config/events/ |
내부 이벤트 정의(agent_platform_session_*, duo_workflow_*, *_mcp_tool_call) |