Przejdź do głównej treści
OpenClaw może udostępniać metryki diagnostyczne przez oficjalną wtyczkę diagnostics-prometheus. Nasłuchuje zaufanej diagnostyki oraz emitowanych przez rdzeń zdarzeń stabilności Gateway, a następnie renderuje tekstowy punkt końcowy Prometheus pod adresem: 
GET /api/diagnostics/prometheus
Typ zawartości to text/plain; version=0.0.4; charset=utf-8, standardowy format ekspozycji Prometheus.
Trasa używa uwierzytelniania Gateway (zakres operatora). Nie udostępniaj jej jako publicznego, nieuwierzytelnionego punktu końcowego /metrics. Pobieraj z niej metryki przez tę samą ścieżkę uwierzytelniania, której używasz dla innych interfejsów API operatora.
Informacje o śladach, logach, wypychaniu OTLP i atrybutach semantycznych OpenTelemetry GenAI znajdziesz w sekcji eksport OpenTelemetry.

​
Szybki start

1

Zainstaluj wtyczkę

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

Włącz wtyczkę

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

Uruchom ponownie Gateway

Trasa HTTP jest rejestrowana podczas uruchamiania wtyczki, więc po włączeniu wykonaj ponowne wczytanie.
4

Pobieraj metryki z chronionej trasy

Wyślij to samo uwierzytelnianie Gateway, którego używają klienci operatora:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Podłącz 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"]
Wymagane jest diagnostics.enabled: true. Bez tego Plugin nadal rejestruje trasę HTTP, ale żadne zdarzenia diagnostyczne nie trafiają do eksportera, więc odpowiedź jest pusta.

​
Eksportowane metryki

MetrykaTypEtykiety
openclaw_run_completed_totallicznikchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totallicznikapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totallicznikfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totallicznikagent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totallicznikagent, channel, model, provider
openclaw_skill_used_totallicznikactivation, agent, skill, source
openclaw_tool_execution_totallicznikerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totallicznikdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totallicznikchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totallicznikchannel, webhook
openclaw_webhook_error_totallicznikchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totallicznikchannel, source
openclaw_message_dispatch_started_totallicznikchannel, source
openclaw_message_dispatch_completed_totallicznikchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
openclaw_message_processed_totallicznikchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totallicznikchannel, delivery_kind
openclaw_message_delivery_totallicznikchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totallicznikbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizemierniklane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totallicznikreason, state
openclaw_session_queue_depthmiernikstate
openclaw_session_turn_created_totallicznikagent, channel, trigger
openclaw_session_stuck_totallicznikreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totallicznikaction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totallicznikreason
openclaw_liveness_sessionsmiernikstate
openclaw_liveness_event_loop_delay_p99_secondshistogramreason
openclaw_liveness_event_loop_delay_max_secondshistogramreason
openclaw_liveness_event_loop_utilization_ratiohistogramreason
openclaw_liveness_cpu_core_ratiohistogramreason
openclaw_payload_large_totallicznikaction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesmiernikkind
openclaw_memory_rss_byteshistogrambrak
openclaw_memory_pressure_totalliczniklevel, reason
openclaw_telemetry_exporter_totallicznikexporter, reason, signal, status
openclaw_prometheus_series_dropped_totallicznikbrak

​
Zasady etykiet

Etykiety Prometheus pozostają ograniczone i mają niską kardynalność. Eksporter nie emituje surowych identyfikatorów diagnostycznych, takich jak runId, sessionKey, sessionId, callId, toolCallId, identyfikatory wiadomości, identyfikatory czatów ani identyfikatory żądań dostawcy.Wartości etykiet są redagowane i muszą być zgodne z polityką znaków o niskiej kardynalności OpenClaw. Wartości, które nie spełniają tej polityki, są zastępowane przez unknown, other albo none, zależnie od metryki. Etykiety wyglądające jak zakresowe klucze sesji agenta również są zastępowane przez unknown.
Eksporter ogranicza przechowywane w pamięci szeregi czasowe do 2048 serii łącznie dla liczników, mierników i histogramów. Nowe serie ponad ten limit są odrzucane, a openclaw_prometheus_series_dropped_total jest zwiększane o jeden za każdym razem.Obserwuj ten licznik jako jednoznaczny sygnał, że atrybut wyżej w potoku przepuszcza wartości o wysokiej kardynalności. Eksporter nigdy nie podnosi limitu automatycznie; jeśli licznik rośnie, napraw źródło zamiast wyłączać limit.
  • tekst promptu, tekst odpowiedzi, dane wejściowe narzędzi, dane wyjściowe narzędzi, prompty systemowe
  • transkrypcje rozmów, ładunki audio, identyfikatory połączeń, identyfikatory pokojów, tokeny przekazania, identyfikatory tur i surowe identyfikatory sesji
  • surowe identyfikatory żądań dostawcy (tylko ograniczone skróty, tam gdzie ma to zastosowanie, w spanach — nigdy w metrykach)
  • klucze sesji i identyfikatory sesji
  • nazwy hostów, ścieżki plików, wartości sekretów

​
Przykłady 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

# Skill usage, split by bounded source
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Preferuj gen_ai_client_token_usage w panelach między dostawcami: jest zgodne z konwencjami semantycznymi OpenTelemetry GenAI i spójne z metrykami z usług GenAI innych niż OpenClaw.

​
Wybór między eksportem Prometheus a OpenTelemetry

OpenClaw obsługuje oba interfejsy niezależnie. Możesz uruchomić jeden z nich, oba albo żaden.
  • Model pull: Prometheus odpytuje /api/diagnostics/prometheus.
  • Nie wymaga zewnętrznego kolektora.
  • Uwierzytelnianie odbywa się przez standardowe uwierzytelnianie Gateway.
  • Interfejs obejmuje tylko metryki (bez trace’ów ani logów).
  • Najlepsze dla stosów już zestandaryzowanych na Prometheus + Grafana.

​
Rozwiązywanie problemów

  • Sprawdź diagnostics.enabled: true w konfiguracji.
  • Potwierdź, że Plugin jest włączony i załadowany za pomocą openclaw plugins list --enabled.
  • Wygeneruj trochę ruchu; liczniki i histogramy emitują wiersze dopiero po co najmniej jednym zdarzeniu.
Punkt końcowy wymaga zakresu operatora Gateway (auth: "gateway" z gatewayRuntimeScopeSurface: "trusted-operator"). Użyj tego samego tokenu lub hasła, którego Prometheus używa dla dowolnej innej trasy operatora Gateway. Nie ma publicznego trybu bez uwierzytelniania.
Nowy atrybut przekracza limit 2048 serii. Sprawdź ostatnie metryki pod kątem etykiety o nieoczekiwanie wysokiej kardynalności i napraw ją u źródła. Eksporter celowo odrzuca nowe serie zamiast po cichu przepisywać etykiety.
Plugin przechowuje stan wyłącznie w pamięci. Po restarcie Gateway liczniki resetują się do zera, a mierniki wznawiają działanie od następnej zgłoszonej wartości. Użyj PromQL rate() i increase(), aby czysto obsłużyć resety.

​
Powiązane