Zum Hauptinhalt springen
OpenClaw kann Diagnostikmetriken über das gebündelte Plugin diagnostics-prometheus verfügbar machen. Es lauscht auf vertrauenswürdige interne Diagnosedaten und stellt einen Prometheus-Textendpunkt bereit unter: 
GET /api/diagnostics/prometheus
Der Content-Type ist text/plain; version=0.0.4; charset=utf-8, das Standardformat für die Prometheus-Exposition.
Die Route verwendet Gateway-Authentifizierung (Operator-Bereich). Stellen Sie sie nicht als öffentlichen, nicht authentifizierten Endpunkt /metrics bereit. Erfassen Sie sie über denselben Authentifizierungspfad, den Sie auch für andere Operator-APIs verwenden.
Für Traces, Logs, OTLP-Push und semantische OpenTelemetry-GenAI-Attribute siehe OpenTelemetry export.

​
Schnellstart

1

Das Plugin aktivieren

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

Das Gateway neu starten

Die HTTP-Route wird beim Start des Plugins registriert, daher nach dem Aktivieren neu laden.
3

Die geschützte Route erfassen

Senden Sie dieselbe Gateway-Authentifizierung, die Ihre Operator-Clients verwenden:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
4

Prometheus anbinden

# 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 ist erforderlich. Ohne diese Einstellung registriert das Plugin zwar weiterhin die HTTP-Route, aber es fließen keine Diagnoseereignisse in den Exporter, sodass die Antwort leer ist.

​
Exportierte Metriken

MetrikTypLabels
openclaw_run_completed_totalCounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondsHistogrammchannel, model, outcome, provider, trigger
openclaw_model_call_totalCounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondsHistogrammapi, error_category, model, outcome, provider, transport
openclaw_model_tokens_totalCounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usageHistogrammmodel, provider, token_type
openclaw_model_cost_usd_totalCounteragent, channel, model, provider
openclaw_tool_execution_totalCountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondsHistogrammerror_category, outcome, params_kind, tool
openclaw_harness_run_totalCounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondsHistogrammchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_message_processed_totalCounterchannel, outcome, reason
openclaw_message_processed_duration_secondsHistogrammchannel, outcome, reason
openclaw_message_delivery_totalCounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondsHistogrammchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizeGaugelane
openclaw_queue_lane_wait_secondsHistogrammlane
openclaw_session_state_totalCounterreason, state
openclaw_session_queue_depthGaugestate
openclaw_memory_bytesGaugekind
openclaw_memory_rss_bytesHistogrammnone
openclaw_memory_pressure_totalCounterlevel, reason
openclaw_telemetry_exporter_totalCounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalCounternone

​
Label-Richtlinie

Prometheus-Labels bleiben begrenzt und von niedriger Kardinalität. Der Exporter gibt keine rohen Diagnosekennungen wie runId, sessionKey, sessionId, callId, toolCallId, Nachrichten-IDs, Chat-IDs oder Provider-Request-IDs aus.Label-Werte werden redigiert 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.
Der Exporter begrenzt die im Speicher gehaltenen Zeitreihen auf 2048 Serien über Counter, Gauges und Histogramme zusammen. Neue Serien oberhalb dieser Grenze werden verworfen, und openclaw_prometheus_series_dropped_total wird jedes Mal um eins erhöht.Beobachten Sie diesen Counter als hartes Signal dafür, dass ein Attribut upstream hochkardinale Werte leakt. Der Exporter hebt die Grenze niemals automatisch an; wenn sie steigt, beheben Sie die Ursache statt die Grenze zu deaktivieren.
  • Prompt-Text, Antworttext, Tool-Eingaben, Tool-Ausgaben, System-Prompts
  • rohe Provider-Request-IDs (nur begrenzte Hashes, wo anwendbar, auf Spans — niemals auf Metriken)
  • Sitzungsschlüssel und Sitzungs-IDs
  • Hostnamen, Dateipfade, geheime Werte

​
PromQL-Rezepte

# Tokens pro Minute, aufgeteilt nach Provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Kosten (USD) über die letzte Stunde, nach Modell
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95. Perzentil der Modellausführungsdauer
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO für Wartezeit in der Queue (95p unter 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Verworfene Prometheus-Serien (Kardinalitätsalarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Bevorzugen Sie gen_ai_client_token_usage für providerübergreifende Dashboards: Es folgt den semantischen OpenTelemetry-GenAI-Konventionen und ist konsistent mit Metriken von GenAI-Diensten, die nicht von OpenClaw stammen.

​
Auswahl zwischen Prometheus- und OpenTelemetry-Export

OpenClaw unterstützt beide Oberflächen unabhängig voneinander. Sie können entweder eine, beide oder keine verwenden.
  • Pull-Modell: Prometheus erfasst /api/diagnostics/prometheus.
  • Kein externer Collector erforderlich.
  • Authentifiziert über die normale Gateway-Authentifizierung.
  • Die Oberfläche umfasst nur Metriken (keine Traces oder Logs).
  • Am besten geeignet für Stacks, die bereits auf Prometheus + Grafana standardisiert sind.

​
Fehlerbehebung

  • Prüfen Sie diagnostics.enabled: true in der Konfiguration.
  • Bestätigen Sie mit openclaw plugins list --enabled, dass das Plugin aktiviert und geladen ist.
  • Erzeugen Sie etwas Traffic; Counter und Histogramme geben erst nach mindestens einem Ereignis Zeilen aus.
Der Endpunkt erfordert den Gateway-Operator-Bereich (auth: "gateway" mit gatewayRuntimeScopeSurface: "trusted-operator"). Verwenden Sie dasselbe Token oder Passwort, das Prometheus auch für jede andere Gateway-Operator-Route verwendet. Es gibt keinen öffentlichen, nicht authentifizierten Modus.
Ein neues Attribut überschreitet die Obergrenze von 2048 Serien. Prüfen Sie aktuelle Metriken auf ein unerwartet hochkardinales Label und beheben Sie es an der Quelle. Der Exporter verwirft neue Serien absichtlich, statt Labels stillschweigend umzuschreiben.
Das Plugin hält den Status nur im Speicher. Nach einem Gateway-Neustart werden Counter auf null zurückgesetzt und Gauges beginnen mit ihrem nächsten gemeldeten Wert neu. Verwenden Sie PromQL rate() und increase(), um Resets sauber zu behandeln.

​
Verwandt