Prometheus 메트릭

OpenClaw은 공식 diagnostics-prometheus Plugin을 통해 진단 메트릭을 노출할 수 있습니다. 이 Plugin은 신뢰할 수 있는 진단과 내부적으로 태그가 지정된 디스패처 소유 진단 이벤트(대기열, 메모리 및 세션 복구 신호)를 수신하고 다음 위치에 Prometheus 텍스트 엔드포인트를 제공합니다.

GET /api/diagnostics/prometheus

콘텐츠 유형은 표준 Prometheus 노출 형식인 text/plain; version=0.0.4; charset=utf-8입니다.

이 경로는 Gateway 인증(운영자 범위, 신뢰할 수 있는 운영자용 인터페이스)을 사용합니다. 이 경로를 인증되지 않은 공개 /metrics 엔드포인트로 노출하지 마세요. 다른 운영자 API에 사용하는 것과 동일한 인증 경로를 통해 스크레이핑하세요.

트레이스, 로그, OTLP 푸시 및 OpenTelemetry GenAI 의미 체계 속성에 대해서는 OpenTelemetry 내보내기를 참조하세요.

빠른 시작

Plugin 설치

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

Plugin 활성화

구성
CLI

{
  plugins: {
    allow: ["diagnostics-prometheus"],
    entries: {
      "diagnostics-prometheus": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
  },
}

openclaw plugins enable diagnostics-prometheus

Gateway 다시 시작

HTTP 경로는 Plugin 시작 시 등록되므로 활성화한 후 다시 로드하세요.

보호된 경로 스크레이핑

운영자 클라이언트에서 사용하는 것과 동일한 Gateway 인증을 전송하세요.

curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus

Prometheus 연결

# prometheus.yml
scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]

diagnostics.enabled의 기본값은 true입니다. 엄격히 제한된 환경에서만 false로 설정하세요. 이 값이 false여도 Plugin은 HTTP 경로를 등록하지만 진단 이벤트가 내보내기로 전달되지 않으므로 응답은 비어 있습니다.

내보내는 메트릭

