Експорт OpenTelemetry

OpenClaw експортує діагностику через вбудований Plugin diagnostics-otel, використовуючи OTLP/HTTP (protobuf). Будь-який колектор або бекенд, що приймає OTLP/HTTP, працює без змін у коді. Для локальних файлових журналів і способів їх читання див. Журналювання.

Як це працює разом

Події діагностики — це структуровані внутрішньопроцесні записи, які створюються Gateway і вбудованими плагінами для запусків моделей, потоку повідомлень, сесій, черг та exec.
Plugin diagnostics-otel підписується на ці події та експортує їх як OpenTelemetry метрики, трасування і журнали через OTLP/HTTP.
Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і сам plugin, тому внутрішньопроцесні накладні витрати за замовчуванням залишаються майже нульовими.

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

{
  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,
    },
  },
}

Ви також можете ввімкнути plugin з CLI:

openclaw plugins enable diagnostics-otel

protocol наразі підтримує лише http/protobuf. grpc ігнорується.

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

Сигнал	Що до нього входить
Метрики	Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черг, стану сесій, exec і тиску на пам’ять.
Трасування	Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів.
Журнали	Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`.

Перемикайте traces, metrics і logs незалежно. Усі три за замовчуванням увімкнені, коли diagnostics.otel.enabled має значення true.

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

{
  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 is ignored
      serviceName: "openclaw-gateway",
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },
  },
}

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

Variable	Призначення
`OTEL_EXPORTER_OTLP_ENDPOINT`	Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Перевизначення кінцевих точок для окремих сигналів, які використовуються, коли відповідний ключ конфігурації `diagnostics.otel.*Endpoint` не задано. Конфігурація для конкретного сигналу має пріоритет над змінною середовища для конкретного сигналу, яка має пріоритет над спільною кінцевою точкою.
`OTEL_SERVICE_NAME`	Перевизначає `diagnostics.otel.serviceName`.
`OTEL_EXPORTER_OTLP_PROTOCOL`	Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`).
`OTEL_SEMCONV_STABILITY_OPT_IN`	Встановіть значення `gen_ai_latest_experimental`, щоб надсилати останній експериментальний атрибут GenAI span (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені, низькокардинальні семантичні атрибути незалежно від цього.
`OPENCLAW_OTEL_PRELOADED`	Встановіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`.

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

Необроблений вміст моделей/інструментів не експортується за замовчуванням. Спани містять обмежені ідентифікатори (channel, provider, model, категорія помилки, лише хешовані request id) і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, вихідні дані інструментів або ключі сесій. Встановлюйте diagnostics.otel.captureContent.* у true лише тоді, коли ваш колектор і політика зберігання схвалені для тексту промптів, відповідей, інструментів або system prompt. Кожен підключ окремо вмикається за принципом opt-in:

inputMessages — вміст запитів користувача.
outputMessages — вміст відповідей моделі.
toolInputs — корисні навантаження аргументів інструментів.
toolOutputs — корисні навантаження результатів інструментів.
systemPrompt — зібраний system/developer prompt.

Коли ввімкнено будь-який підключ, спани моделей та інструментів отримують обмежені, редаговані атрибути openclaw.content.* лише для цього класу.

Семплювання та скидання

Трасування: diagnostics.otel.sampleRate (лише для root span, 0.0 відкидає все, 1.0 зберігає все).
Метрики: diagnostics.otel.flushIntervalMs (мінімум 1000).
Журнали: OTLP-журнали враховують logging.level (рівень файлового журналу). Редагування консолі не застосовується до OTLP-журналів. Для інсталяцій із великим обсягом краще використовувати семплювання/фільтрацію на колекторі OTLP, а не локальне семплювання.

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

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

openclaw.tokens (лічильник, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model)
openclaw.cost.usd (лічильник, attrs: openclaw.channel, openclaw.provider, openclaw.model)
openclaw.run.duration_ms (гістограма, attrs: openclaw.channel, openclaw.provider, openclaw.model)
openclaw.context.tokens (гістограма, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
gen_ai.client.token.usage (гістограма, метрика GenAI semantic conventions, attrs: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
gen_ai.client.operation.duration (гістограма, секунди, метрика GenAI semantic conventions, attrs: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, необов’язково error.type)

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

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

Черги та сесії

openclaw.queue.lane.enqueue (лічильник, attrs: openclaw.lane)
openclaw.queue.lane.dequeue (лічильник, attrs: openclaw.lane)
openclaw.queue.depth (гістограма, attrs: openclaw.lane або openclaw.channel=heartbeat)
openclaw.queue.wait_ms (гістограма, attrs: openclaw.lane)
openclaw.session.state (лічильник, attrs: openclaw.state, openclaw.reason)
openclaw.session.stuck (лічильник, attrs: openclaw.state)
openclaw.session.stuck_age_ms (гістограма, attrs: openclaw.state)
openclaw.run.attempt (лічильник, attrs: openclaw.attempt)

Exec

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

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

openclaw.memory.heap_used_bytes (гістограма, attrs: openclaw.memory.kind)
openclaw.memory.rss_bytes (гістограма)
openclaw.memory.pressure (лічильник, attrs: openclaw.memory.level)
openclaw.tool.loop.iterations (лічильник, attrs: openclaw.toolName, openclaw.outcome)
openclaw.tool.loop.duration_ms (гістограма, attrs: openclaw.toolName, openclaw.outcome)

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

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 semantic conventions
- 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 semantic conventions
- gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
- openclaw.provider.request_id_hash (обмежений хеш на основі SHA від upstream request id провайдера; сирі id не експортуються)
openclaw.tool.execution
- gen_ai.tool.name, openclaw.toolName, openclaw.errorCategory, openclaw.tool.params.*
openclaw.exec
- openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.timed_out
openclaw.webhook.processed
- openclaw.channel, openclaw.webhook, openclaw.chatId
openclaw.webhook.error
- openclaw.channel, openclaw.webhook, openclaw.chatId, openclaw.error
openclaw.message.processed
- openclaw.channel, openclaw.outcome, openclaw.chatId, openclaw.messageId, 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 (без вмісту prompt, history, response або ключів сесії)
openclaw.tool.loop
- openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (без повідомлень циклу, params або виводу інструмента)
openclaw.memory.pressure
- openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

Коли захоплення вмісту явно ввімкнено, спани моделей та інструментів також можуть містити обмежені, редаговані атрибути openclaw.content.* для конкретних класів вмісту, які ви явно ввімкнули.

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

Події нижче лежать в основі метрик і спанів, наведених вище. Plugins також можуть підписуватися на них напряму без експорту OTLP. Використання моделі

model.usage — токени, вартість, тривалість, контекст, провайдер/модель/channel, id сесій. usage — це облік провайдера/ходу для вартості та телеметрії; context.used — це поточний знімок prompt/context і він може бути меншим за 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.stuck
run.attempt
diagnostic.heartbeat (агреговані лічильники: webhook/черга/сесія)

Exec

exec.process.completed — підсумковий результат, тривалість, ціль, режим, код виходу та тип збою. Текст команди й робочі каталоги не включаються.

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

Ви можете зберегти події діагностики доступними для plugins або користувацьких приймачів без запуску diagnostics-otel:

{
  diagnostics: { enabled: true },
}

Для цільового виводу налагодження без підвищення logging.level використовуйте прапорці діагностики. Прапорці нечутливі до регістру та підтримують wildcard-и (наприклад, telegram.* або *):

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

Або як одноразове перевизначення через env:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

Вивід прапорців потрапляє до стандартного файла журналу (logging.file) і все ще редагується logging.redactSensitive. Повний посібник: Прапорці діагностики.

Вимкнення

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

Ви також можете не додавати diagnostics-otel до plugins.allow або виконати openclaw plugins disable diagnostics-otel.

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

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

Gateway

Remote access

Security

Nodes and media

Web interfaces

Експорт OpenTelemetry

Як це працює разом

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

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

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

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

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

Семплювання та скидання

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

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

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

Черги та сесії

Exec

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

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

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

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

Вимкнення

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

Gateway

Remote access

Security

Nodes and media

Web interfaces

​Як це працює разом

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

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

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

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

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

​Семплювання та скидання

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

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

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

​Черги та сесії

​Exec

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

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

​Каталог подій діагностики

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

​Вимкнення

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

Як це працює разом

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

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

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

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

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

Семплювання та скидання

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

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

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

Черги та сесії

Exec

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

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

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

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

Вимкнення

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