Ana içeriğe atla
OpenClaw, birlikte gelen diagnostics-prometheus Plugin’i aracılığıyla tanılama metriklerini sunabilir. Güvenilir dahili tanılamaları dinler ve şu adreste bir Prometheus metin uç noktası oluşturur: 
GET /api/diagnostics/prometheus
İçerik türü text/plain; version=0.0.4; charset=utf-8 şeklindedir; bu, standart Prometheus dışa aktarma biçimidir.
Yol Gateway kimlik doğrulamasını kullanır (operatör kapsamı). Bunu herkese açık, kimlik doğrulamasız bir /metrics uç noktası olarak sunmayın. Kazımayı, diğer operatör API’leri için kullandığınız aynı kimlik doğrulama yolu üzerinden yapın.
İzler, günlükler, OTLP push ve OpenTelemetry GenAI anlamsal öznitelikleri için bkz. OpenTelemetry dışa aktarma.

​
Hızlı başlangıç

1

Plugin'i etkinleştirin

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

Gateway'i yeniden başlatın

HTTP yolu Plugin başlangıcında kaydedilir, bu nedenle etkinleştirdikten sonra yeniden yükleyin.
3

Korumalı yolu kazıyı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
4

Prometheus'u bağlayın

# 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 yine HTTP yolunu kaydeder ancak hiçbir tanılama olayı dışa aktarıcıya akmaz, bu yüzden yanıt boştur.

​
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_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_tool_execution_totalsayaçerror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
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_message_processed_totalsayaçchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_totalsayaçchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalsayaçreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
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 politikası

Prometheus etiketleri sınırlı ve düşük kardinalitelidir. Dışa aktarıcı; runId, sessionKey, sessionId, callId, toolCallId, mesaj kimlikleri, sohbet kimlikleri veya sağlayıcı istek kimlikleri gibi ham tanılama tanımlayıcılarını yaymaz.Etiket değerleri redakte edilir ve OpenClaw’ın düşük kardinaliteli karakter politikasına uymalıdır. Politikayı geçemeyen değerler, metriğe bağlı olarak unknown, other veya none ile değiştirilir.
Dışa aktarıcı, bellekte tutulan zaman serilerini sayaçlar, gauge’lar ve histogramlar dahil toplam 2048 seri ile sınırlar. Bu sınırın ötesindeki yeni seriler bırakılır ve her seferinde openclaw_prometheus_series_dropped_total bir artırılır.Yukarı akışta bir özniteliğin yüksek kardinaliteli değer sızdırdığına dair kesin bir sinyal olarak bu sayacı izleyin. Dışa aktarıcı sınırı asla otomatik olarak yükseltmez; artıyorsa sınırı devre dışı bırakmak yerine kaynağı düzeltin.
  • istem metni, yanıt metni, araç girdileri, araç çıktıları, sistem istemleri
  • ham sağlayıcı istek kimlikleri (yalnızca geçerliyse sınırlı karmalar span’lerde bulunur — metriklerde asla)
  • oturum anahtarları ve oturum kimlikleri
  • host adları, dosya yolları, gizli değerler

​
PromQL tarifleri

# Dakika başına token, sağlayıcıya göre bölünmüş
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Son bir saatte harcama (USD), modele göre
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95. yüzdelik model çalışma süresi
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Kuyruk bekleme süresi SLO'su (95p 2s altı)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Bırakılan Prometheus serileri (kardinalite alarmı)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Sağlayıcılar arası panolar için gen_ai_client_token_usage tercih edin: OpenTelemetry GenAI anlamsal kurallarını izler ve OpenClaw dışındaki GenAI hizmetlerinden gelen metriklerle tutarlıdır.

​
Prometheus ve OpenTelemetry dışa aktarma arasında seçim

OpenClaw her iki yüzeyi de bağımsız olarak destekler. Bunlardan birini, ikisini birden veya hiçbirini çalıştırabilirsiniz.
  • Pull modeli: Prometheus, /api/diagnostics/prometheus yolunu kazır.
  • Harici toplayıcı gerekmez.
  • Normal Gateway kimlik doğrulaması üzerinden doğrulanı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 değerini kontrol edin.
  • openclaw plugins list --enabled ile Plugin’in etkin ve yüklü olduğunu doğrulayın.
  • Biraz trafik oluşturun; sayaçlar ve histogramlar ancak en az bir olaydan sonra satır yayar.
Uç nokta Gateway operatör kapsamını gerektirir (auth: "gateway" ve gatewayRuntimeScopeSurface: "trusted-operator"). Prometheus’un diğer herhangi bir Gateway operatör yolu için kullandığı aynı token’ı veya parolayı kullanın. Herkese açık kimlik doğrulamasız kip yoktur.
Yeni bir öznitelik 2048 seri sınırını aşıyor. Son metriklerde beklenmedik derecede yüksek kardinaliteli bir etiketi inceleyin ve bunu kaynakta düzeltin. Dışa aktarıcı, etiketleri sessizce yeniden yazmak yerine bilinçli olarak yeni serileri bırakır.
Plugin durumu yalnızca bellekte tutar. Gateway yeniden başlatıldıktan sonra sayaçlar sıfıra döner ve gauge’lar bir sonraki bildirilen değerlerinden yeniden başlar. Sıfırlamaları temiz şekilde ele almak için PromQL rate() ve increase() kullanın.

​
İlgili