Ana içeriğe atla

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, tanılama metriklerini resmi diagnostics-prometheus Plugin’i aracılığıyla sunabilir. Güvenilen dahili tanılamaları dinler ve şu adreste Prometheus metin uç noktası oluşturur: 
GET /api/diagnostics/prometheus
İçerik türü, standart Prometheus sunum 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ı gerektirmeyen bir /metrics uç noktası olarak sunmayın. Diğer operatör API’leri için kullandığınız aynı kimlik doğrulama yolu üzerinden kazıyı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 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şlatılırken kaydedilir, bu nedenle etkinleştirdikten sonra yeniden yükleyin.
4

Korumalı rotayı 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
5

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 HTTP rotasını yine de kaydeder, ancak dışa aktarıcıya hiçbir tanılama olayı akmaz; bu yüzden 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_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_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_recovery_totalsayaçaction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
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 politikası

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 politikasıyla eşleşmelidir. 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, göstergeler ve histogramlar genelinde toplam 2048 seriyle sınırlar. Bu sınırın ötesindeki yeni seriler atılır ve her seferinde openclaw_prometheus_series_dropped_total bir artırılır.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 yükseltmez; değer 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
  • Konuşma dökümleri, ses yükleri, çağrı kimlikleri, oda kimlikleri, devir tokenları, tur kimlikleri ve ham oturum kimlikleri
  • ham sağlayıcı istek kimlikleri (yalnızca uygun olduğunda span’lerde sınırlı karmalar; 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

# 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 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 veya hiçbirini çalıştırabilirsiniz.
  • Pull modeli: Prometheus /api/diagnostics/prometheus adresini kazır.
  • Harici collector gerekmez.
  • Normal Gateway kimlik doğrulaması üzerinden kimliği doğrulanır.
  • Yüzey yalnızca metriklerden oluşur (iz veya günlük yoktur).
  • Prometheus + Grafana üzerinde zaten standartlaşmış yığınlar için en iyisidir.

​
Sorun giderme

  • Yapılandırmada diagnostics.enabled: true olup olmadığını kontrol edin.
  • Plugin’in etkinleştirildiğini ve openclaw plugins list --enabled ile yüklendiğini doğrulayın.
  • Biraz trafik oluşturun; sayaçlar ve histogramlar yalnızca 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 Gateway operatör rotaları için kullandığı aynı tokenı veya parolayı kullanın. Genel, kimliği doğrulanmamış bir 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 atar.
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 ele almak için PromQL rate() ve increase() kullanın.

​
İlgili