Ana içeriğe atla
OpenClaw, resmi diagnostics-prometheus Plugin aracılığıyla tanılama metriklerini sunabilir. Güvenilir tanılamaları ve çekirdeğin yaydığı Gateway kararlılık olaylarını dinler, ardından şu adreste bir Prometheus metin uç noktası oluşturur: 
GET /api/diagnostics/prometheus
İçerik türü, standart Prometheus gösterim biçimi olan text/plain; version=0.0.4; charset=utf-8 değeridir.
Rota, Gateway kimlik doğrulamasını (operatör kapsamı) kullanır. Bunu herkese açık, kimlik doğrulamasız bir /metrics uç noktası olarak sunmayın. Diğer operatör API’leri için kullandığınız aynı kimlik doğrulama yolu üzerinden toplayın.
İzler, günlükler, OTLP push ve OpenTelemetry GenAI semantik öznitelikleri için bkz. OpenTelemetry dışa aktarma.

​
Hızlı başlangıç

1

Plugin'i yükleyin

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

Plugin'i etkinleştirin

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

Gateway'i yeniden başlatın

HTTP rotası Plugin başlangıcında kaydedilir, bu yüzden etkinleştirdikten sonra yeniden yükleyin.
4

Korumalı rotayı toplayın

Operatör istemcilerinizin kullandığı aynı gateway kimlik doğrulamasını gönderin:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Prometheus'u Bağla

# 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 gereklidir. Bu olmadan Plugin HTTP rotasını yine kaydeder, ancak dışa aktarıcıya hiçbir tanılama olayı akmaz; bu nedenle yanıt boş olur.

​
Dışa aktarılan metrikler

MetrikTürEtiketler
openclaw_run_completed_totalsayaçchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalsayaçapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalsayaçfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalsayaçagent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalsayaçagent, channel, model, provider
openclaw_skill_used_totalsayaçactivation, agent, skill, source
openclaw_tool_execution_totalsayaçerror_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_totalsayaçdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalsayaçchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalsayaçchannel, webhook
openclaw_webhook_error_totalsayaçchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totalsayaçchannel, source
openclaw_message_dispatch_started_totalsayaçchannel, source
openclaw_message_dispatch_completed_totalsayaçchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
openclaw_message_processed_totalsayaçchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totalsayaçchannel, delivery_kind
openclaw_message_delivery_totalsayaçchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalsayaçbrain, 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_sizegöstergelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalsayaçreason, state
openclaw_session_queue_depthgöstergestate
openclaw_session_turn_created_totalsayaçagent, channel, trigger
openclaw_session_stuck_totalsayaçreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totalsayaçaction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totalsayaçreason
openclaw_liveness_sessionsgöstergestate
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_totalsayaçaction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesgöstergekind
openclaw_memory_rss_byteshistogramyok
openclaw_memory_pressure_totalsayaçlevel, reason
openclaw_telemetry_exporter_totalsayaçexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalsayaçyok

​
Etiket ilkesi

Prometheus etiketleri sınırlı ve düşük kardinaliteli kalır. Dışa aktarıcı runId, sessionKey, sessionId, callId, toolCallId, ileti kimlikleri, sohbet kimlikleri veya sağlayıcı istek kimlikleri gibi ham tanılama tanımlayıcıları yaymaz.Etiket değerleri redakte edilir ve OpenClaw’ın düşük kardinaliteli karakter ilkesiyle eşleşmelidir. İlkeyi karşılamayan değerler metriğe bağlı olarak unknown, other veya none ile değiştirilir. Kapsamlı aracı oturum anahtarlarına benzeyen etiketler de unknown ile değiştirilir.
Dışa aktarıcı; sayaçlar, göstergeler ve histogramlar genelinde bellekte tutulan zaman serilerini toplam 2048 seriyle sınırlar. Bu sınırın ötesindeki yeni seriler bırakılır ve openclaw_prometheus_series_dropped_total her seferinde bir artar.Bu sayacı, yukarı akıştaki bir özniteliğin yüksek kardinaliteli değerler sızdırdığına dair kesin bir sinyal olarak izleyin. Dışa aktarıcı sınırı hiçbir zaman otomatik olarak kaldırmaz; sayaç yükselirse sınırı devre dışı bırakmak yerine kaynağı düzeltin.
  • istem metni, yanıt metni, araç girdileri, araç çıktıları, sistem istemleri
  • Talk dökümleri, ses yükleri, çağrı kimlikleri, oda kimlikleri, devretme belirteçleri, tur kimlikleri ve ham oturum kimlikleri
  • ham sağlayıcı istek kimlikleri (yalnızca uygulanabildiğinde span’lerde sınırlı hash’ler; metriklerde asla)
  • oturum anahtarları ve oturum kimlikleri
  • ana makine adları, dosya yolları, gizli değerler

​
PromQL tarifleri

# 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
Sağlayıcılar arası panolar için gen_ai_client_token_usage kullanmayı tercih edin: OpenTelemetry GenAI semantik kurallarını izler ve OpenClaw dışı GenAI hizmetlerinden gelen metriklerle tutarlıdır.

​
Prometheus ve OpenTelemetry dışa aktarımı arasında seçim yapma

OpenClaw her iki yüzeyi de bağımsız olarak destekler. Birini, ikisini birden ya da hiçbirini çalıştırabilirsiniz.
  • Pull modeli: Prometheus /api/diagnostics/prometheus adresini kazır.
  • Harici toplayıcı gerekmez.
  • Normal Gateway kimlik doğrulaması üzerinden kimlik doğrulaması yapılır.
  • Yüzey yalnızca metriklerden oluşur (iz veya günlük yoktur).
  • Zaten Prometheus + Grafana üzerinde standartlaşmış yığınlar için en uygunudur.

​
Sorun giderme

  • Yapılandırmada diagnostics.enabled: true ayarını kontrol edin.
  • Plugin’in etkinleştirildiğini ve openclaw plugins list --enabled ile yüklendiğini doğrulayın.
  • Biraz trafik üretin; sayaçlar ve histogramlar yalnızca en az bir olaydan sonra satır yayar.
Uç nokta Gateway operatör kapsamını gerektirir (gatewayRuntimeScopeSurface: "trusted-operator" ile auth: "gateway"). Prometheus’un diğer Gateway operatör rotaları için kullandığı aynı belirteci veya parolayı kullanın. Herkese açık, kimlik doğrulamasız mod yoktur.
Yeni bir öznitelik 2048 seri sınırını aşıyor. Beklenmedik derecede yüksek kardinaliteli bir etiket için son metrikleri inceleyin ve sorunu kaynağında düzeltin. Dışa aktarıcı, etiketleri sessizce yeniden yazmak yerine yeni serileri kasıtlı olarak düşürür.
Plugin durumu yalnızca bellekte tutar. Gateway yeniden başlatıldıktan sonra sayaçlar sıfırlanır ve göstergeler bir sonraki bildirilen değerlerinde yeniden başlar. Sıfırlamaları temiz şekilde işlemek için PromQL rate() ve increase() kullanın.

​
İlgili