Экспорт OpenTelemetry

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

​

Быстрый старт

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 | both
      sampleRate: 0.2, // сэмплер корневых диапазонов, 0.0..1.0
      flushIntervalMs: 60000, // интервал экспорта метрик (минимум 1000ms)
      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)

​

Talk

• 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; создаётся, когда событие Talk сообщает длительность)
• openclaw.talk.audio.bytes (гистограмма, атрибуты: те же, что у openclaw.talk.event; создаётся для событий аудиокадров Talk, сообщающих длину в байтах)

​

Очереди и сеансы

• 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 минут и в 3 раза больше 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; создаётся при обнаружении повторяющегося цикла вызовов инструментов)

​

Exec

• 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.* (ввод/вывод/чтение из кеша/запись в кеш/всего)
  • 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 и вкладка журналов в Control UI
• Внутреннее устройство журналирования Gateway — стили журналов WS, префиксы подсистем и захват консольного вывода
• Диагностические флаги — флаги целевого отладочного журналирования
• Экспорт диагностики — операторский инструмент создания пакета поддержки (отдельный от экспорта OTEL)
• Справочник по конфигурации — полный справочник по полям diagnostics.*