메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw은 공식 diagnostics-prometheus Plugin을 통해 진단 메트릭을 노출할 수 있습니다. 신뢰할 수 있는 내부 진단을 수신하고 다음 위치에 Prometheus 텍스트 엔드포인트를 렌더링합니다: 
GET /api/diagnostics/prometheus
콘텐츠 유형은 표준 Prometheus 노출 형식인 text/plain; version=0.0.4; charset=utf-8입니다.
이 라우트는 Gateway 인증(운영자 범위)을 사용합니다. 공개 무인증 /metrics 엔드포인트로 노출하지 마세요. 다른 운영자 API에 사용하는 것과 동일한 인증 경로를 통해 스크레이프하세요.
트레이스, 로그, OTLP 푸시, OpenTelemetry GenAI 시맨틱 속성은 OpenTelemetry 내보내기를 참고하세요.

​
빠른 시작

1

Plugin 설치

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
2

Plugin 활성화

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

Gateway 다시 시작

HTTP 라우트는 Plugin 시작 시 등록되므로 활성화한 뒤 다시 로드하세요.
4

보호된 라우트 스크레이프

운영자 클라이언트가 사용하는 것과 동일한 Gateway 인증을 보내세요:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

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가 필요합니다. 이 값이 없으면 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_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_tool_execution_total카운터error_category, outcome, params_kind, tool
openclaw_tool_execution_duration_seconds히스토그램error_category, outcome, params_kind, tool
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_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_recovery_total카운터action, active_work_kind, state, status
openclaw_session_recovery_age_seconds히스토그램action, active_work_kind, state, status
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카운터없음

​
레이블 정책

Prometheus 레이블은 제한되고 저카디널리티를 유지합니다. 내보내기는 runId, sessionKey, sessionId, callId, toolCallId, 메시지 ID, 채팅 ID 또는 제공자 요청 ID 같은 원시 진단 식별자를 내보내지 않습니다.레이블 값은 수정되어 표시되며 OpenClaw의 저카디널리티 문자 정책과 일치해야 합니다. 정책을 통과하지 못하는 값은 메트릭에 따라 unknown, other 또는 none으로 대체됩니다.
exporter는 메모리에 보존되는 시계열을 카운터, 게이지, 히스토그램을 합쳐 2048개 시리즈로 제한합니다. 이 한도를 넘는 새 시리즈는 삭제되며, 그때마다 openclaw_prometheus_series_dropped_total이 1씩 증가합니다.이 카운터를 상위 속성에서 높은 카디널리티 값이 누출되고 있다는 강한 신호로 관찰하세요. exporter는 한도를 자동으로 올리지 않습니다. 값이 증가하면 한도를 비활성화하지 말고 원인을 수정하세요.
  • 프롬프트 텍스트, 응답 텍스트, 도구 입력, 도구 출력, 시스템 프롬프트
  • Talk 대화 기록, 오디오 페이로드, 호출 ID, 방 ID, 핸드오프 토큰, 턴 ID, 원시 세션 ID
  • 원시 제공자 요청 ID(해당하는 경우 span에는 제한된 해시만 포함되며, 메트릭에는 절대 포함되지 않음)
  • 세션 키와 세션 ID
  • 호스트 이름, 파일 경로, 비밀 값

​
PromQL 레시피

# Tokens per minute, split by provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spend (USD) over the last hour, by model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95th percentile model run duration
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Queue wait time SLO (95p under 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
교차 제공자 대시보드에는 gen_ai_client_token_usage를 선호하세요. 이는 OpenTelemetry GenAI 의미 체계 규칙을 따르며 OpenClaw가 아닌 GenAI 서비스의 메트릭과도 일관됩니다.

​
Prometheus와 OpenTelemetry 내보내기 중 선택

OpenClaw는 두 인터페이스를 독립적으로 모두 지원합니다. 둘 중 하나를 실행하거나, 둘 다 실행하거나, 둘 다 실행하지 않을 수 있습니다.
  • Pull 모델: Prometheus가 /api/diagnostics/prometheus를 스크레이프합니다.
  • 외부 collector가 필요하지 않습니다.
  • 일반 Gateway 인증을 통해 인증됩니다.
  • 인터페이스는 메트릭 전용입니다(트레이스나 로그 없음).
  • Prometheus + Grafana로 이미 표준화된 스택에 가장 적합합니다.

​
문제 해결

  • config에서 diagnostics.enabled: true를 확인하세요.
  • Plugin이 활성화되어 있고 openclaw plugins list --enabled로 로드되었는지 확인하세요.
  • 트래픽을 생성하세요. 카운터와 히스토그램은 이벤트가 하나 이상 발생한 뒤에만 줄을 내보냅니다.
엔드포인트에는 Gateway operator 범위(auth: "gateway" 및 gatewayRuntimeScopeSurface: "trusted-operator")가 필요합니다. Prometheus가 다른 Gateway operator 경로에 사용하는 것과 동일한 토큰 또는 비밀번호를 사용하세요. 공개 미인증 모드는 없습니다.
새 속성이 2048개 시리즈 한도를 초과하고 있습니다. 최근 메트릭에서 예상치 못하게 카디널리티가 높은 label을 점검하고 원인에서 수정하세요. exporter는 label을 조용히 다시 쓰는 대신 의도적으로 새 시리즈를 삭제합니다.
Plugin은 상태를 메모리에만 보관합니다. Gateway를 재시작하면 카운터는 0으로 재설정되고 게이지는 다음에 보고되는 값에서 다시 시작합니다. 재설정을 깔끔하게 처리하려면 PromQL rate()와 increase()를 사용하세요.

​
관련