OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Prometheus-Metriken

OpenClaw kann Diagnosemetriken über das offizielle diagnostics-prometheus-Plugin bereitstellen. Es erfasst vertrauenswürdige Diagnosedaten sowie intern markierte, dem Dispatcher zugeordnete Diagnoseereignisse (Signale zu Warteschlangen, Arbeitsspeicher und Sitzungswiederherstellung) und stellt einen Prometheus-Textendpunkt unter folgender Adresse bereit:

text
GET /api/diagnostics/prometheus

Der Inhaltstyp ist text/plain; version=0.0.4; charset=utf-8, das standardmäßige Prometheus-Expositionsformat.

Informationen zu Traces, Protokollen, OTLP-Push und semantischen OpenTelemetry-GenAI-Attributen finden Sie unter OpenTelemetry-Export.

Schnellstart

  • Plugin installieren

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

  • Plugin aktivieren

    Konfiguration

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

    CLI

    bash
    openclaw plugins enable diagnostics-prometheus

  • Gateway neu starten

    Die HTTP-Route wird beim Start des Plugins registriert. Laden Sie das Gateway daher nach der Aktivierung neu.

  • Geschützte Route abrufen

    Senden Sie dieselbe Gateway-Authentifizierung, die Ihre Operator-Clients verwenden:

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

  • Prometheus anbinden

    yaml
    # prometheus.ymlscrape_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"]

    • Exportierte Metriken

    Metrik Typ Labels
    openclaw_run_completed_total Zähler channel, model, outcome, provider, trigger
    openclaw_run_duration_seconds Histogramm channel, model, outcome, provider, trigger
    openclaw_model_call_total Zähler api, error_category, model, observation_unit, outcome, provider, transport
    openclaw_model_call_duration_seconds Histogramm api, error_category, model, observation_unit, outcome, provider, transport
    openclaw_model_failover_total Zähler from_model, from_provider, lane, reason, suspended, to_model, to_provider
    openclaw_model_tokens_total Zähler agent, channel, model, provider, token_type
    openclaw_gen_ai_client_token_usage Histogramm model, provider, token_type
    openclaw_model_cost_usd_total Zähler agent, channel, model, provider
    openclaw_model_usage_duration_seconds Histogramm agent, channel, model, provider
    openclaw_skill_used_total Zähler activation, agent, skill, source
    openclaw_tool_execution_total Zähler error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_duration_seconds Histogramm error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_blocked_total Zähler denied_reason, params_kind, tool, tool_owner, tool_source
    openclaw_harness_run_total Zähler channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_harness_run_duration_seconds Histogramm channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_webhook_received_total Zähler channel, webhook
    openclaw_webhook_error_total Zähler channel, webhook
    openclaw_webhook_duration_seconds Histogramm channel, webhook
    openclaw_message_received_total Zähler channel, source
    openclaw_message_dispatch_started_total Zähler channel, source
    openclaw_message_dispatch_completed_total Zähler channel, outcome, reason, source
    openclaw_message_dispatch_duration_seconds Histogramm channel, outcome, reason, source
    openclaw_message_processed_total Zähler channel, outcome, reason
    openclaw_message_processed_duration_seconds Histogramm channel, outcome, reason
    openclaw_message_delivery_started_total Zähler channel, delivery_kind
    openclaw_message_delivery_total Zähler channel, delivery_kind, error_category, outcome
    openclaw_message_delivery_duration_seconds Histogramm channel, delivery_kind, error_category, outcome
    openclaw_talk_event_total Zähler brain, event_type, mode, provider, transport
    openclaw_talk_event_duration_seconds Histogramm brain, event_type, mode, provider, transport
    openclaw_talk_audio_bytes Histogramm brain, event_type, mode, provider, transport
    openclaw_queue_lane_size Messwert lane
    openclaw_queue_lane_wait_seconds Histogramm lane
    openclaw_session_state_total Zähler reason, state
    openclaw_session_queue_depth Messwert state
    openclaw_session_turn_created_total Zähler agent, channel, trigger
    openclaw_session_stuck_total Zähler reason, state
    openclaw_session_stuck_age_seconds Histogramm reason, state
    openclaw_session_recovery_total Zähler action, active_work_kind, state, status
    openclaw_session_recovery_age_seconds Histogramm action, active_work_kind, state, status
    openclaw_liveness_warning_total Zähler reason
    openclaw_liveness_sessions Messwert state
    openclaw_liveness_event_loop_delay_p99_seconds Histogramm reason
    openclaw_liveness_event_loop_delay_max_seconds Histogramm reason
    openclaw_liveness_event_loop_utilization_ratio Histogramm reason
    openclaw_liveness_cpu_core_ratio Histogramm reason
    openclaw_payload_large_total Zähler action, channel, plugin, reason, surface
    openclaw_payload_large_bytes Histogramm action, channel, plugin, reason, surface
    openclaw_memory_bytes Messwert kind
    openclaw_memory_rss_bytes Histogramm keine
    openclaw_memory_pressure_total Zähler level, reason
    openclaw_telemetry_exporter_total Zähler exporter, reason, signal, status
    openclaw_prometheus_series_dropped_total Zähler keine
    openclaw_diagnostic_async_queue_dropped_total Zähler drop_class
    openclaw_diagnostic_async_queue_length Messwert keine

    Für Metriken zu Modellaufrufen misst observation_unit="request" eine beobachtbare Provider-Anfrage. observation_unit="turn" misst einen synthetischen Agentendurchlauf von Claude Code oder der Codex CLI, der mehrere verborgene Provider-Anfragen enthalten kann. Halten Sie diese Zeitreihen beim Vergleich der Latenz getrennt.

    Richtlinie für Labels

    Begrenzte Labels mit niedriger Kardinalität

    Prometheus-Labels bleiben begrenzt und weisen eine niedrige Kardinalität auf. Der Exporter gibt keine unverarbeiteten Diagnosekennungen wie runId, sessionKey, sessionId, callId, toolCallId, Nachrichten-IDs, Chat-IDs oder IDs von Provider-Anfragen aus.

    Labelwerte werden unkenntlich gemacht und müssen der OpenClaw-Zeichenrichtlinie für niedrige Kardinalität entsprechen. Werte, die diese Richtlinie nicht erfüllen, werden je nach Metrik durch unknown, other oder none ersetzt. Labels, die wie bereichsbezogene Schlüssel für Agentensitzungen aussehen, werden ebenfalls durch unknown ersetzt.

    Zeitreihenlimit und Erfassung von Überschreitungen

    Der Exporter begrenzt die Anzahl der im Arbeitsspeicher vorgehaltenen Zeitreihen über Zähler, Messwerte und Histogramme hinweg auf insgesamt 2048 Zeitreihen. Neue Zeitreihen, die dieses Limit überschreiten, werden verworfen, und openclaw_prometheus_series_dropped_total wird jedes Mal um eins erhöht.

    Überwachen Sie diesen Zähler als eindeutiges Signal dafür, dass ein vorgelagertes Attribut Werte mit hoher Kardinalität durchlässt. Der Exporter hebt das Limit niemals automatisch auf. Wenn der Zähler steigt, beheben Sie die Ursache, statt das Limit zu deaktivieren.

    Was niemals in der Prometheus-Ausgabe erscheint
    • Prompttext, Antworttext, Tool-Eingaben, Tool-Ausgaben, System-Prompts
    • Gesprächstranskripte, Audiodaten, Anruf-IDs, Raum-IDs, Übergabe-Token, Durchlauf-IDs und unverarbeitete Sitzungs-IDs
    • unverarbeitete IDs von Provider-Anfragen (gegebenenfalls nur begrenzte Hashwerte in Spans – niemals in Metriken)
    • Sitzungsschlüssel und Sitzungs-IDs
    • Hostnamen, Dateipfade, geheime Werte

    PromQL-Rezepte

    promql
    # Token pro Minute, nach Provider aufgeschlüsseltsum by (provider) (rate(openclaw_model_tokens_total[1m])) # Ausgaben (USD) während der letzten Stunde, nach Modellsum by (model) (increase(openclaw_model_cost_usd_total[1h])) # 95. Perzentil der Dauer von Modellläufenhistogram_quantile(  0.95,  sum by (le, provider, model)    (rate(openclaw_run_duration_seconds_bucket[5m]))) # SLO für die Wartezeit in der Warteschlange (95. Perzentil unter 2s)histogram_quantile(  0.95,  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # Skill-Nutzung, nach begrenzter Quelle aufgeschlüsseltsum by (skill, source) (increase(openclaw_skill_used_total[24h])) # Verworfene Prometheus-Zeitreihen (Kardinalitätsalarm)increase(openclaw_prometheus_series_dropped_total[15m]) > 0

    Wahl zwischen Prometheus- und OpenTelemetry-Export

    OpenClaw unterstützt beide Schnittstellen unabhängig voneinander. Sie können eine, beide oder keine davon verwenden.

    diagnostics-prometheus

    • Pull-Modell: Prometheus ruft /api/diagnostics/prometheus ab.
    • Kein externer Collector erforderlich.
    • Authentifizierung über die normale Gateway-Authentifizierung.
    • Die Schnittstelle umfasst nur Metriken (keine Traces oder Protokolle).
    • Am besten für Stacks geeignet, die bereits auf Prometheus + Grafana standardisiert sind.

    diagnostics-otel

    • Push-Modell: OpenClaw sendet OTLP/HTTP an einen Collector oder ein OTLP-kompatibles Backend.
    • Die Schnittstelle umfasst Metriken, Traces und Protokolle.
    • Stellt über einen OpenTelemetry Collector (prometheus- oder prometheusremotewrite-Exporter) eine Verbindung zu Prometheus her, wenn Sie beides benötigen.
    • Den vollständigen Katalog finden Sie unter OpenTelemetry-Export.

    Fehlerbehebung

    Leerer Antworttext
    • Prüfen Sie, dass diagnostics.enabled in der Konfiguration nicht auf false gesetzt ist (der Standardwert ist true).
    • Bestätigen Sie mit openclaw plugins list --enabled, dass das Plugin aktiviert und geladen ist.
    • Erzeugen Sie etwas Datenverkehr. Zähler und Histogramme geben erst nach mindestens einem Ereignis Zeilen aus.
    401 / nicht autorisiert

    Der Endpunkt erfordert den Gateway-Operator-Berechtigungsbereich (auth: "gateway" mit gatewayRuntimeScopeSurface: "trusted-operator"). Verwenden Sie dasselbe Token oder Passwort, das Prometheus für alle anderen Gateway-Operator-Routen verwendet. Es gibt keinen öffentlichen, nicht authentifizierten Modus.

    `openclaw_prometheus_series_dropped_total` steigt

    Ein neues Attribut überschreitet das Limit von 2048 Zeitreihen. Untersuchen Sie die aktuellen Metriken auf ein Label mit unerwartet hoher Kardinalität und beheben Sie die Ursache. Der Exporter verwirft absichtlich neue Zeitreihen, statt Labels stillschweigend umzuschreiben.

    Prometheus zeigt nach einem Neustart veraltete Zeitreihen an

    Das Plugin speichert seinen Zustand ausschließlich im Arbeitsspeicher. Nach einem Neustart des Gateways werden Zähler auf null zurückgesetzt, und Messwerte beginnen erneut mit ihrem nächsten gemeldeten Wert. Verwenden Sie in PromQL rate() und increase(), um Zurücksetzungen korrekt zu verarbeiten.

    Verwandte Themen

    Was this useful?
    On this page

    On this page