Експорт OpenTelemetry

• Діагностичні події — це структуровані внутрішньопроцесні записи, які створюють Gateway і вбудовані плагіни для запусків моделей, потоків повідомлень, сеансів, черг і exec.
• diagnostics-otel підписується на ці події та експортує їх як метрики, трасування й журнали OpenTelemetry через OTLP/HTTP, а також може дублювати записи журналу у форматі JSONL до stdout.
• Виклики постачальників отримують заголовок W3C traceparent із довіреного контексту сегмента виклику моделі OpenClaw, якщо транспорт постачальника підтримує власні заголовки. Контекст трасування, створений Plugin, не поширюється.
• Експортери підключаються лише тоді, коли ввімкнено і діагностичну поверхню, і Plugin, тому за замовчуванням внутрішньопроцесні витрати залишаються майже нульовими.

​

Швидкий початок

openclaw plugins install clawhub:@openclaw/diagnostics-otel

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
    },
  },
}

​

Експортовані сигнали

​

Довідник із конфігурації

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      tracesEndpoint: "http://otel-collector:4318/v1/traces",
      metricsEndpoint: "http://otel-collector:4318/v1/metrics",
      logsEndpoint: "http://otel-collector:4318/v1/logs",
      protocol: "http/protobuf", // grpc вимикає експорт OTLP
      serviceName: "openclaw-gateway", // якщо не задано, використовується OTEL_SERVICE_NAME, а потім "openclaw"
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      logsExporter: "otlp", // otlp | stdout | обидва
      sampleRate: 0.2, // засіб вибірки кореневих сегментів, 0.0..1.0
      flushIntervalMs: 60000, // інтервал експорту метрик (мін. 1000 мс)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
        toolDefinitions: false,
      },
    },
  },
}

​

Змінні середовища

​

Конфіденційність і захоплення вмісту

• inputMessages — вміст запиту користувача.
• outputMessages — вміст відповіді моделі.
• toolInputs — дані аргументів інструмента.
• toolOutputs — дані результатів інструмента.
• systemPrompt — складений системний запит або запит розробника.
• toolDefinitions — назви, описи та схеми інструментів моделі.

​

Вибірка та скидання

• Трасування: diagnostics.otel.sampleRate установлює TraceIdRatioBasedSampler лише для кореневого спану (0.0 відкидає все, 1.0 зберігає все). Якщо значення не задано, використовується стандартне налаштування OpenTelemetry SDK (завжди ввімкнено).
• Метрики: diagnostics.otel.flushIntervalMs (обмежується мінімальним значенням 1000); якщо значення не задано, використовується стандартний інтервал періодичного експорту SDK.
• Журнали: журнали OTLP враховують logging.level (рівень файлового журналу) та використовують шлях редагування діагностичних записів журналу, а не форматування консолі. Для інсталяцій із великим обсягом даних варто віддавати перевагу вибірці та фільтруванню колектора OTLP замість локальної вибірки. Установіть diagnostics.otel.logsExporter: "stdout", якщо ваша платформа вже передає stdout/stderr обробнику журналів і у вас немає колектора журналів OTLP. Записи stdout — це по одному об’єкту JSON у кожному рядку з ts, signal, service.name, рівнем серйозності, тілом, відредагованими атрибутами та довіреними полями трасування, якщо вони доступні.
• Кореляція файлових журналів: файлові журнали JSONL містять на верхньому рівні traceId, spanId, parentSpanId і traceFlags, коли виклик журналювання має дійсний контекст діагностичного трасування, що дає змогу обробникам журналів пов’язувати локальні рядки журналу з експортованими спанами.
• Кореляція запитів: HTTP-запити Gateway і кадри WebSocket створюють внутрішню область трасування запиту. Журнали та діагностичні події в цій області за замовчуванням успадковують трасування запиту, а спани запуску агента й виклику моделі створюються як дочірні, тому заголовки traceparent постачальника залишаються в тому самому трасуванні.
• Кореляція викликів моделі: спани openclaw.model.call за замовчуванням містять безпечні розміри компонентів запиту та атрибути токенів для кожного виклику, якщо результат постачальника надає дані про використання. openclaw.model.usage залишається спаном обліку на рівні запуску для агрегованої вартості, контексту й панелей каналів і залишається в тому самому діагностичному трасуванні, коли середовище виконання, що його створює, має довірений контекст трасування.

