diff --git a/docs/uk/gateway/opentelemetry.md b/docs/uk/gateway/opentelemetry.md index 259e657c0..9147e61b1 100644 --- a/docs/uk/gateway/opentelemetry.md +++ b/docs/uk/gateway/opentelemetry.md @@ -1,35 +1,35 @@ --- read_when: - - Ви хочете надсилати використання моделей OpenClaw, потік повідомлень або метрики сесії до колектора OpenTelemetry - - Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого бекенда OTLP - - Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати дашборди чи сповіщення -summary: Експортуйте діагностику OpenClaw до будь-якого колектора OpenTelemetry через Plugin diagnostics-otel (OTLP/HTTP) + - Ви хочете надсилати дані про використання моделей OpenClaw, потік повідомлень або метрики сеансів до колектора OpenTelemetry + - Ви налаштовуєте передавання трасувань, метрик або журналів до Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого бекенда OTLP + - Вам потрібні точні назви метрик, назв спанів або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення +summary: Експортуйте діагностичні дані OpenClaw до будь-якого колектора OpenTelemetry через Plugin diagnostics-otel (OTLP/HTTP) title: Експорт OpenTelemetry x-i18n: - generated_at: "2026-04-26T18:13:26Z" + generated_at: "2026-04-26T19:56:13Z" model: gpt-5.4 provider: openai - source_hash: 1301b5d8e7852b8e94be3a5928b5075c0109a3f3879033e52efcd1a75098cac9 + source_hash: 379e0cada90888a3703785147d62ebe418f48216169577443cc8c95dc2a9fff8 source_path: gateway/opentelemetry.md workflow: 15 --- -OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel`, -використовуючи **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, -працює без змін у коді. Про локальні файлові журнали й те, як їх читати, дивіться +OpenClaw експортує діагностичні дані через вбудований Plugin `diagnostics-otel` +з використанням **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, +працює без змін у коді. Про локальні файлові журнали та способи їх читання див. [Журналювання](/uk/logging). ## Як це працює разом -- **Діагностичні події** — це структуровані внутрішньопроцесні записи, які надсилають - Gateway і вбудовані плагіни для запусків моделей, потоку повідомлень, сесій, черг +- **Діагностичні події** — це структуровані внутрішньопроцесні записи, які створюються + Gateway і вбудованими plugins для запусків моделей, потоку повідомлень, сеансів, черг та exec. -- **Plugin `diagnostics-otel`** підписується на ці події й експортує їх як - OpenTelemetry **метрики**, **трасування** та **журнали** через OTLP/HTTP. -- **Виклики провайдера** отримують заголовок W3C `traceparent` із довіреного - контексту спана виклику моделі OpenClaw, коли транспорт провайдера приймає - власні заголовки. Контекст трасування, надісланий Plugin, не поширюється. -- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і плагін, +- **Plugin `diagnostics-otel`** підписується на ці події та експортує їх як + OpenTelemetry **метрики**, **трасування** і **журнали** через OTLP/HTTP. +- **Виклики провайдера** отримують заголовок W3C `traceparent` із + контексту довіреного span виклику моделі OpenClaw, коли транспорт провайдера приймає користувацькі + заголовки. Контекст трасування, створений Plugin, не поширюється. +- Експортери підключаються лише тоді, коли ввімкнено і діагностичну поверхню, і Plugin, тому внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими. ## Швидкий початок @@ -59,7 +59,7 @@ OpenClaw експортує діагностику через вбудовани } ``` -Ви також можете ввімкнути плагін із CLI: +Ви також можете ввімкнути Plugin з CLI: ```bash openclaw plugins enable diagnostics-otel @@ -73,12 +73,12 @@ openclaw plugins enable diagnostics-otel | Сигнал | Що до нього входить | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| **Метрики** | Лічильники й гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сесії, exec і тиску на пам’ять. | -| **Трасування** | Спани для використання моделей, викликів моделей, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту й циклів інструментів. | -| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | +| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сеансів, exec і тиску пам’яті. | +| **Трасування** | Spans для використання моделей, викликів моделей, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | +| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | -Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три параметри за замовчуванням -увімкнені, коли `diagnostics.otel.enabled` має значення true. +Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три параметри за замовчуванням увімкнені, +коли `diagnostics.otel.enabled` має значення true. ## Довідник конфігурації @@ -115,48 +115,52 @@ openclaw plugins enable diagnostics-otel ### Змінні середовища -| Змінна | Призначення | -| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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` не задано. Конфігурація конкретного сигналу має вищий пріоритет за env для конкретного сигналу, яке, своєю чергою, має вищий пріоритет за спільну кінцеву точку. | +| Змінна | Призначення | +| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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` не задано. Конфігурація для конкретного сигналу має пріоритет над env для конкретного сигналу, а env для конкретного сигналу — над спільною кінцевою точкою. | | `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає протокол передавання (сьогодні враховується лише `http/protobuf`). | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Встановіть значення `gen_ai_latest_experimental`, щоб надсилати останній експериментальний атрибут спана GenAI (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | -| `OPENCLAW_OTEL_PRELOADED` | Встановіть значення `1`, якщо інше попереднє завантаження або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді плагін пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики й враховує `traces`/`metrics`/`logs`. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (наразі враховується лише `http/protobuf`). | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Установіть значення `gen_ai_latest_experimental`, щоб виводити найновіший експериментальний атрибут span GenAI (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | +| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді Plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає діагностичні слухачі та враховує `traces`/`metrics`/`logs`. | ## Конфіденційність і захоплення вмісту -Необроблений вміст моделей та інструментів **не** експортується за замовчуванням. Спани містять -обмежені ідентифікатори (канал, провайдер, модель, категорія помилки, ідентифікатори запитів -лише як хеш) і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, -вихідні дані інструментів або ключі сесії. +Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Spans містять обмежені +ідентифікатори (канал, провайдер, модель, категорію помилки, ідентифікатори запитів лише у вигляді хешів) +і ніколи не включають текст промпта, текст відповіді, вхідні дані інструментів, вихідні дані інструментів +або ключі сеансів. -Вихідні запити до моделей можуть містити заголовок W3C `traceparent`. Цей заголовок -генерується лише з діагностичного контексту трасування, що належить OpenClaw, для активного виклику -моделі. Наявні заголовки `traceparent`, передані викликачем, замінюються, тому плагіни або -власні параметри провайдера не можуть підробити походження міжсервісного трасування. +Вихідні запити до моделі можуть містити заголовок W3C `traceparent`. Цей заголовок +генерується лише з контексту діагностичного трасування, що належить OpenClaw, для активного виклику +моделі. Наявні заголовки `traceparent`, передані викликачем, замінюються, тому plugins або +користувацькі параметри провайдера не можуть підробити походження трасування між сервісами. -Встановлюйте `diagnostics.otel.captureContent.*` у `true` лише тоді, коли ваш колектор і -політика зберігання схвалені для тексту промптів, відповідей, інструментів або системних промптів. -Кожен підключ є незалежно opt-in: +Установлюйте `diagnostics.otel.captureContent.*` у `true` лише тоді, коли ваш колектор і +політика зберігання дозволяють текст промптів, відповідей, інструментів або системних промптів. +Кожен підключ є окремо opt-in: -- `inputMessages` — вміст користувацького промпту. +- `inputMessages` — вміст користувацького промпта. - `outputMessages` — вміст відповіді моделі. -- `toolInputs` — корисні навантаження аргументів інструментів. -- `toolOutputs` — корисні навантаження результатів інструментів. -- `systemPrompt` — зібраний системний/developer промпт. +- `toolInputs` — корисне навантаження аргументів інструментів. +- `toolOutputs` — корисне навантаження результатів інструментів. +- `systemPrompt` — зібраний системний/розробницький промпт. -Коли будь-який підключ увімкнено, спани моделей та інструментів отримують обмежені, відредаговані +Коли ввімкнено будь-який підключ, spans моделі та інструментів отримують обмежені, відредаговані атрибути `openclaw.content.*` лише для цього класу. ## Семплювання та скидання -- **Трасування:** `diagnostics.otel.sampleRate` (лише для кореневого спана, `0.0` відкидає все, - `1.0` зберігає все). +- **Трасування:** `diagnostics.otel.sampleRate` (лише для root-span, `0.0` відкидає всі, + `1.0` зберігає всі). - **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`). - **Журнали:** журнали OTLP враховують `logging.level` (рівень файлового журналу). Вони використовують - шлях редагування діагностичних записів журналу, а не форматування консолі. Для інсталяцій із - великим обсягом даних краще використовувати семплювання/фільтрацію колектора OTLP, а не локальне семплювання. + шлях редагування діагностичних записів журналу, а не форматування консолі. Для інсталяцій із великим обсягом + даних варто віддавати перевагу семплюванню/фільтрації в колекторі OTLP замість локального семплювання. +- **Кореляція файлових журналів:** журнали JSONL включають поля верхнього рівня `traceId`, + `spanId`, `parentSpanId` і `traceFlags`, коли виклик журналу містить дійсний контекст + діагностичного трасування, що дає змогу процесорам журналів пов’язувати локальні рядки журналу з + експортованими spans. ## Експортовані метрики @@ -166,8 +170,8 @@ openclaw plugins enable diagnostics-otel - `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, 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, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`) +- `gen_ai.client.token.usage` (гістограма, метрика семантичних угод GenAI, 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, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язково `error.type`) ### Потік повідомлень @@ -180,7 +184,7 @@ openclaw plugins enable diagnostics-otel - `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`) @@ -191,15 +195,15 @@ openclaw plugins enable diagnostics-otel - `openclaw.session.stuck_age_ms` (гістограма, attrs: `openclaw.state`) - `openclaw.run.attempt` (лічильник, attrs: `openclaw.attempt`) -### Життєвий цикл Harness +### Життєвий цикл harness -- `openclaw.harness.duration_ms` (гістограма, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` для помилок) +- `openclaw.harness.duration_ms` (гістограма, attrs: `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` у разі помилок) ### 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` (гістограма) @@ -207,23 +211,23 @@ openclaw plugins enable diagnostics-otel - `openclaw.tool.loop.iterations` (лічильник, attrs: `openclaw.toolName`, `openclaw.outcome`) - `openclaw.tool.loop.duration_ms` (гістограма, attrs: `openclaw.toolName`, `openclaw.outcome`) -## Експортовані спани +## Експортовані spans - `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.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.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI - `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport` - - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для id запиту до висхідного провайдера; необроблені id не експортуються) + - `openclaw.provider.request_id_hash` (обмежений SHA-хеш ідентифікатора запиту до висхідного провайдера; сирі ідентифікатори не експортуються) - `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.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`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` - `openclaw.exec` @@ -239,27 +243,27 @@ openclaw plugins enable diagnostics-otel - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту промпту, історії, відповіді або ключа сесії) + - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту промпта, історії, відповіді або ключа сеансу) - `openclaw.tool.loop` - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструмента) - `openclaw.memory.pressure` - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes` -Якщо захоплення вмісту явно ввімкнено, спани моделей та інструментів також можуть -включати обмежені, відредаговані атрибути `openclaw.content.*` для конкретних -класів вмісту, які ви ввімкнули. +Коли явно ввімкнено захоплення вмісту, spans моделі та інструментів також можуть +містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних +класів вмісту, на які ви погодилися. ## Каталог діагностичних подій -Події нижче лежать в основі наведених вище метрик і спанів. Плагіни також можуть підписуватися -на них напряму без експорту OTLP. +Наведені нижче події лежать в основі метрик і spans вище. Plugins також можуть +підписуватися на них безпосередньо без експорту OTLP. **Використання моделей** - `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал, - id сесії. `usage` — це облік провайдера/ходу для вартості та телеметрії; - `context.used` — це поточний знімок промпту/контексту, і він може бути меншим за - `usage.total` провайдера, коли залучено кешоване введення або виклики циклу інструментів. + ідентифікатори сеансу. `usage` — це облік провайдера/ходу для вартості та телеметрії; + `context.used` — це поточний знімок промпта/контексту і він може бути меншим за + `usage.total` провайдера, коли задіяно кешоване введення або виклики циклу інструментів. **Потік повідомлень** @@ -267,21 +271,21 @@ openclaw plugins enable diagnostics-otel - `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/черга/сесія) +- `diagnostic.heartbeat` (агреговані лічильники: webhook/черга/сеанс) -**Життєвий цикл Harness** +**Життєвий цикл harness** - `harness.run.started` / `harness.run.completed` / `harness.run.error` — - життєвий цикл одного запуску для harness агента. Містить `harnessId`, необов’язковий - `pluginId`, провайдера/модель/канал та id запуску. Завершення додає + життєвий цикл кожного запуску для agent harness. Містить `harnessId`, необов’язковий + `pluginId`, провайдера/модель/канал та ідентифікатор запуску. Завершення додає `durationMs`, `outcome`, необов’язкові `resultClassification`, `yieldDetected` і лічильники `itemLifecycle`. Помилки додають `phase` - (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` і + (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` та необов’язковий `cleanupFailed`. **Exec** @@ -292,7 +296,7 @@ openclaw plugins enable diagnostics-otel ## Без експортера -Ви можете залишити діагностичні події доступними для плагінів або власних приймачів без +Ви можете залишити діагностичні події доступними для plugins або користувацьких приймачів без запуску `diagnostics-otel`: ```json5 @@ -302,7 +306,7 @@ openclaw plugins enable diagnostics-otel ``` Для цільового виводу налагодження без підвищення `logging.level` використовуйте -прапорці діагностики. Прапорці нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або +діагностичні прапорці. Прапорці нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або `*`): ```json5 @@ -311,15 +315,15 @@ openclaw plugins enable diagnostics-otel } ``` -Або як разове перевизначення через env: +Або як одноразове перевизначення через env: ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -Вивід прапорців надходить до стандартного файла журналу (`logging.file`) і все ще +Вивід прапорців потрапляє до стандартного файла журналу (`logging.file`) і, як і раніше, редагується через `logging.redactSensitive`. Повний посібник: -[Прапорці діагностики](/uk/diagnostics/flags). +[Діагностичні прапорці](/uk/diagnostics/flags). ## Вимкнення @@ -329,13 +333,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway } ``` -Ви також можете не додавати `diagnostics-otel` до `plugins.allow` або виконати +Ви також можете не включати `diagnostics-otel` до `plugins.allow` або виконати `openclaw plugins disable diagnostics-otel`. ## Пов’язане -- [Журналювання](/uk/logging) — файлові журнали, вивід у консоль, перегляд через CLI та вкладка журналів у Control UI +- [Журналювання](/uk/logging) — файлові журнали, вивід у консоль, tailing у CLI та вкладка Logs у Control UI - [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі -- [Прапорці діагностики](/uk/diagnostics/flags) — прапорці цільових журналів налагодження -- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент операторського пакета підтримки (окремо від експорту OTEL) +- [Діагностичні прапорці](/uk/diagnostics/flags) — цільові прапорці журналів налагодження +- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент операторського support bundle (окремо від експорту OTEL) - [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` diff --git a/docs/uk/logging.md b/docs/uk/logging.md index 10c14e707..951e55664 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -1,39 +1,38 @@ --- read_when: - - Вам потрібен дружній до початківців огляд логування в OpenClaw - - Ви хочете налаштувати рівні логування, формати або редагування конфіденційних даних - - Ви усуваєте несправності й вам потрібно швидко знайти журнали -summary: Журнали файлів, вивід консолі, CLI tailing та вкладка Logs у Control UI -title: Логування + - Вам потрібен огляд журналювання OpenClaw, зрозумілий для початківців + - Ви хочете налаштувати рівні журналювання, формати або маскування конфіденційних даних + - Ви виконуєте діагностику й хочете швидко знайти журнали +summary: Журнали файлів, вивід консолі, відстеження CLI та вкладка Logs в Control UI +title: Журналювання x-i18n: - generated_at: "2026-04-26T19:17:03Z" + generated_at: "2026-04-26T19:56:14Z" model: gpt-5.4 provider: openai - source_hash: 3c1d4629a1d886d38061a9bb89c4b4e7720189de7647eee2174821070a12b600 + source_hash: b4846f17e911e6fc2c202ec78ce83c8d0fc8e567942f88324ffc1ba230c0b8b0 source_path: logging.md workflow: 15 --- -OpenClaw має дві основні поверхні логування: +OpenClaw має дві основні поверхні журналювання: -- **Журнали файлів** (рядки JSON), які записує Gateway. -- **Вивід консолі**, що показується в терміналах і Gateway Debug UI. +- **Файлові журнали** (рядки JSON), які записує Gateway. +- **Вивід консолі**, що показується в терміналах і в Gateway Debug UI. -Вкладка **Logs** у Control UI виконує tail журналу файлу gateway. На цій сторінці -пояснюється, де знаходяться журнали, як їх читати та як налаштовувати рівні й формати логування. +Вкладка **Logs** у Control UI відстежує файловий журнал gateway. На цій сторінці пояснюється, де розміщуються журнали, як їх читати та як налаштовувати рівні й формати журналювання. -## Де зберігаються журнали +## Де розміщуються журнали -За замовчуванням Gateway записує ротаційний файл журналу в: +За замовчуванням Gateway записує циклічний файл журналу в: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` Дата використовує локальний часовий пояс хоста gateway. -Кожен файл ротуються, коли досягає `logging.maxFileBytes` (типово: 100 МБ). +Кожен файл ротується, коли досягає `logging.maxFileBytes` (за замовчуванням: 100 MB). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом, наприклад -`openclaw-YYYY-MM-DD.1.log`, і продовжує записувати в новий активний журнал замість -приглушення діагностичних даних. +`openclaw-YYYY-MM-DD.1.log`, і продовжує запис у новий активний журнал замість +пригнічення діагностичних даних. Ви можете перевизначити це в `~/.openclaw/openclaw.json`: @@ -47,9 +46,9 @@ OpenClaw зберігає до п’яти нумерованих архівів ## Як читати журнали -### CLI: live tail (рекомендовано) +### CLI: відстеження в реальному часі (рекомендовано) -Використовуйте CLI, щоб виконувати tail файла журналу gateway через RPC: +Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC: ```bash openclaw logs --follow @@ -57,34 +56,34 @@ openclaw logs --follow Корисні поточні параметри: -- `--local-time`: відображати часові позначки у вашому локальному часовому поясі +- `--local-time`: відображати часові мітки у вашому локальному часовому поясі - `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC -- `--expect-final`: прапорець очікування фінальної відповіді для RPC на базі агента (приймається тут через спільний клієнтський шар) +- `--expect-final`: прапорець очікування фінальної відповіді для RPC з підтримкою агента (приймається тут через спільний клієнтський шар) Режими виводу: - **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу. - **Не-TTY-сеанси**: звичайний текст. - `--json`: JSON з розділенням по рядках (одна подія журналу на рядок). -- `--plain`: примусово ввімкнути звичайний текст у TTY-сеансах. +- `--plain`: примусово використовувати звичайний текст у TTY-сеансах. - `--no-color`: вимкнути ANSI-кольори. Коли ви передаєте явний `--url`, CLI не застосовує автоматично конфігурацію чи -облікові дані з середовища; додайте `--token` самостійно, якщо цільовий Gateway -вимагає автентифікацію. +облікові дані середовища; якщо цільовий Gateway +потребує автентифікації, додайте `--token` самостійно. -У режимі JSON CLI виводить об’єкти з тегом `type`: +У режимі JSON CLI виводить об’єкти з міткою `type`: - `meta`: метадані потоку (файл, курсор, розмір) - `log`: розібраний запис журналу -- `notice`: підказки про обрізання / ротацію +- `notice`: підказки про усічення / ротацію - `raw`: нерозібраний рядок журналу -Якщо Gateway local loopback запитує pairing, `openclaw logs` автоматично -перемикається на налаштований локальний файл журналу. Явні цілі `--url` не +Якщо Gateway на local loopback запитує pairing, `openclaw logs` автоматично +перемикається на налаштований локальний файл журналу. Явно вказані цілі через `--url` не використовують цей резервний варіант. -Якщо Gateway недоступний, CLI виводить коротку підказку виконати: +Якщо Gateway недоступний, CLI виведе коротку підказку виконати: ```bash openclaw doctor @@ -92,12 +91,12 @@ openclaw doctor ### Control UI (web) -Вкладка **Logs** у Control UI виконує tail того самого файла за допомогою `logs.tail`. -Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як її відкрити. +Вкладка **Logs** у Control UI відстежує той самий файл через `logs.tail`. +Як її відкрити, див. у [/web/control-ui](/uk/web/control-ui). ### Журнали лише каналів -Щоб фільтрувати активність каналів (WhatsApp/Telegram тощо), використовуйте: +Щоб відфільтрувати активність каналу (WhatsApp/Telegram/тощо), використовуйте: ```bash openclaw channels logs --channel whatsapp @@ -105,9 +104,9 @@ openclaw channels logs --channel whatsapp ## Формати журналів -### Журнали файлів (JSONL) +### Файлові журнали (JSONL) -Кожен рядок у файлі журналу є JSON-об’єктом. CLI і Control UI аналізують ці +Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI аналізують ці записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення). ### Вивід консолі @@ -115,18 +114,18 @@ openclaw channels logs --channel whatsapp Журнали консолі **враховують TTY** і форматуються для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) -- Кольорове позначення рівнів (info/warn/error) -- Необов’язковий компактний режим або режим JSON +- Кольорове позначення рівня (info/warn/error) +- Необов’язковий компактний або JSON-режим Форматування консолі керується `logging.consoleStyle`. -### Журнали Gateway WebSocket +### Журнали WebSocket Gateway -`openclaw gateway` також має логування протоколу WebSocket для трафіку RPC: +`openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку: -- звичайний режим: лише цікаві результати (помилки, помилки аналізу, повільні виклики) +- звичайний режим: лише важливі результати (помилки, помилки розбору, повільні виклики) - `--verbose`: увесь трафік запитів/відповідей -- `--ws-log auto|compact|full`: вибір стилю детального відображення +- `--ws-log auto|compact|full`: вибрати стиль докладного відображення - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -137,9 +136,9 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## Налаштування логування +## Налаштування журналювання -Уся конфігурація логування знаходиться в `logging` у `~/.openclaw/openclaw.json`. +Усі налаштування журналювання розміщуються в `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -154,58 +153,65 @@ openclaw gateway --verbose --ws-log full } ``` -### Рівні логування +### Рівні журналювання -- `logging.level`: рівень **журналів файлів** (JSONL). +- `logging.level`: рівень **файлових журналів** (JSONL). - `logging.consoleLevel`: рівень деталізації **консолі**. -Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тож ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. +Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. -`--verbose` впливає лише на вивід консолі та деталізацію журналу WS; він не змінює -рівні журналу файлів. +`--verbose` впливає лише на вивід консолі та деталізацію журналів WS; він не змінює +рівні файлових журналів. + +### Кореляція трасувань + +Файлові журнали мають формат JSONL. Коли виклик журналювання містить коректний контекст діагностичного трасування, +OpenClaw записує поля трасування як JSON-ключі верхнього рівня (`traceId`, `spanId`, +`parentSpanId`, `traceFlags`), щоб зовнішні обробники журналів могли пов’язати цей рядок +із OTEL spans і поширенням `traceparent` постачальника. ### Стилі консолі `logging.consoleStyle`: -- `pretty`: зручний для читання людиною, кольоровий, із часовими позначками. -- `compact`: щільніший вивід (найкраще для довгих сеансів). -- `json`: JSON на рядок (для обробників журналів). +- `pretty`: зручний для людей, кольоровий, із часовими мітками. +- `compact`: щільніший вивід (найкраще для тривалих сеансів). +- `json`: JSON у кожному рядку (для обробників журналів). -### Редагування конфіденційних даних +### Маскування -OpenClaw може редагувати конфіденційні токени до того, як вони потраплять у вивід консолі, журнали файлів, -записи журналів OTLP або збережений текст стенограми сеансу: +OpenClaw може маскувати чутливі токени до того, як вони потраплять у вивід консолі, файлові журнали, +записи журналів OTLP або збережений текст транскрипту сеансу: -- `logging.redactSensitive`: `off` | `tools` (типово: `tools`) -- `logging.redactPatterns`: список рядків regex для перевизначення типового набору +- `logging.redactSensitive`: `off` | `tools` (за замовчуванням: `tools`) +- `logging.redactPatterns`: список рядків regex для перевизначення набору за замовчуванням -Журнали файлів і стенограми сеансів залишаються у форматі JSONL, але значення секретів, що збігаються, -маскуються до того, як рядок або повідомлення буде записано на диск. Редагування конфіденційних даних виконується за принципом best-effort: +Файлові журнали й транскрипти сеансів залишаються у форматі JSONL, але відповідні значення секретів +маскуються до того, як рядок або повідомлення буде записано на диск. Маскування виконується за принципом best-effort: воно застосовується до текстового вмісту повідомлень і рядків журналу, але не до кожного -ідентифікатора чи поля двійкового payload. +ідентифікатора чи поля двійкового корисного навантаження. ## Діагностика та OpenTelemetry -Діагностика — це структуровані, машинозчитувані події для запусків моделей і -телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не** -замінюють журнали — вони живлять метрики, трасування та експортери. Події генеруються +Діагностичні дані — це структуровані, машиночитані події для запусків моделей і +телеметрії потоку повідомлень (webhooks, черги, стан сеансу). Вони **не** +замінюють журнали — вони живлять метрики, трасування та exporters. Події генеруються в процесі незалежно від того, експортуєте ви їх чи ні. Дві суміжні поверхні: - **Експорт OpenTelemetry** — надсилає метрики, трасування та журнали через OTLP/HTTP до - будь-якого колектора або бекенду, сумісного з OpenTelemetry (Grafana, Datadog, + будь-якого collector або backend, сумісного з OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, - назви метрик/span, змінні середовища та модель конфіденційності описані на окремій сторінці: + назви metric/span, змінні середовища та модель конфіденційності розміщені на окремій сторінці: [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -- **Прапорці діагностики** — цільові прапорці журналів налагодження, які спрямовують додаткові журнали до +- **Прапорці діагностики** — цільові прапорці debug-log, які спрямовують додаткові журнали до `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру - та підтримують шаблони з wildcard (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` - або через перевизначення середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: + і підтримують шаблони з підстановками (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` + або через перевизначення змінною середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: [Прапорці діагностики](/uk/diagnostics/flags). -Щоб увімкнути події діагностики для Plugin або власних sinks без експорту OTLP: +Щоб увімкнути діагностичні події для Plugin або користувацьких приймачів без експорту OTLP: ```json5 { @@ -213,18 +219,18 @@ OpenClaw може редагувати конфіденційні токени } ``` -Для експорту OTLP до колектора див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry). +Для експорту OTLP до collector див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -## Поради з усунення несправностей +## Поради з діагностики проблем - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Журнали порожні?** Переконайтеся, що Gateway запущено і він записує у шлях файла, +- **Журнали порожні?** Переконайтеся, що Gateway запущений і записує у шлях до файлу, вказаний у `logging.file`. - **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. -## Пов’язане +## Пов’язані матеріали - [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог metric/span, модель конфіденційності -- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналів налагодження -- [Внутрішня будова логування Gateway](/uk/gateway/logging) — стилі журналу WS, префікси підсистем і захоплення консолі +- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці debug-log +- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і перехоплення консолі - [Довідник з конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`