English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Gateway

Метрики Prometheus

OmeniaClaw може надавати діагностичні метрики через офіційний Plugin diagnostics-prometheus. Він слухає довірені внутрішні діагностичні події та формує текстову кінцеву точку Prometheus за адресою:

text
GET /api/diagnostics/prometheus

Тип вмісту: text/plain; version=0.0.4; charset=utf-8, стандартний формат експозиції Prometheus.

Для трасувань, журналів, OTLP push та семантичних атрибутів OpenTelemetry GenAI див. експорт OpenTelemetry.

Швидкий старт

  • Install the plugin

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

  • Enable the plugin

    Config

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

    CLI

    bash
    OmeniaClaw plugins enable diagnostics-prometheus

  • Restart the Gateway

    HTTP-маршрут реєструється під час запуску Plugin, тому перезавантажте після ввімкнення.

  • Scrape the protected route

    Надішліть ту саму автентифікацію Gateway, яку використовують ваші клієнти оператора:

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

  • Wire Prometheus

    yaml
    # prometheus.ymlscrape_configs:  - job_name: OmeniaClaw    scrape_interval: 30s    metrics_path: /api/diagnostics/prometheus    authorization:      credentials_file: /etc/prometheus/OmeniaClaw-gateway-token    static_configs:      - targets: ["OmeniaClaw-gateway:18789"]

    • Експортовані метрики

    Метрика Тип Мітки
    OmeniaClaw_run_completed_total counter channel, model, outcome, provider, trigger
    OmeniaClaw_run_duration_seconds histogram channel, model, outcome, provider, trigger
    OmeniaClaw_model_call_total counter api, error_category, model, outcome, provider, transport
    OmeniaClaw_model_call_duration_seconds histogram api, error_category, model, outcome, provider, transport
    OmeniaClaw_model_tokens_total counter agent, channel, model, provider, token_type
    OmeniaClaw_gen_ai_client_token_usage histogram model, provider, token_type
    OmeniaClaw_model_cost_usd_total counter agent, channel, model, provider
    OmeniaClaw_tool_execution_total counter error_category, outcome, params_kind, tool
    OmeniaClaw_tool_execution_duration_seconds histogram error_category, outcome, params_kind, tool
    OmeniaClaw_harness_run_total counter channel, error_category, harness, model, outcome, phase, plugin, provider
    OmeniaClaw_harness_run_duration_seconds histogram channel, error_category, harness, model, outcome, phase, plugin, provider
    OmeniaClaw_message_processed_total counter channel, outcome, reason
    OmeniaClaw_message_processed_duration_seconds histogram channel, outcome, reason
    OmeniaClaw_message_delivery_started_total counter channel, delivery_kind
    OmeniaClaw_message_delivery_total counter channel, delivery_kind, error_category, outcome
    OmeniaClaw_message_delivery_duration_seconds histogram channel, delivery_kind, error_category, outcome
    OmeniaClaw_talk_event_total counter brain, event_type, mode, provider, transport
    OmeniaClaw_talk_event_duration_seconds histogram brain, event_type, mode, provider, transport
    OmeniaClaw_talk_audio_bytes histogram brain, event_type, mode, provider, transport
    OmeniaClaw_queue_lane_size gauge lane
    OmeniaClaw_queue_lane_wait_seconds histogram lane
    OmeniaClaw_session_state_total counter reason, state
    OmeniaClaw_session_queue_depth gauge state
    OmeniaClaw_session_recovery_total counter action, active_work_kind, state, status
    OmeniaClaw_session_recovery_age_seconds histogram action, active_work_kind, state, status
    OmeniaClaw_memory_bytes gauge kind
    OmeniaClaw_memory_rss_bytes histogram немає
    OmeniaClaw_memory_pressure_total counter level, reason
    OmeniaClaw_telemetry_exporter_total counter exporter, reason, signal, status
    OmeniaClaw_prometheus_series_dropped_total counter немає

    Політика міток

    Bounded, low-cardinality labels

    Мітки Prometheus залишаються обмеженими та з низькою кардинальністю. Експортер не видає сирі діагностичні ідентифікатори, як-от runId, sessionKey, sessionId, callId, toolCallId, ідентифікатори повідомлень, ідентифікатори чатів або ідентифікатори запитів провайдера.

    Значення міток редагуються та мають відповідати політиці OmeniaClaw щодо символів із низькою кардинальністю. Значення, які не відповідають політиці, замінюються на unknown, other або none, залежно від метрики.

    Обмеження рядів і облік переповнення

    Експортер обмежує збережені часові ряди в пам’яті 2048 рядами сукупно для лічильників, вимірювачів і гістограм. Нові ряди понад це обмеження відкидаються, а OmeniaClaw_prometheus_series_dropped_total збільшується на одиницю щоразу.

    Відстежуйте цей лічильник як чіткий сигнал, що атрибут вище за потоком пропускає значення з високою кардинальністю. Експортер ніколи не підвищує обмеження автоматично; якщо лічильник зростає, виправте джерело, а не вимикайте обмеження.

    Що ніколи не з’являється у виводі Prometheus
    • текст промпта, текст відповіді, вхідні дані інструментів, вихідні дані інструментів, системні промпти
    • стенограми розмов, аудіо payloads, ідентифікатори викликів, ідентифікатори кімнат, токени передавання, ідентифікатори ходів і необроблені ідентифікатори сеансів
    • необроблені ідентифікатори запитів провайдера (лише обмежені хеші, де застосовно, на spans — ніколи в метриках)
    • ключі сеансів і ідентифікатори сеансів
    • імена хостів, шляхи до файлів, секретні значення

    Рецепти PromQL

    promql
    # Tokens per minute, split by providersum by (provider) (rate(OmeniaClaw_model_tokens_total[1m])) # Spend (USD) over the last hour, by modelsum by (model) (increase(OmeniaClaw_model_cost_usd_total[1h])) # 95th percentile model run durationhistogram_quantile(  0.95,  sum by (le, provider, model)    (rate(OmeniaClaw_run_duration_seconds_bucket[5m]))) # Queue wait time SLO (95p under 2s)histogram_quantile(  0.95,  sum by (le, lane) (rate(OmeniaClaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # Dropped Prometheus series (cardinality alarm)increase(OmeniaClaw_prometheus_series_dropped_total[15m]) > 0

    Вибір між експортом Prometheus і OpenTelemetry

    OmeniaClaw підтримує обидві поверхні незалежно. Ви можете запускати одну з них, обидві або жодну.

    diagnostics-prometheus

    • Модель pull: Prometheus зчитує /api/diagnostics/prometheus.
    • Зовнішній колектор не потрібен.
    • Автентифікація через звичайну автентифікацію Gateway.
    • Поверхня містить лише метрики (без трасувань або логів).
    • Найкраще підходить для стеків, уже стандартизованих на Prometheus + Grafana.

    diagnostics-otel

    • Модель push: OmeniaClaw надсилає OTLP/HTTP до колектора або OTLP-сумісного бекенда.
    • Поверхня містить метрики, трасування й логи.
    • Підключається до Prometheus через OpenTelemetry Collector (експортер prometheus або prometheusremotewrite), коли потрібні обидва варіанти.
    • Див. Експорт OpenTelemetry для повного каталогу.

    Усунення несправностей

    Порожнє тіло відповіді
    • Перевірте diagnostics.enabled: true у конфігурації.
    • Підтвердьте, що Plugin увімкнено й завантажено, за допомогою OmeniaClaw plugins list --enabled.
    • Згенеруйте трохи трафіку; лічильники й гістограми виводять рядки лише після принаймні однієї події.
    401 / не авторизовано

    Ендпоінт потребує області оператора Gateway (auth: "gateway" з gatewayRuntimeScopeSurface: "trusted-operator"). Використовуйте той самий токен або пароль, який Prometheus використовує для будь-якого іншого операторського маршруту Gateway. Публічного режиму без автентифікації немає.

    `OmeniaClaw_prometheus_series_dropped_total` зростає

    Новий атрибут перевищує обмеження в 2048 рядів. Перегляньте останні метрики на наявність неочікувано висококардинальної мітки та виправте її в джерелі. Експортер навмисно відкидає нові ряди замість того, щоб непомітно переписувати мітки.

    Prometheus показує застарілі ряди після перезапуску

    Plugin зберігає стан лише в пам’яті. Після перезапуску Gateway лічильники скидаються до нуля, а вимірювачі починають знову з наступного повідомленого значення. Використовуйте PromQL rate() і increase(), щоб коректно обробляти скидання.

    Пов’язане

    Was this useful?
    On this page

    On this page