메인 콘텐츠로 건너뛰기
OpenClaw는 번들된 diagnostics-prometheus Plugin을 통해 진단 메트릭을 노출할 수 있습니다. 이 Plugin은 신뢰된 내부 진단을 수신하고 다음 위치에 Prometheus 텍스트 엔드포인트를 렌더링합니다. 
GET /api/diagnostics/prometheus
Content type은 표준 Prometheus exposition 형식인 text/plain; version=0.0.4; charset=utf-8입니다.
이 경로는 Gateway 인증(operator 범위)을 사용합니다. 이를 공개된 인증 없는 /metrics 엔드포인트로 노출하지 마세요. 다른 operator API에 사용하는 것과 동일한 인증 경로를 통해 스크레이프하세요.
트레이스, 로그, OTLP push, OpenTelemetry GenAI semantic attribute는 OpenTelemetry export를 참고하세요.

​
빠른 시작

1

Plugin 활성화

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

Gateway 재시작

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

보호된 경로 스크레이프

operator 클라이언트가 사용하는 것과 동일한 gateway 인증을 전송하세요.
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
4

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 경로를 등록하더라도 exporter로 진단 이벤트가 흐르지 않으므로 응답이 비어 있습니다.

​
내보내는 메트릭

메트릭유형라벨
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogram없음
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounter없음

​
라벨 정책

Prometheus 라벨은 제한되고 낮은 카디널리티를 유지합니다. exporter는 runId, sessionKey, sessionId, callId, toolCallId, 메시지 ID, chat ID, provider 요청 ID 같은 원시 진단 식별자를 내보내지 않습니다.라벨 값은 마스킹되며 OpenClaw의 낮은 카디널리티 문자 정책과 일치해야 합니다. 정책을 통과하지 못하는 값은 메트릭에 따라 unknown, other, none으로 대체됩니다.
exporter는 counter, gauge, histogram을 모두 합쳐 메모리에 유지되는 시계열을 2048개로 제한합니다. 이 상한을 넘는 새 시리즈는 버려지며, 그때마다 openclaw_prometheus_series_dropped_total이 1씩 증가합니다.이 counter를 업스트림 attribute에서 높은 카디널리티 값이 새고 있다는 강한 신호로 관찰하세요. exporter는 상한을 자동으로 높이지 않습니다. 값이 증가한다면 상한을 끄는 대신 원인을 수정하세요.
  • 프롬프트 텍스트, 응답 텍스트, 도구 입력, 도구 출력, system prompt
  • 원시 provider 요청 ID(해당하는 경우 span에는 제한된 해시만 존재할 수 있으나, 메트릭에는 절대 없음)
  • 세션 키와 세션 ID
  • 호스트 이름, 파일 경로, 비밀 값

​
PromQL 예시

# 분당 토큰 수, provider별 분리
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# 지난 1시간 동안의 비용(USD), model별
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 (95p가 2초 미만)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# 버려진 Prometheus 시리즈(카디널리티 경보)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
교차-provider 대시보드에는 gen_ai_client_token_usage를 우선 사용하세요. 이 메트릭은 OpenTelemetry GenAI semantic convention을 따르며, OpenClaw가 아닌 다른 GenAI 서비스의 메트릭과도 일관됩니다.

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

OpenClaw는 두 표면을 독립적으로 모두 지원합니다. 둘 중 하나만 실행해도 되고, 둘 다 실행해도 되고, 둘 다 실행하지 않아도 됩니다.
  • Pull 모델: Prometheus가 /api/diagnostics/prometheus를 스크레이프합니다.
  • 외부 collector가 필요 없습니다.
  • 일반 Gateway 인증을 통해 인증됩니다.
  • 표면은 메트릭만 포함합니다(트레이스 또는 로그 없음).
  • 이미 Prometheus + Grafana를 표준으로 사용하는 스택에 가장 적합합니다.

​
문제 해결

  • config에서 diagnostics.enabled: true를 확인하세요.
  • openclaw plugins list --enabled로 Plugin이 활성화되어 로드되었는지 확인하세요.
  • 약간의 트래픽을 발생시키세요. counter와 histogram은 적어도 한 번 이벤트가 발생한 뒤에만 라인을 출력합니다.
이 엔드포인트는 Gateway operator 범위(auth: "gateway", gatewayRuntimeScopeSurface: "trusted-operator")를 요구합니다. Prometheus가 다른 Gateway operator 경로에 사용하는 것과 동일한 token 또는 password를 사용하세요. 공개 무인증 모드는 없습니다.
새 attribute가 2048 시리즈 상한을 초과하고 있습니다. 최근 메트릭에서 예상보다 카디널리티가 높은 라벨을 찾아 소스에서 수정하세요. exporter는 라벨을 조용히 재작성하는 대신 의도적으로 새 시리즈를 버립니다.
Plugin은 상태를 메모리에만 유지합니다. Gateway 재시작 후 counter는 0으로 재설정되고 gauge는 다음 보고 값에서 다시 시작합니다. 재설정을 깔끔하게 처리하려면 PromQL의 rate()와 increase()를 사용하세요.

​
관련 항목