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

Gateway

Prometheus metrikleri

OpenClaw, resmi diagnostics-prometheus plugin aracılığıyla tanılama metriklerini sunabilir. Güvenilir tanılamaların yanı sıra dahili olarak etiketlenmiş, dağıtıcıya ait tanılama olaylarını (kuyruk, bellek ve oturum kurtarma sinyalleri) dinler ve şu adreste bir Prometheus metin uç noktası oluşturur:

text
GET /api/diagnostics/prometheus

İçerik türü, standart Prometheus sunum biçimi olan text/plain; version=0.0.4; charset=utf-8 değeridir.

İzler, günlükler, OTLP gönderimi ve OpenTelemetry GenAI semantik öznitelikleri için OpenTelemetry dışa aktarımı bölümüne bakın.

Hızlı başlangıç

  • Plugin'i yükleyin

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

  • Plugin'i etkinleştirin

    Yapılandırma

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

    CLI

    bash
    openclaw plugins enable diagnostics-prometheus

  • Gateway'i yeniden başlatın

    HTTP rotası Plugin başlatılırken kaydedilir; bu nedenle etkinleştirdikten sonra yeniden yükleyin.

  • Korumalı rotadan veri toplayın

    Operatör istemcilerinizin kullandığı Gateway kimlik doğrulamasının aynısını gönderin:

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

  • Prometheus'u bağlayın

    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"]

    • Dışa aktarılan metrikler

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

    Model çağrısı metrikleri için observation_unit="request", gözlemlenebilir tek bir sağlayıcı isteğini ölçer. observation_unit="turn", birden fazla gizli sağlayıcı isteği içerebilen sentetik bir Claude Code veya Codex CLI aracı dönüşünü ölçer. Gecikmeyi karşılaştırırken bu serileri ayrı tutun.

    Etiket politikası

    Sınırlı, düşük kardinaliteli etiketler

    Prometheus etiketleri sınırlı ve düşük kardinaliteli kalır. 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ı yayımlamaz.

    Etiket değerleri sansürlenir ve OpenClaw'ın düşük kardinaliteli karakter politikasıyla eşleşmelidir. Politikaya uymayan değerler, metriğe bağlı olarak unknown, other veya none ile değiştirilir. Kapsamlı aracı oturumu anahtarlarına benzeyen etiketler de unknown ile değiştirilir.

    Seri sınırı ve taşma hesabı

    Dışa aktarıcı, sayaçlar, göstergeler ve histogramların toplamında bellekte tutulan zaman serilerini 2048 seriyle sınırlar. Bu sınırın üzerindeki yeni seriler bırakı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 ilişkin kesin bir sinyal olarak izleyin. Dışa aktarıcı sınırı hiçbir zaman otomatik olarak yükseltmez; değer artarsa sınırı devre dışı bırakmak yerine kaynağı düzeltin.

    Prometheus çıktısında hiçbir zaman görünmeyenler
    • 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 belirteçleri, dönüş kimlikleri ve ham oturum kimlikleri
    • ham sağlayıcı istek kimlikleri (uygun olduğu durumlarda yalnızca span'lerde sınırlı karmalar — metriklerde hiçbir zaman bulunmaz)
    • oturum anahtarları ve oturum kimlikleri
    • ana makine adları, dosya yolları, gizli değerler

    PromQL tarifleri

    promql
    # Sağlayıcıya göre ayrılmış, dakika başına belirteçlersum by (provider) (rate(openclaw_model_tokens_total[1m])) # Modele göre son bir saatteki harcama (USD)sum by (model) (increase(openclaw_model_cost_usd_total[1h])) # Model çalıştırma süresinin 95. yüzdelik dilimihistogram_quantile(  0.95,  sum by (le, provider, model)    (rate(openclaw_run_duration_seconds_bucket[5m]))) # Kuyruk bekleme süresi SLO'su (95p, 2 sn'nin altında)histogram_quantile(  0.95,  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # Sınırlı kaynağa göre ayrılmış Skills kullanımısum by (skill, source) (increase(openclaw_skill_used_total[24h])) # Bırakılan Prometheus serileri (kardinalite alarmı)increase(openclaw_prometheus_series_dropped_total[15m]) > 0

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

    OpenClaw her iki yüzeyi de birbirinden bağımsız olarak destekler. İkisinden birini, ikisini birden veya hiçbirini çalıştırabilirsiniz.

    diagnostics-prometheus

    • Çekme modeli: Prometheus, /api/diagnostics/prometheus uç noktasını tarar.
    • Harici toplayıcı gerekmez.
    • Normal Gateway kimlik doğrulamasıyla doğrulanır.
    • Yüzey yalnızca metrikleri içerir (iz veya günlük içermez).
    • Prometheus + Grafana üzerinde zaten standartlaşmış yığınlar için en uygunudur.

    diagnostics-otel

    • Gönderme modeli: OpenClaw, OTLP/HTTP aracılığıyla bir toplayıcıya veya OTLP uyumlu arka uca veri gönderir.
    • Yüzey; metrikleri, izleri ve günlükleri içerir.
    • Her ikisine de ihtiyaç duyduğunuzda bir OpenTelemetry Collector (prometheus veya prometheusremotewrite dışa aktarıcısı) aracılığıyla Prometheus ile köprü kurar.
    • Tam katalog için OpenTelemetry dışa aktarımı sayfasına bakın.

    Sorun giderme

    Boş yanıt gövdesi
    • Yapılandırmada diagnostics.enabled değerinin false olarak ayarlanmadığını kontrol edin (varsayılanı true değeridir).
    • Plugin'in etkinleştirildiğini ve openclaw plugins list --enabled ile yüklendiğini doğrulayın.
    • Bir miktar trafik oluşturun; sayaçlar ve histogramlar yalnızca en az bir olaydan sonra satır yayımlar.
    401 / yetkisiz

    Uç nokta, Gateway operatör kapsamını (auth: "gateway" ile gatewayRuntimeScopeSurface: "trusted-operator") gerektirir. Prometheus'un diğer Gateway operatör rotaları için kullandığı belirteç veya parolanın aynısını kullanın. Kimlik doğrulaması gerektirmeyen herkese açık bir mod yoktur.

    OPENCLAWVERBATIM323END artıyor

    Yeni bir öznitelik, 2048 serilik sınırı aşıyor. Beklenmedik ölçüde yüksek kardinaliteli bir etiket olup olmadığını görmek için son metrikleri inceleyin ve sorunu kaynağında düzeltin. Dışa aktarıcı, etiketleri sessizce yeniden yazmak yerine yeni serileri bilinçli olarak bırakır.

    Prometheus yeniden başlatmadan sonra eski seriler gösteriyor

    Plugin, durumu yalnızca bellekte tutar. Gateway yeniden başlatıldıktan sonra sayaçlar sıfırlanır ve göstergeler bildirilen sonraki değerlerinden yeniden başlar. Sıfırlamaları sorunsuz işlemek için PromQL rate() ve increase() kullanın.

    İlgili içerikler

    Was this useful?
    Bu sayfada

    Bu sayfada