메트릭	유형	레이블
`openclaw_run_completed_total`	카운터	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_run_duration_seconds`	히스토그램	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_model_call_total`	카운터	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_call_duration_seconds`	히스토그램	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_failover_total`	카운터	`from_model`, `from_provider`, `lane`, `reason`, `suspended`, `to_model`, `to_provider`
`openclaw_model_tokens_total`	카운터	`agent`, `channel`, `model`, `provider`, `token_type`
`openclaw_gen_ai_client_token_usage`	히스토그램	`model`, `provider`, `token_type`
`openclaw_model_cost_usd_total`	카운터	`agent`, `channel`, `model`, `provider`
`openclaw_model_usage_duration_seconds`	히스토그램	`agent`, `channel`, `model`, `provider`
`openclaw_skill_used_total`	카운터	`activation`, `agent`, `skill`, `source`
`openclaw_tool_execution_total`	카운터	`error_category`, `outcome`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_tool_execution_duration_seconds`	히스토그램	`error_category`, `outcome`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_tool_execution_blocked_total`	카운터	`denied_reason`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_harness_run_total`	카운터	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_harness_run_duration_seconds`	히스토그램	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_webhook_received_total`	카운터	`channel`, `webhook`
`openclaw_webhook_error_total`	카운터	`channel`, `webhook`
`openclaw_webhook_duration_seconds`	히스토그램	`channel`, `webhook`
`openclaw_message_received_total`	카운터	`channel`, `source`
`openclaw_message_dispatch_started_total`	카운터	`channel`, `source`
`openclaw_message_dispatch_completed_total`	카운터	`channel`, `outcome`, `reason`, `source`
`openclaw_message_dispatch_duration_seconds`	히스토그램	`channel`, `outcome`, `reason`, `source`
`openclaw_message_processed_total`	카운터	`channel`, `outcome`, `reason`
`openclaw_message_processed_duration_seconds`	히스토그램	`channel`, `outcome`, `reason`
`openclaw_message_delivery_started_total`	카운터	`channel`, `delivery_kind`
`openclaw_message_delivery_total`	카운터	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_message_delivery_duration_seconds`	히스토그램	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_talk_event_total`	카운터	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_event_duration_seconds`	히스토그램	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_audio_bytes`	히스토그램	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_queue_lane_size`	게이지	`lane`
`openclaw_queue_lane_wait_seconds`	히스토그램	`lane`
`openclaw_session_state_total`	카운터	`reason`, `state`
`openclaw_session_queue_depth`	게이지	`state`
`openclaw_session_turn_created_total`	카운터	`agent`, `channel`, `trigger`
`openclaw_session_stuck_total`	카운터	`reason`, `state`
`openclaw_session_stuck_age_seconds`	히스토그램	`reason`, `state`
`openclaw_session_recovery_total`	카운터	`action`, `active_work_kind`, `state`, `status`
`openclaw_session_recovery_age_seconds`	히스토그램	`action`, `active_work_kind`, `state`, `status`
`openclaw_liveness_warning_total`	카운터	`reason`
`openclaw_liveness_sessions`	게이지	`state`
`openclaw_liveness_event_loop_delay_p99_seconds`	히스토그램	`reason`
`openclaw_liveness_event_loop_delay_max_seconds`	히스토그램	`reason`
`openclaw_liveness_event_loop_utilization_ratio`	히스토그램	`reason`
`openclaw_liveness_cpu_core_ratio`	히스토그램	`reason`
`openclaw_payload_large_total`	카운터	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_payload_large_bytes`	히스토그램	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_memory_bytes`	게이지	`kind`
`openclaw_memory_rss_bytes`	히스토그램	없음
`openclaw_memory_pressure_total`	카운터	`level`, `reason`
`openclaw_telemetry_exporter_total`	카운터	`exporter`, `reason`, `signal`, `status`
`openclaw_prometheus_series_dropped_total`	카운터	없음
`openclaw_diagnostic_async_queue_dropped_total`	카운터	`drop_class`
`openclaw_diagnostic_async_queue_length`	게이지	없음

레이블 정책

제한된 낮은 카디널리티 레이블

Prometheus 레이블은 제한된 낮은 카디널리티를 유지합니다. 내보내기는 runId, sessionKey, sessionId, callId, toolCallId, 메시지 ID, 채팅 ID 또는 제공자 요청 ID와 같은 원시 진단 식별자를 내보내지 않습니다.레이블 값은 민감 정보가 제거되며 OpenClaw의 낮은 카디널리티 문자 정책과 일치해야 합니다. 정책을 충족하지 못하는 값은 메트릭에 따라 unknown, other 또는 none으로 대체됩니다. 범위가 지정된 에이전트 세션 키처럼 보이는 레이블도 unknown으로 대체됩니다.

시계열 상한 및 초과 집계

내보내기는 카운터, 게이지, 히스토그램을 합쳐 메모리에 유지하는 시계열을 2048개로 제한합니다. 이 상한을 초과하는 새 시계열은 삭제되며, 삭제될 때마다 openclaw_prometheus_series_dropped_total이 1씩 증가합니다.이 카운터를 업스트림 속성에서 높은 카디널리티의 값이 누출되고 있음을 나타내는 확실한 신호로 모니터링하세요. 내보내기는 상한을 자동으로 높이지 않습니다. 값이 증가하면 상한을 비활성화하지 말고 원인을 수정하세요.

Prometheus 출력에 절대 포함되지 않는 항목

프롬프트 텍스트, 응답 텍스트, 도구 입력, 도구 출력, 시스템 프롬프트
대화 기록, 오디오 페이로드, 통화 ID, 방 ID, 핸드오프 토큰, 턴 ID, 원시 세션 ID
원시 제공자 요청 ID(해당하는 경우 범위가 제한된 해시만 스팬에 포함되며 메트릭에는 절대 포함되지 않음)
세션 키 및 세션 ID
호스트 이름, 파일 경로, 비밀 값

PromQL 사용 예시

