Przejdź do głównej treści

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 może udostępniać metryki diagnostyczne przez oficjalny Plugin diagnostics-prometheus. Nasłuchuje zaufanej diagnostyki wewnętrznej i 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, czyli standardowy format ekspozycji Prometheus.
Ta trasa używa uwierzytelniania Gateway (zakres operatora). Nie udostępniaj jej jako publicznego, nieuwierzytelnionego punktu końcowego /metrics. Zbieraj ją 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 Plugin

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

Włącz Plugin

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

Uruchom ponownie Gateway

Trasa HTTP jest rejestrowana przy uruchamianiu Plugin, więc po włączeniu wykonaj przeładowanie.
4

Zbieraj chronioną trasę

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"]
diagnostics.enabled: true jest wymagane. 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_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_started_totalcounterchannel, delivery_kind
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcounterbrain, 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_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogrambrak
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounterbrak

​
Zasady etykiet

Etykiety Prometheus pozostają ograniczone i mają niską krotność. 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 krotności OpenClaw. Wartości, które nie spełniają tej polityki, są zastępowane przez unknown, other lub none, zależnie od metryki.
Eksporter ogranicza przechowywane w pamięci szeregi czasowe do 2048 serii łącznie dla liczników, wskaźników i histogramów. Nowe serie powyżej tego limitu są odrzucane, a openclaw_prometheus_series_dropped_total zwiększa się o jeden za każdym razem.Traktuj ten licznik jako twardy sygnał, że atrybut po stronie źródła przecieka 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 pokoi, tokeny przekazania, identyfikatory tur i surowe identyfikatory sesji
  • surowe identyfikatory żądań dostawcy (tylko ograniczone hashe, tam gdzie mają zastosowanie, w spanach — nigdy w metrykach)
  • klucze sesji i identyfikatory sesji
  • nazwy hostów, ścieżki plików, wartości sekretów

​
Przepisy 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
W przypadku pulpitów obejmujących wielu dostawców preferuj gen_ai_client_token_usage: jest zgodne z konwencjami semantycznymi OpenTelemetry GenAI i spójne z metrykami usług GenAI innych niż OpenClaw.

​
Wybór między eksportem Prometheus a OpenTelemetry

OpenClaw obsługuje obie powierzchnie niezależnie. Możesz uruchomić jedną, obie albo żadną.
  • Model pull: Prometheus odczytuje /api/diagnostics/prometheus.
  • Nie wymaga zewnętrznego kolektora.
  • Uwierzytelnianie odbywa się przez normalne uwierzytelnianie Gateway.
  • Powierzchnia obejmuje tylko metryki (bez śladów ani dzienników).
  • Najlepsze dla stosów już ustandaryzowanych 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.
Endpoint 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 niespodziewanie 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 wskaźniki wznawiają pracę od następnej zgłoszonej wartości. Użyj PromQL rate() i increase(), aby czysto obsługiwać resety.

​
Powiązane