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

Gateway

معیارهای Prometheus

OpenClaw می‌تواند معیارهای عیب‌یابی را از طریق Plugin رسمی diagnostics-prometheus ارائه کند. این Plugin به داده‌های عیب‌یابی مورداعتماد و نیز رویدادهای عیب‌یابی برچسب‌گذاری‌شده داخلی که تحت مالکیت توزیع‌کننده هستند (سیگنال‌های صف، حافظه و بازیابی نشست) گوش می‌دهد و یک نقطه پایانی متنی Prometheus را در نشانی زیر ارائه می‌کند:

text
GET /api/diagnostics/prometheus

نوع محتوا text/plain; version=0.0.4; charset=utf-8 است که قالب استاندارد ارائه داده‌های Prometheus محسوب می‌شود.

برای ردگیری‌ها، گزارش‌ها، ارسال OTLP و ویژگی‌های معنایی OpenTelemetry GenAI، به خروجی OpenTelemetry مراجعه کنید.

شروع سریع

  • نصب Plugin

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

  • فعال‌سازی Plugin

    پیکربندی

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

    CLI

    bash
    openclaw plugins enable diagnostics-prometheus

  • راه‌اندازی مجدد Gateway

    مسیر HTTP هنگام راه‌اندازی Plugin ثبت می‌شود؛ بنابراین پس از فعال‌سازی، آن را مجدداً بارگذاری کنید.

  • جمع‌آوری داده از مسیر محافظت‌شده

    همان اطلاعات احراز هویت Gateway را ارسال کنید که کلاینت‌های اپراتور شما استفاده می‌کنند:

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

  • اتصال Prometheus

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

    • معیارهای صادرشده

    معیار نوع برچسب‌ها
    openclaw_run_completed_total شمارنده channel, model, outcome, provider, trigger
    openclaw_run_duration_seconds هیستوگرام channel, model, outcome, provider, trigger
    openclaw_model_call_total شمارنده api, error_category, model, outcome, provider, transport
    openclaw_model_call_duration_seconds هیستوگرام api, error_category, model, outcome, provider, transport
    openclaw_model_failover_total شمارنده from_model, from_provider, lane, reason, suspended, to_model, to_provider
    openclaw_model_tokens_total شمارنده agent, channel, model, provider, token_type
    openclaw_gen_ai_client_token_usage هیستوگرام model, provider, token_type
    openclaw_model_cost_usd_total شمارنده agent, channel, model, provider
    openclaw_model_usage_duration_seconds هیستوگرام agent, channel, model, provider
    openclaw_skill_used_total شمارنده activation, agent, skill, source
    openclaw_tool_execution_total شمارنده error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_duration_seconds هیستوگرام error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_blocked_total شمارنده denied_reason, params_kind, tool, tool_owner, tool_source
    openclaw_harness_run_total شمارنده channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_harness_run_duration_seconds هیستوگرام channel, error_category, harness, model, outcome, phase, plugin, provider
    openclaw_webhook_received_total شمارنده channel, webhook
    openclaw_webhook_error_total شمارنده channel, webhook
    openclaw_webhook_duration_seconds هیستوگرام channel, webhook
    openclaw_message_received_total شمارنده channel, source
    openclaw_message_dispatch_started_total شمارنده channel, source
    openclaw_message_dispatch_completed_total شمارنده channel, outcome, reason, source
    openclaw_message_dispatch_duration_seconds هیستوگرام channel, outcome, reason, source
    openclaw_message_processed_total شمارنده channel, outcome, reason
    openclaw_message_processed_duration_seconds هیستوگرام channel, outcome, reason
    openclaw_message_delivery_started_total شمارنده channel, delivery_kind
    openclaw_message_delivery_total شمارنده channel, delivery_kind, error_category, outcome
    openclaw_message_delivery_duration_seconds هیستوگرام channel, delivery_kind, error_category, outcome
    openclaw_talk_event_total شمارنده brain, event_type, mode, provider, transport
    openclaw_talk_event_duration_seconds هیستوگرام brain, event_type, mode, provider, transport
    openclaw_talk_audio_bytes هیستوگرام brain, event_type, mode, provider, transport
    openclaw_queue_lane_size سنجه lane
    openclaw_queue_lane_wait_seconds هیستوگرام lane
    openclaw_session_state_total شمارنده reason, state
    openclaw_session_queue_depth سنجه state
    openclaw_session_turn_created_total شمارنده agent, channel, trigger
    openclaw_session_stuck_total شمارنده reason, state
    openclaw_session_stuck_age_seconds هیستوگرام reason, state
    openclaw_session_recovery_total شمارنده action, active_work_kind, state, status
    openclaw_session_recovery_age_seconds هیستوگرام action, active_work_kind, state, status
    openclaw_liveness_warning_total شمارنده reason
    openclaw_liveness_sessions سنجه state
    openclaw_liveness_event_loop_delay_p99_seconds هیستوگرام reason
    openclaw_liveness_event_loop_delay_max_seconds هیستوگرام reason
    openclaw_liveness_event_loop_utilization_ratio هیستوگرام reason
    openclaw_liveness_cpu_core_ratio هیستوگرام reason
    openclaw_payload_large_total شمارنده action, channel, plugin, reason, surface
    openclaw_payload_large_bytes هیستوگرام action, channel, plugin, reason, surface
    openclaw_memory_bytes سنجه kind
    openclaw_memory_rss_bytes هیستوگرام هیچ‌کدام
    openclaw_memory_pressure_total شمارنده level, reason
    openclaw_telemetry_exporter_total شمارنده exporter, reason, signal, status
    openclaw_prometheus_series_dropped_total شمارنده هیچ‌کدام
    openclaw_diagnostic_async_queue_dropped_total شمارنده drop_class
    openclaw_diagnostic_async_queue_length سنجه هیچ‌کدام

    خط‌مشی برچسب‌ها

    برچسب‌های محدود با کاردینالیتی پایین

    برچسب‌های Prometheus محدود و دارای کاردینالیتی پایین باقی می‌مانند. صادرکننده شناسه‌های تشخیصی خام مانند runId،‏ sessionKey،‏ sessionId،‏ callId،‏ toolCallId، شناسه‌های پیام، شناسه‌های گفت‌وگو یا شناسه‌های درخواست ارائه‌دهنده را منتشر نمی‌کند.

    مقادیر برچسب‌ها حذف اطلاعات حساس می‌شوند و باید با خط‌مشی نویسه‌های کم‌کاردینالیتی OpenClaw مطابقت داشته باشند. مقادیری که با این خط‌مشی مطابقت ندارند، بسته به معیار با unknown،‏ other یا none جایگزین می‌شوند. برچسب‌هایی که شبیه کلیدهای نشست عاملِ محدوده‌بندی‌شده هستند نیز با unknown جایگزین می‌شوند.

    سقف سری‌ها و محاسبه سرریز

    صادرکننده، تعداد سری‌های زمانی نگه‌داری‌شده در حافظه را در مجموع شمارنده‌ها، سنجه‌ها و هیستوگرام‌ها به ۲۰۴۸ سری محدود می‌کند. سری‌های جدید فراتر از این سقف حذف می‌شوند و openclaw_prometheus_series_dropped_total هر بار یک واحد افزایش می‌یابد.

    این شمارنده را به‌عنوان نشانه‌ای قطعی از نشت مقادیر با کاردینالیتی بالا از یک ویژگی بالادستی زیر نظر بگیرید. صادرکننده هرگز این سقف را به‌طور خودکار افزایش نمی‌دهد؛ اگر شمارنده بالا می‌رود، به‌جای غیرفعال‌کردن سقف، منبع را اصلاح کنید.

    مواردی که هرگز در خروجی Prometheus ظاهر نمی‌شوند
    • متن پرامپت، متن پاسخ، ورودی‌های ابزار، خروجی‌های ابزار، پرامپت‌های سیستمی
    • رونوشت‌های مکالمه، داده‌های صوتی، شناسه‌های تماس، شناسه‌های اتاق، توکن‌های واگذاری، شناسه‌های نوبت و شناسه‌های خام نشست
    • شناسه‌های خام درخواست ارائه‌دهنده (فقط هش‌های کران‌دار، در موارد مقتضی، در spanها — هرگز در متریک‌ها)
    • کلیدها و شناسه‌های نشست
    • نام‌های میزبان، مسیرهای فایل، مقادیر محرمانه

    دستورالعمل‌های PromQL

    promql
    # Tokens per minute, split by providersum by (provider) (rate(openclaw_model_tokens_total[1m])) # Spend (USD) over the last hour, by modelsum by (model) (increase(openclaw_model_cost_usd_total[1h])) # 95th percentile model run durationhistogram_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 sourcesum by (skill, source) (increase(openclaw_skill_used_total[24h])) # Dropped Prometheus series (cardinality alarm)increase(openclaw_prometheus_series_dropped_total[15m]) > 0

    انتخاب میان خروجی Prometheus و OpenTelemetry

    OpenClaw از هر دو سطح به‌طور مستقل پشتیبانی می‌کند. می‌توانید یکی، هر دو یا هیچ‌کدام را اجرا کنید.

    diagnostics-prometheus

    • مدل واکشی: Prometheus مسیر /api/diagnostics/prometheus را جمع‌آوری می‌کند.
    • به جمع‌آورنده خارجی نیازی ندارد.
    • از طریق احراز هویت عادی Gateway احراز هویت می‌شود.
    • این سطح فقط شامل متریک‌ها است و ردیابی یا گزارش رویداد ندارد.
    • بهترین گزینه برای پشته‌هایی است که از قبل بر Prometheus و Grafana استاندارد شده‌اند.

    diagnostics-otel

    • مدل ارسال: OpenClaw داده‌های OTLP/HTTP را به یک جمع‌آورنده یا بخش پشتی سازگار با OTLP می‌فرستد.
    • این سطح شامل متریک‌ها، ردیابی‌ها و گزارش‌های رویداد است.
    • هنگامی که به هر دو نیاز دارید، از طریق OpenTelemetry Collector و صادرکننده prometheus یا prometheusremotewrite به Prometheus متصل می‌شود.
    • برای فهرست کامل، به خروجی OpenTelemetry مراجعه کنید.

    عیب‌یابی

    بدنه پاسخ خالی
    • بررسی کنید که diagnostics.enabled در پیکربندی روی false تنظیم نشده باشد؛ مقدار پیش‌فرض آن true است.
    • با openclaw plugins list --enabled تأیید کنید که Plugin فعال و بارگذاری شده است.
    • مقداری ترافیک ایجاد کنید؛ شمارنده‌ها و هیستوگرام‌ها تنها پس از وقوع حداقل یک رویداد، خط خروجی تولید می‌کنند.
    401 / غیرمجاز

    نقطه پایانی به دامنه اپراتور Gateway نیاز دارد (auth: "gateway" همراه با gatewayRuntimeScopeSurface: "trusted-operator"). از همان توکن یا گذرواژه‌ای استفاده کنید که Prometheus برای سایر مسیرهای اپراتور Gateway استفاده می‌کند. هیچ حالت عمومی بدون احراز هویتی وجود ندارد.

    `openclaw_prometheus_series_dropped_total` در حال افزایش است

    یک ویژگی جدید از سقف ۲۰۴۸ سری فراتر رفته است. متریک‌های اخیر را برای یافتن برچسبی با کاردینالیتی بالای غیرمنتظره بررسی کنید و آن را در منبع اصلاح کنید. صادرکننده عمداً سری‌های جدید را حذف می‌کند و برچسب‌ها را بی‌سروصدا بازنویسی نمی‌کند.

    Prometheus پس از راه‌اندازی مجدد، سری‌های قدیمی را نشان می‌دهد

    Plugin وضعیت را فقط در حافظه نگه می‌دارد. پس از راه‌اندازی مجدد Gateway، شمارنده‌ها به صفر بازنشانی می‌شوند و سنجه‌ها از مقدار گزارش‌شده بعدی خود دوباره آغاز می‌شوند. برای مدیریت صحیح بازنشانی‌ها از rate() و increase() در PromQL استفاده کنید.

    مرتبط

    Was this useful?
    On this page

    On this page