# 제공자별 분당 토큰 수
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# 최근 1시간 동안의 모델별 지출(USD)
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 모델 실행 시간의 95번째 백분위수
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# 큐 대기 시간 SLO(95번째 백분위수가 2초 미만)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# 제한된 소스별 Skill 사용량
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# 삭제된 Prometheus 시계열(카디널리티 경보)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0

여러 제공자를 아우르는 대시보드에는 gen_ai_client_token_usage를 사용하는 것이 좋습니다. 이 메트릭은 OpenTelemetry GenAI 시맨틱 규칙을 따르며 OpenClaw 이외의 GenAI 서비스에서 제공하는 메트릭과도 일관됩니다.

Prometheus와 OpenTelemetry 내보내기 중 선택하기

OpenClaw는 두 인터페이스를 독립적으로 지원합니다. 둘 중 하나만 사용하거나, 둘 다 사용하거나, 둘 다 사용하지 않을 수 있습니다.

diagnostics-prometheus
diagnostics-otel

풀 모델: Prometheus가 /api/diagnostics/prometheus를 스크레이프합니다.
외부 수집기가 필요하지 않습니다.
일반적인 Gateway 인증을 통해 인증됩니다.
메트릭만 제공합니다(트레이스 또는 로그는 제공하지 않음).
이미 Prometheus + Grafana를 표준으로 사용하는 스택에 가장 적합합니다.

푸시 모델: OpenClaw가 OTLP/HTTP를 통해 수집기 또는 OTLP 호환 백엔드로 전송합니다.
메트릭, 트레이스, 로그를 제공합니다.
둘 다 필요한 경우 OpenTelemetry Collector(prometheus 또는 prometheusremotewrite 내보내기)를 통해 Prometheus와 연동합니다.
전체 목록은 OpenTelemetry 내보내기를 참조하세요.

문제 해결

빈 응답 본문

구성에서 diagnostics.enabled가 false로 설정되어 있지 않은지 확인하세요(기본값은 true).
openclaw plugins list --enabled를 사용하여 Plugin이 활성화되고 로드되었는지 확인하세요.
트래픽을 생성하세요. 카운터와 히스토그램은 이벤트가 하나 이상 발생한 후에만 행을 출력합니다.

401 / 권한 없음

이 엔드포인트에는 Gateway 운영자 범위(gatewayRuntimeScopeSurface: "trusted-operator"가 설정된 auth: "gateway")가 필요합니다. Prometheus가 다른 Gateway 운영자 경로에 사용하는 것과 동일한 토큰 또는 비밀번호를 사용하세요. 인증되지 않은 공개 모드는 없습니다.

`openclaw_prometheus_series_dropped_total`이 증가함

새 속성이 2048개 시계열 상한을 초과하고 있습니다. 최근 메트릭에서 예상보다 카디널리티가 높은 레이블을 찾아 원인을 수정하세요. 내보내기는 레이블을 조용히 다시 작성하는 대신 의도적으로 새 시계열을 삭제합니다.

재시작 후 Prometheus에 오래된 시계열이 표시됨

Plugin은 상태를 메모리에만 유지합니다. Gateway를 재시작하면 카운터는 0으로 초기화되고 게이지는 다음에 보고되는 값부터 다시 시작됩니다. 초기화를 깔끔하게 처리하려면 PromQL rate()와 increase()를 사용하세요.

Gateway

Remote access

Security

Nodes and media

Web interfaces

Prometheus 메트릭

빠른 시작

내보내는 메트릭

레이블 정책

PromQL 사용 예시

Prometheus와 OpenTelemetry 내보내기 중 선택하기

문제 해결

관련 문서

​빠른 시작

​내보내는 메트릭

​레이블 정책

​PromQL 사용 예시

​Prometheus와 OpenTelemetry 내보내기 중 선택하기

​문제 해결

​관련 문서

빠른 시작

내보내는 메트릭

레이블 정책

PromQL 사용 예시

Prometheus와 OpenTelemetry 내보내기 중 선택하기

문제 해결

관련 문서