​

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

​

Використання моделі

• openclaw.tokens (лічильник, атрибути: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
• openclaw.cost.usd (лічильник, атрибути: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.run.duration_ms (гістограма, атрибути: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.context.tokens (гістограма, атрибути: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
• gen_ai.client.token.usage (гістограма, метрика семантичних конвенцій GenAI, атрибути: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
• gen_ai.client.operation.duration (гістограма, секунди, метрика семантичних конвенцій GenAI, атрибути: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, необов’язковий error.type)
• openclaw.model_call.duration_ms (гістограма, атрибути: openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, а також openclaw.errorCategory і openclaw.failureKind для класифікованих помилок)
• openclaw.model_call.request_bytes (гістограма, розмір у байтах UTF-8 остаточного корисного навантаження запиту до моделі; без необробленого вмісту корисного навантаження)
• openclaw.model_call.response_bytes (гістограма, розмір у байтах UTF-8 корисного навантаження потокових фрагментів відповіді; для високочастотних дельт тексту, міркувань і викликів інструментів враховуються лише додаткові байти delta; без необробленого вмісту відповіді)
• openclaw.model_call.time_to_first_byte_ms (гістограма, час до першої події потокової відповіді)
• openclaw.model.failover (лічильник, атрибути: openclaw.provider, openclaw.model, openclaw.failover.to_provider, openclaw.failover.to_model, openclaw.failover.reason, openclaw.failover.suspended, openclaw.lane)
• openclaw.skill.used (лічильник, атрибути: openclaw.skill.name, openclaw.skill.source, openclaw.skill.activation, необов’язковий openclaw.agent, необов’язковий openclaw.toolName)

​

Потік повідомлень

• openclaw.webhook.received (лічильник, атрибути: openclaw.channel, openclaw.webhook)
• openclaw.webhook.error (лічильник, атрибути: openclaw.channel, openclaw.webhook)
• openclaw.webhook.duration_ms (гістограма, атрибути: openclaw.channel, openclaw.webhook)
• openclaw.message.queued (лічильник, атрибути: openclaw.channel, openclaw.source)
• openclaw.message.received (лічильник, атрибути: openclaw.channel, openclaw.source)
• openclaw.message.dispatch.started (лічильник, атрибути: openclaw.channel, openclaw.source)
• openclaw.message.dispatch.completed (лічильник, атрибути: openclaw.channel, openclaw.outcome, openclaw.reason, openclaw.source)
• openclaw.message.dispatch.duration_ms (гістограма, атрибути: openclaw.channel, openclaw.outcome, openclaw.reason, openclaw.source)
• openclaw.message.processed (лічильник, атрибути: openclaw.channel, openclaw.outcome)
• openclaw.message.duration_ms (гістограма, атрибути: openclaw.channel, openclaw.outcome)
• openclaw.message.delivery.started (лічильник, атрибути: openclaw.channel, openclaw.delivery.kind)
• openclaw.message.delivery.duration_ms (гістограма, атрибути: openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory)

​

Розмова

• openclaw.talk.event (лічильник, атрибути: openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
• openclaw.talk.event.duration_ms (гістограма, атрибути: такі самі, як у openclaw.talk.event; створюється, коли подія розмови повідомляє тривалість)
• openclaw.talk.audio.bytes (гістограма, атрибути: такі самі, як у openclaw.talk.event; створюється для подій аудіокадрів розмови, що повідомляють довжину в байтах)

​

Черги та сеанси

• openclaw.queue.lane.enqueue (лічильник, атрибути: openclaw.lane)
• openclaw.queue.lane.dequeue (лічильник, атрибути: openclaw.lane)
• openclaw.queue.depth (гістограма, атрибути: openclaw.lane або openclaw.channel=heartbeat)
• openclaw.queue.wait_ms (гістограма, атрибути: openclaw.lane)
• openclaw.session.state (лічильник, атрибути: openclaw.state, openclaw.reason)
• openclaw.session.stuck (лічильник, атрибути: openclaw.state; створюється для застарілого облікового стану сеансу, який можна відновити)
• openclaw.session.stuck_age_ms (гістограма, атрибути: openclaw.state; створюється для застарілого облікового стану сеансу, який можна відновити)
• openclaw.session.turn.created (лічильник, атрибути: openclaw.agent, openclaw.channel, openclaw.trigger)
• openclaw.session.recovery.requested (лічильник, атрибути: openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
• openclaw.session.recovery.completed (лічильник, атрибути: openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
• openclaw.session.recovery.age_ms (гістограма, атрибути: такі самі, як у відповідного лічильника відновлення)
• openclaw.run.attempt (лічильник, атрибути: openclaw.attempt)

​

Телеметрія активності сеансів

• session.long_running: активна вбудована робота, виклики моделі або виклики інструментів усе ще виконуються. Належні власнику виклики моделі, які не надають сигналів довше за diagnostics.stuckSessionWarnMs, також позначаються як довготривалі до diagnostics.stuckSessionAbortMs, щоб повільні або непотокові постачальники моделей не виглядали як завислі сеанси Gateway, доки можливе спостереження за перериванням.
• session.stalled: активна робота існує, але активний запуск останнім часом не повідомляв про прогрес. Належні власнику виклики моделі переходять із session.long_running до session.stalled після досягнення diagnostics.stuckSessionAbortMs; застаріла активність моделі чи інструмента без власника не вважається нешкідливою довготривалою роботою. Спочатку завислі вбудовані запуски лише спостерігаються, а потім після diagnostics.stuckSessionAbortMs без прогресу перериваються з очікуванням завершення, щоб наступні ходи в черзі смуги могли відновитися. Якщо значення не задано, поріг переривання за замовчуванням дорівнює безпечнішому розширеному вікну: щонайменше 5 хвилин і трикратне значення diagnostics.stuckSessionWarnMs.
• session.stuck: застарілий обліковий стан сеансу без активної роботи або неактивний сеанс у черзі із застарілою активністю моделі чи інструмента без власника. Це негайно звільняє відповідну смугу сеансу після проходження перевірок відновлення.

• openclaw.liveness.warning (лічильник, атрибути: openclaw.liveness.reason)
• openclaw.liveness.event_loop_delay_p99_ms (гістограма, атрибути: openclaw.liveness.reason)
• openclaw.liveness.event_loop_delay_max_ms (гістограма, атрибути: openclaw.liveness.reason)
• openclaw.liveness.event_loop_utilization (гістограма, атрибути: openclaw.liveness.reason)
• openclaw.liveness.cpu_core_ratio (гістограма, атрибути: openclaw.liveness.reason)

​

Життєвий цикл тестового середовища

• openclaw.harness.duration_ms (гістограма, атрибути: openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.harness.phase у разі помилок)

​

Виконання інструментів і виявлення циклів

• openclaw.tool.execution.duration_ms (гістограма, атрибути: gen_ai.tool.name, openclaw.toolName, openclaw.tool.source, openclaw.tool.owner, openclaw.tool.params.kind, а також openclaw.errorCategory у разі помилок)
• openclaw.tool.execution.blocked (лічильник, атрибути: gen_ai.tool.name, openclaw.toolName, openclaw.tool.source, openclaw.tool.owner, openclaw.tool.params.kind, openclaw.deniedReason)
• openclaw.tool.loop (лічильник, атрибути: openclaw.toolName, openclaw.loop.level, openclaw.loop.action, openclaw.loop.detector, openclaw.loop.count, необов’язковий openclaw.loop.paired_tool; створюється, коли виявлено повторюваний цикл викликів інструмента)

​

Виконання команд

• openclaw.exec.duration_ms (гістограма, атрибути: openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

​

Внутрішня діагностика (пам’ять, корисні навантаження, стан експортерів)

• openclaw.payload.large (лічильник, атрибути: openclaw.payload.surface, openclaw.payload.action, openclaw.channel, openclaw.plugin, openclaw.reason)
• openclaw.payload.large_bytes (гістограма, атрибути: такі самі, як у openclaw.payload.large)
• openclaw.memory.rss_bytes / openclaw.memory.heap_used_bytes / openclaw.memory.heap_total_bytes / openclaw.memory.external_bytes / openclaw.memory.array_buffers_bytes (гістограми, без атрибутів; зразки пам’яті процесу)
• openclaw.memory.pressure (лічильник, атрибути: openclaw.memory.level, openclaw.memory.reason)
• openclaw.diagnostic.async_queue.dropped (лічильник, атрибути: openclaw.diagnostic.async_queue.drop_class; відкидання через зворотний тиск внутрішньої діагностичної черги)
• openclaw.telemetry.exporter.events (лічильник, атрибути: openclaw.exporter, openclaw.signal, openclaw.status, необов’язковий openclaw.reason, необов’язковий openclaw.errorCategory; власна телеметрія життєвого циклу та збоїв експортера)

​

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

• openclaw.model.usage
  • openclaw.channel, openclaw.provider, openclaw.model
  • openclaw.tokens.* (input/output/cache_read/cache_write/total)
  • gen_ai.system за замовчуванням або gen_ai.provider.name, якщо ввімкнено найновіші семантичні угоди GenAI
  • gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.*
• openclaw.run
  • openclaw.outcome, openclaw.channel, openclaw.provider, openclaw.model, openclaw.errorCategory
• openclaw.model.call
  • gen_ai.system за замовчуванням або gen_ai.provider.name, якщо ввімкнено найновіші семантичні угоди GenAI
  • gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
  • openclaw.errorCategory, error.type і необов’язковий openclaw.failureKind у разі помилок
  • openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
  • openclaw.model_call.prompt.input_messages_count, openclaw.model_call.prompt.input_messages_chars, openclaw.model_call.prompt.system_prompt_chars, openclaw.model_call.prompt.tool_definitions_count, openclaw.model_call.prompt.tool_definitions_chars, openclaw.model_call.prompt.total_chars (лише безпечні розміри компонентів, без тексту запиту)
  • openclaw.model_call.usage.* і gen_ai.usage.*, коли результат виклику моделі містить дані про використання від постачальника для цього окремого виклику
  • Подія проміжку openclaw.provider.request з атрибутом openclaw.upstreamRequestIdHash (обмеженим, на основі хешу), коли результат від зовнішнього постачальника містить ідентифікатор запиту; необроблені ідентифікатори ніколи не експортуються
  • З OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental проміжки викликів моделі використовують найновішу назву проміжку логічного висновку GenAI {gen_ai.operation.name} {gen_ai.request.model} і тип проміжку CLIENT замість openclaw.model.call.
• openclaw.harness.run
  • openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
  • Після завершення: openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
  • У разі помилки: openclaw.harness.phase, openclaw.errorCategory, необов’язковий openclaw.harness.cleanup_failed
• openclaw.tool.execution
  • gen_ai.tool.name, gen_ai.operation.name (execute_tool), openclaw.toolName, openclaw.tool.source, необов’язкові gen_ai.tool.call.id, openclaw.tool.owner, openclaw.tool.params.*
  • Необов’язкові openclaw.errorCategory/openclaw.errorCode у разі помилок, openclaw.deniedReason і openclaw.outcome=blocked, коли виконання заборонено політикою або пісочницею
• openclaw.exec
  • openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.exit_signal, openclaw.exec.timed_out
• openclaw.webhook.processed
  • openclaw.channel, openclaw.webhook
• openclaw.webhook.error
  • openclaw.channel, openclaw.webhook, openclaw.error
• openclaw.message.processed
  • openclaw.channel, openclaw.outcome, openclaw.reason
• openclaw.message.delivery
  • openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory, openclaw.delivery.result_count
• openclaw.session.stuck
  • openclaw.state, openclaw.ageMs, openclaw.queueDepth
• openclaw.context.assembled
  • openclaw.prompt.size, openclaw.history.size, openclaw.context.tokens, openclaw.errorCategory (без вмісту запиту, історії, відповіді або ключа сеансу)
• openclaw.tool.loop
  • openclaw.toolName, openclaw.loop.level, openclaw.loop.action, openclaw.loop.detector, openclaw.loop.count, необов’язковий openclaw.loop.paired_tool (без повідомлень циклу, параметрів або результатів інструмента)
• openclaw.memory.pressure
  • openclaw.memory.level, openclaw.memory.reason, openclaw.memory.rss_bytes, openclaw.memory.heap_used_bytes, openclaw.memory.heap_total_bytes, openclaw.memory.external_bytes, openclaw.memory.array_buffers_bytes, необов’язкові openclaw.memory.threshold_bytes/openclaw.memory.rss_growth_bytes/openclaw.memory.window_ms

​

Каталог діагностичних подій

• model.usage — токени, вартість, тривалість, контекст, постачальник/модель/канал, ідентифікатори сеансів. usage — облік постачальника/ходу для вартості й телеметрії; context.used — поточний знімок запиту/контексту, який може бути меншим за usage.total постачальника, якщо використовуються кешовані вхідні дані або виклики циклу інструментів.

• webhook.received / webhook.processed / webhook.error
• message.queued / message.processed
• message.delivery.started / message.delivery.completed / message.delivery.error

• queue.lane.enqueue / queue.lane.dequeue
• session.state / session.long_running / session.stalled / session.stuck
• run.attempt / run.progress
• diagnostic.heartbeat (агреговані лічильники: вебхуки/черга/сеанс)

• harness.run.started / harness.run.completed / harness.run.error — життєвий цикл кожного запуску середовища виконання агента. Містить harnessId, необов’язковий pluginId, постачальника/модель/канал та ідентифікатор запуску. Після завершення додаються durationMs, outcome, необов’язкові resultClassification, yieldDetected і лічильники itemLifecycle. У разі помилки додаються phase (prepare/start/send/resolve/cleanup), errorCategory і необов’язковий cleanupFailed.

• exec.process.completed — кінцевий результат, тривалість, ціль, режим, код виходу та тип помилки. Текст команди й робочі каталоги не включаються.
• exec.approval.followup_suppressed — застаріле подальше повідомлення про схвалення відкинуто після переприв’язування сеансу. Містить approvalId, reason (session_rebound), phase (direct_delivery або gateway_preflight) і часову позначку диспетчера. Ключі сеансів, маршрути й текст команди не включаються.

​

Без експортера

{
  diagnostics: { enabled: true },
}

{
  diagnostics: { flags: ["telegram.http"] },
}

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

​

Вимкнення

{
  diagnostics: { otel: { enabled: false } },
}

​

Пов’язані матеріали

• Журналювання — файлові журнали, консольний вивід, перегляд журналів через CLI та вкладка журналів в інтерфейсі керування
• Внутрішня реалізація журналювання Gateway — стилі журналів WS, префікси підсистем і захоплення консолі
• Діагностичні прапорці — прапорці цільового налагоджувального журналювання
• Експорт діагностики — інструмент пакета підтримки для оператора (окремо від експорту OTEL)
• Довідник із конфігурації — повний довідник полів diagnostics.*