From 6dfaa8177fd5b63efd90fa7ea3a9f03afb02faf9 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 21:18:08 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/opentelemetry.md | 238 ++++++++++++++++--------------- docs/uk/logging.md | 171 +++++++++++----------- 2 files changed, 212 insertions(+), 197 deletions(-) diff --git a/docs/uk/gateway/opentelemetry.md b/docs/uk/gateway/opentelemetry.md index 1511ad3e6..f9ad3a9f5 100644 --- a/docs/uk/gateway/opentelemetry.md +++ b/docs/uk/gateway/opentelemetry.md @@ -1,36 +1,36 @@ --- read_when: - - Ви хочете надсилати використання моделей OpenClaw, потік повідомлень або метрики сеансів до колектора OpenTelemetry - - Ви налаштовуєте траси, метрики або логи для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого бекенда OTLP + - Ви хочете надсилати дані про використання моделей 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-26T20:47:26Z" + generated_at: "2026-04-26T21:17:06Z" model: gpt-5.4 provider: openai - source_hash: 4c0462a19d5eebde92f87fef3d26dfe7338c3d446caf4b8c7097eb1a13a278fe + source_hash: 1ad923fff12ff89766999370fe39a75c1aa5f386ce4641fde1c385b24439cc1b source_path: gateway/opentelemetry.md workflow: 15 --- OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel` з використанням **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, -працюватиме без змін у коді. Про локальні файлові логи та способи їх читання див. -[Логування](/uk/logging). +працює без змін у коді. Для локальних файлових журналів і того, як їх читати, див. +[Журналювання](/uk/logging). ## Як це працює разом -- **Події діагностики** — це структуровані внутрішньопроцесні записи, які генерують - Gateway і вбудовані плагіни для запусків моделей, потоку повідомлень, сеансів, черг +- **Діагностичні події** — це структуровані внутрішньопроцесні записи, які створюються + Gateway і вбудованими плагінами для запусків моделей, потоку повідомлень, сесій, черг та exec. -- **Plugin `diagnostics-otel`** підписується на ці події та експортує їх як - OpenTelemetry **метрики**, **траси** й **логи** через OTLP/HTTP. -- **Виклики провайдера** отримують заголовок W3C `traceparent` з довіреного контексту span виклику моделі OpenClaw, - якщо транспорт провайдера підтримує користувацькі заголовки. - Контекст трасування, згенерований Plugin, не передається далі. +- **Plugin `diagnostics-otel`** підписується на ці події й експортує їх як + OpenTelemetry **метрики**, **трасування** та **журнали** через OTLP/HTTP. +- **Виклики провайдера** отримують заголовок W3C `traceparent` із контексту + довіреного span виклику моделі OpenClaw, якщо транспорт провайдера приймає власні + заголовки. Контекст трасування, створений Plugin, не передається далі. - Експортери підключаються лише тоді, коли увімкнено і поверхню діагностики, і Plugin, - тож внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими. + тому внутрішньопроцесна вартість за замовчуванням залишається майже нульовою. ## Швидкий старт @@ -71,14 +71,14 @@ openclaw plugins enable diagnostics-otel ## Експортовані сигнали -| Сигнал | Що до нього входить | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сеансу, exec і тиску пам’яті. | -| **Траси** | Spans для використання моделі, викликів моделі, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | -| **Логи** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | +| Сигнал | Що до нього входить | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сесії, exec і тиску пам’яті. | +| **Трасування** | Спани для використання моделей, викликів моделей, життєвого циклу harness, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | +| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | -Параметри `traces`, `metrics` і `logs` можна вмикати окремо. Усі три за замовчуванням увімкнені, -коли `diagnostics.otel.enabled` має значення true. +Перемикайте `traces`, `metrics` і `logs` незалежно. За замовчуванням усі три +увімкнені, коли `diagnostics.otel.enabled` має значення true. ## Довідник конфігурації @@ -115,105 +115,111 @@ 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_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | -| `OTEL_EXPORTER_OTLP_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 або хост-процес уже зареєстрував глобальний SDK OpenTelemetry. Тоді Plugin пропустить власний життєвий цикл NodeSDK, але все одно підключить слухачі діагностики та врахує `traces`/`metrics`/`logs`. | +| Змінна | Призначення | +| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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`, щоб виводити останній експериментальний атрибут span GenAI (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | +| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інше preload-рішення або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді Plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. | ## Конфіденційність і захоплення вмісту -Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Spans містять обмежені -ідентифікатори (канал, провайдер, модель, категорія помилки, лише хешовані id запитів) -і ніколи не включають текст запиту, текст відповіді, входи інструментів, виходи інструментів чи ключі сеансу. +Необроблений вміст моделей/інструментів **не** експортується за замовчуванням. Спани містять +обмежені ідентифікатори (канал, провайдер, модель, категорія помилки, лише хешовані request id) +і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, вихідні дані +інструментів або ключі сесій. Вихідні запити до моделі можуть містити заголовок W3C `traceparent`. Цей заголовок -генерується лише з контексту діагностичного трасування, що належить OpenClaw, для активного виклику моделі. -Наявні заголовки `traceparent`, передані викликачем, замінюються, тому плагіни або -користувацькі параметри провайдера не можуть підробити міжсервісне походження трасування. +генерується лише з діагностичного контексту трасування, що належить OpenClaw, для активного виклику +моделі. Наявні заголовки `traceparent`, передані викликачем, замінюються, тому Plugins або +власні параметри провайдера не можуть підробити походження трасування між сервісами. -Установлюйте `diagnostics.otel.captureContent.*` у `true` лише тоді, коли ваш колектор і -політика зберігання схвалені для тексту запитів, відповідей, інструментів або системних запитів. -Кожен підключ окремо вмикається за згодою: +Установлюйте `diagnostics.otel.captureContent.*` у значення `true` лише тоді, коли ваш колектор і +політика зберігання схвалені для тексту промптів, відповідей, інструментів або системних промптів. +Кожен підключ окремо вмикається явно: -- `inputMessages` — вміст запиту користувача. +- `inputMessages` — вміст користувацького промпту. - `outputMessages` — вміст відповіді моделі. -- `toolInputs` — корисні навантаження аргументів інструмента. -- `toolOutputs` — корисні навантаження результатів інструмента. -- `systemPrompt` — зібраний системний/розробницький запит. +- `toolInputs` — корисні навантаження аргументів інструментів. +- `toolOutputs` — корисні навантаження результатів інструментів. +- `systemPrompt` — зібраний системний/розробницький промпт. -Коли будь-який підключ увімкнено, spans моделі та інструментів отримують обмежені, відредаговані +Коли ввімкнено будь-який підключ, спани моделі та інструментів отримують обмежені, відредаговані атрибути `openclaw.content.*` лише для цього класу. ## Семплювання та скидання -- **Траси:** `diagnostics.otel.sampleRate` (лише root-span, `0.0` відкидає всі, - `1.0` зберігає всі). +- **Трасування:** `diagnostics.otel.sampleRate` (лише root-span, `0.0` відкидає все, + `1.0` зберігає все). - **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`). -- **Логи:** OTLP-логи враховують `logging.level` (рівень файлового логування). Вони використовують - шлях редагування діагностичних log-record, а не форматування консолі. Для інсталяцій із великим обсягом - даних краще використовувати семплювання/фільтрацію в колекторі OTLP, а не локальне семплювання. -- **Кореляція з файловими логами:** JSONL-файли логів містять верхньорівневі поля `traceId`, - `spanId`, `parentSpanId` і `traceFlags`, коли виклик логування має коректний контекст діагностичного трасування, - що дає змогу процесорам логів пов’язувати локальні рядки логів з експортованими spans. +- **Журнали:** журнали OTLP враховують `logging.level` (рівень файлового журналу). Вони використовують + шлях редагування діагностичних log record, а не форматування консолі. Для інсталяцій із великим + обсягом даних краще використовувати семплювання/фільтрацію в колекторі OTLP, а не локальне семплювання. +- **Кореляція файлових журналів:** журнали JSONL включають верхньорівневі `traceId`, + `spanId`, `parentSpanId` і `traceFlags`, коли виклик журналювання містить коректний + діагностичний контекст трасування, що дає змогу обробникам журналів поєднувати локальні рядки журналу + з експортованими спанами. +- **Кореляція запитів:** HTTP-запити Gateway і кадри WebSocket створюють внутрішню + область трасування запиту. Журнали та діагностичні події в цій області за замовчуванням + успадковують трасування запиту, тоді як спани запуску агента та виклику моделі + створюються як дочірні, щоб заголовки провайдера `traceparent` залишалися в межах того самого трасування. ## Експортовані метрики -### Використання моделі +### Використання моделей -- `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.model_call.request_bytes` (гістограма, розмір у байтах UTF-8 фінального корисного навантаження запиту до моделі; без необробленого вмісту навантаження) +- `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`) +- `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`) +- `openclaw.model_call.duration_ms` (гістограма, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`) +- `openclaw.model_call.request_bytes` (гістограма, розмір у байтах UTF-8 фінального payload запиту до моделі; без необробленого вмісту payload) - `openclaw.model_call.response_bytes` (гістограма, розмір у байтах UTF-8 потокових подій відповіді моделі; без необробленого вмісту відповіді) - `openclaw.model_call.time_to_first_byte_ms` (гістограма, час до першої потокової події відповіді) ### Потік повідомлень -- `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.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.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` (лічильник, атрибути: `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.run.attempt` (лічильник, атрибути: `openclaw.attempt`) +- `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`) ### Життєвий цикл harness -- `openclaw.harness.duration_ms` (гістограма, атрибути: `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` (гістограма, атрибути: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) +- `openclaw.exec.duration_ms` (гістограма, attrs: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) -### Внутрішні метрики діагностики (пам’ять і цикл інструментів) +### Внутрішня діагностика (пам’ять і цикл інструментів) -- `openclaw.memory.heap_used_bytes` (гістограма, атрибути: `openclaw.memory.kind`) +- `openclaw.memory.heap_used_bytes` (гістограма, attrs: `openclaw.memory.kind`) - `openclaw.memory.rss_bytes` (гістограма) -- `openclaw.memory.pressure` (лічильник, атрибути: `openclaw.memory.level`) -- `openclaw.tool.loop.iterations` (лічильник, атрибути: `openclaw.toolName`, `openclaw.outcome`) -- `openclaw.tool.loop.duration_ms` (гістограма, атрибути: `openclaw.toolName`, `openclaw.outcome`) +- `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`) -## Експортовані spans +## Експортовані спани - `openclaw.model.usage` - `openclaw.channel`, `openclaw.provider`, `openclaw.model` @@ -226,11 +232,11 @@ openclaw plugins enable diagnostics-otel - `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.model_call.request_bytes`, `openclaw.model_call.response_bytes`, `openclaw.model_call.time_to_first_byte_ms` - - `openclaw.provider.request_id_hash` (обмежений SHA-хеш id запиту до висхідного провайдера; необроблені id не експортуються) + - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для upstream request id провайдера; сирі id не експортуються) - `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` @@ -246,27 +252,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` -Коли захоплення вмісту явно ввімкнено, spans моделі та інструментів також можуть -містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних -класів вмісту, які ви явно ввімкнули. +Коли захоплення вмісту явно ввімкнене, спани моделі та інструментів також можуть +включати обмежені, відредаговані атрибути `openclaw.content.*` для конкретних +класів вмісту, на які ви дали згоду. -## Каталог подій діагностики +## Каталог діагностичних подій -Події нижче є основою для наведених вище метрик і spans. Плагіни також можуть підписуватися -на них безпосередньо, без експорту OTLP. +Наведені нижче події лежать в основі метрик і спанів вище. Plugins також можуть +підписуватися на них безпосередньо без експорту OTLP. -**Використання моделі** +**Використання моделей** - `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал, - id сеансів. `usage` — це облік провайдера/ходу для вартості та телеметрії; - `context.used` — це поточний знімок запиту/контексту й може бути меншим за - `usage.total` провайдера, коли задіяні кешований вхід або виклики циклу інструментів. + id сесій. `usage` — це облік провайдера/ходу для вартості й телеметрії; + `context.used` — це поточний знімок промпту/контексту і він може бути меншим за + `usage.total` провайдера, коли задіяно кешоване введення або виклики циклу інструментів. **Потік повідомлень** @@ -274,32 +280,32 @@ 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.run.started` / `harness.run.completed` / `harness.run.error` — - життєвий цикл кожного запуску harness агента. Містить `harnessId`, необов’язковий - `pluginId`, провайдера/модель/канал і id запуску. Завершення додає + життєвий цикл кожного запуску для harness агента. Включає `harnessId`, необов’язковий + `pluginId`, провайдер/модель/канал і id запуску. Завершення додає `durationMs`, `outcome`, необов’язкові `resultClassification`, `yieldDetected` - та лічильники `itemLifecycle`. Помилки додають `phase` - (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` та + і лічильники `itemLifecycle`. Помилки додають `phase` + (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` і необов’язковий `cleanupFailed`. **Exec** -- `exec.process.completed` — підсумковий результат, тривалість, ціль, режим, код +- `exec.process.completed` — кінцевий результат, тривалість, ціль, режим, код виходу та тип збою. Текст команди й робочі каталоги не включаються. ## Без експортера -Ви можете зберегти події діагностики доступними для плагінів або користувацьких приймачів без +Ви можете залишити діагностичні події доступними для Plugins або власних приймачів без запуску `diagnostics-otel`: ```json5 @@ -308,8 +314,8 @@ openclaw plugins enable diagnostics-otel } ``` -Для цільового виводу налагодження без підвищення `logging.level` використовуйте прапорці -діагностики. Прапорці нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або +Для цільового виводу налагодження без підвищення `logging.level` використовуйте +прапорці діагностики. Прапорці нечутливі до регістру й підтримують шаблони (наприклад, `telegram.*` або `*`): ```json5 @@ -318,14 +324,14 @@ openclaw plugins enable diagnostics-otel } ``` -Або як одноразове перевизначення через env: +Або як одноразове перевизначення через змінну середовища: ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -Вивід прапорців надходить до стандартного файла логів (`logging.file`) і все ще -редагується за допомогою `logging.redactSensitive`. Повний посібник: +Вивід прапорців потрапляє до стандартного файла журналу (`logging.file`) і все ще +редагується через `logging.redactSensitive`. Повний посібник: [Прапорці діагностики](/uk/diagnostics/flags). ## Вимкнення @@ -341,8 +347,8 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ## Пов’язане -- [Логування](/uk/logging) — файлові логи, вивід у консоль, tailing у CLI та вкладка Logs в Control UI -- [Внутрішня будова логування Gateway](/uk/gateway/logging) — стилі логів WS, префікси підсистем і захоплення консолі -- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці логів налагодження -- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент пакета підтримки для операторів (окремо від експорту OTEL) +- [Журналювання](/uk/logging) — файлові журнали, вивід у консоль, перегляд через CLI та вкладка Журнали в Control UI +- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Прапорці діагностики](/uk/diagnostics/flags) — прапорці цільового журналювання для налагодження +- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент підтримки для збору пакета даних оператора (окремо від експорту OTEL) - [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` diff --git a/docs/uk/logging.md b/docs/uk/logging.md index 823670af2..c36b7fe26 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -1,38 +1,38 @@ --- read_when: - - Вам потрібен огляд журналювання OpenClaw, зрозумілий для початківців - - Ви хочете налаштувати рівні журналювання, формати або редагування конфіденційних даних - - Ви усуваєте неполадки й вам потрібно швидко знайти журнали -summary: Файлові журнали, вивід консолі, відстеження CLI та вкладка Журнали в Control UI -title: Журналювання + - Вам потрібен огляд логування OpenClaw, зрозумілий для початківців + - Ви хочете налаштувати рівні логування, формати або редагування конфіденційних даних + - Ви усуваєте несправності й вам потрібно швидко знайти логи +summary: Файлові логи, вивід консолі, відстеження CLI та вкладка «Логи» в Control UI +title: Логування x-i18n: - generated_at: "2026-04-26T20:47:23Z" + generated_at: "2026-04-26T21:17:02Z" model: gpt-5.4 provider: openai - source_hash: 2a6e363818e1d48b8b265bf18214772f40ffd55c423acd50dee7659f37b44bfa + source_hash: ece4fe127194144fccda44d42903cdbb989183b6e87aedf9ac2470704be26bdb source_path: logging.md workflow: 15 --- -OpenClaw має дві основні поверхні журналювання: +OpenClaw має дві основні поверхні логування: -- **Файлові журнали** (рядки JSON), які записує Gateway. -- **Вивід консолі**, який показується в терміналах і в Gateway Debug UI. +- **Файлові логи** (рядки JSON), які записує Gateway. +- **Вивід консолі**, що показується в терміналах і в Gateway Debug UI. -Вкладка **Logs** у Control UI відстежує файловий журнал gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. +Вкладка **Logs** у Control UI відстежує файловий лог gateway. На цій сторінці пояснюється, де зберігаються логи, як їх читати та як налаштовувати рівні й формати логування. -## Де зберігаються журнали +## Де зберігаються логи -Типово Gateway записує циклічний файл журналу в: +Типово Gateway записує циклічний файл логу за шляхом: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` Дата використовує локальний часовий пояс хоста gateway. -Кожен файл ротуватиметься, коли досягне `logging.maxFileBytes` (типово: 100 МБ). +Кожен файл ротується, коли досягає `logging.maxFileBytes` (типово: 100 МБ). OpenClaw зберігає до п’яти пронумерованих архівів поруч з активним файлом, наприклад -`openclaw-YYYY-MM-DD.1.log`, і продовжує записувати у новий активний журнал замість -приглушення діагностики. +`openclaw-YYYY-MM-DD.1.log`, і продовжує писати в новий активний лог, а не +приглушує діагностичні дані. Ви можете перевизначити це в `~/.openclaw/openclaw.json`: @@ -44,11 +44,11 @@ OpenClaw зберігає до п’яти пронумерованих архі } ``` -## Як читати журнали +## Як читати логи ### CLI: відстеження в реальному часі (рекомендовано) -Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC: +Використовуйте CLI, щоб відстежувати файл логу gateway через RPC: ```bash openclaw logs --follow @@ -56,32 +56,34 @@ openclaw logs --follow Корисні поточні параметри: -- `--local-time`: відображати часові мітки у вашому локальному часовому поясі +- `--local-time`: показувати часові мітки у вашому локальному часовому поясі - `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC -- `--expect-final`: прапорець очікування фінальної відповіді RPC з підтримкою агента (приймається тут через спільний клієнтський шар) +- `--expect-final`: прапорець очікування фінальної відповіді RPC із підтримкою агентів (підтримується тут через спільний клієнтський шар) Режими виводу: -- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу. -- **Не-TTY-сеанси**: звичайний текст. -- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок). +- **TTY-сеанси**: гарно оформлені, кольорові, структуровані рядки логів. +- **Не-TTY сеанси**: звичайний текст. +- `--json`: JSON з розділенням по рядках (одна подія логу на рядок). - `--plain`: примусово використовувати звичайний текст у TTY-сеансах. - `--no-color`: вимкнути ANSI-кольори. -Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або -середовища; якщо цільовий Gateway вимагає автентифікацію, додайте `--token` самостійно. +Коли ви передаєте явний `--url`, CLI не застосовує автоматично конфігурацію чи +облікові дані із середовища; додайте `--token` самостійно, якщо цільовий Gateway +потребує автентифікації. У режимі JSON CLI виводить об’єкти з тегом `type`: - `meta`: метадані потоку (файл, курсор, розмір) -- `log`: розібраний запис журналу +- `log`: розібраний запис логу - `notice`: підказки про обрізання / ротацію -- `raw`: нерозібраний рядок журналу +- `raw`: нерозібраний рядок логу -Якщо Gateway на local loopback запитує сполучення, `openclaw logs` автоматично повертається -до налаштованого локального файлу журналу. Явні цілі `--url` не використовують цей резервний варіант. +Якщо Gateway на local loopback запитує pairing, `openclaw logs` автоматично +перемикається на налаштований локальний файл логу. Для явних цілей `--url` +цей резервний варіант не використовується. -Якщо Gateway недоступний, CLI виведе коротку підказку виконати: +Якщо Gateway недоступний, CLI виводить коротку підказку виконати: ```bash openclaw doctor @@ -89,10 +91,10 @@ openclaw doctor ### Control UI (веб) -Вкладка **Logs** у Control UI відстежує той самий файл через `logs.tail`. -Як її відкрити, див. у [/web/control-ui](/uk/web/control-ui). +Вкладка **Logs** у Control UI відстежує той самий файл за допомогою `logs.tail`. +Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як її відкрити. -### Журнали лише каналів +### Логи лише каналів Щоб відфільтрувати активність каналів (WhatsApp/Telegram тощо), використовуйте: @@ -100,30 +102,30 @@ openclaw doctor openclaw channels logs --channel whatsapp ``` -## Формати журналів +## Формати логів -### Файлові журнали (JSONL) +### Файлові логи (JSONL) -Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI розбирають ці -записи для відображення структурованого виводу (час, рівень, підсистема, повідомлення). +Кожен рядок у файлі логу — це об’єкт JSON. CLI і Control UI розбирають ці +записи, щоб показувати структурований вивід (час, рівень, підсистема, повідомлення). ### Вивід консолі -Журнали консолі **враховують TTY** і форматуються для зручності читання: +Логи консолі **враховують TTY** і форматуються для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) - Кольорове позначення рівнів (info/warn/error) - Необов’язковий компактний або JSON-режим -Форматування консолі керується `logging.consoleStyle`. +Форматування консолі керується через `logging.consoleStyle`. -### Журнали WebSocket Gateway +### Логи Gateway WebSocket -`openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку: +`openclaw gateway` також має логування протоколу WebSocket для RPC-трафіку: -- звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики) +- звичайний режим: лише важливі результати (помилки, помилки розбору, повільні виклики) - `--verbose`: увесь трафік запитів/відповідей -- `--ws-log auto|compact|full`: вибір стилю докладного відображення +- `--ws-log auto|compact|full`: вибір стилю детального виводу - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -134,9 +136,9 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## Налаштування журналювання +## Налаштування логування -Уся конфігурація журналювання знаходиться в розділі `logging` у `~/.openclaw/openclaw.json`. +Усі налаштування логування зберігаються в `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -151,78 +153,85 @@ 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. Коли виклик журналювання містить коректний контекст діагностичного трасування, +Файлові логи мають формат JSONL. Коли виклик логу містить коректний діагностичний контекст трасування, OpenClaw записує поля трасування як JSON-ключі верхнього рівня (`traceId`, `spanId`, -`parentSpanId`, `traceFlags`), щоб зовнішні обробники журналів могли співвіднести рядок -зі span-ами OTEL і передаванням `traceparent` від провайдера. +`parentSpanId`, `traceFlags`), щоб зовнішні обробники логів могли пов’язувати рядок +із span OTEL і передаванням `traceparent` провайдера. + +HTTP-запити Gateway і WebSocket-фрейми Gateway створюють внутрішню область трасування запиту. +Логи й діагностичні події, згенеровані в межах цієї асинхронної області, успадковують +трасування запиту, якщо не передано явний контекст трасування. Трасування запуску агента й +виклику моделі стають дочірніми до активного трасування запиту, тому локальні логи, +діагностичні знімки, span OTEL і довірені заголовки провайдера `traceparent` можна +пов’язати через `traceId` без логування сирого вмісту запиту або моделі. ### Розмір і час виклику моделі -Діагностика викликів моделі записує обмежені вимірювання запитів/відповідей без +Діагностика викликів моделі записує обмежені вимірювання запиту/відповіді без захоплення сирого вмісту prompt або відповіді: -- `requestPayloadBytes`: розмір у байтах UTF-8 кінцевого payload запиту до моделі +- `requestPayloadBytes`: розмір у байтах UTF-8 фінального payload запиту до моделі - `responseStreamBytes`: розмір у байтах UTF-8 подій потокової відповіді моделі -- `timeToFirstByteMs`: час до першої події потокової відповіді +- `timeToFirstByteMs`: затримка до першої події потокової відповіді - `durationMs`: загальна тривалість виклику моделі -Ці поля доступні для діагностичних знімків, хуків Plugin для викликів моделі та -span-ів/метрик OTEL для викликів моделі, коли ввімкнено експорт діагностики. +Ці поля доступні для діагностичних знімків, hook-ів Plugin для викликів моделі та +span/метрик OTEL для викликів моделі, коли ввімкнено експорт діагностики. ### Стилі консолі `logging.consoleStyle`: -- `pretty`: зручно для людей, з кольорами та часовими мітками. +- `pretty`: зручний для людини, кольоровий, з часовими мітками. - `compact`: щільніший вивід (найкраще для довгих сеансів). -- `json`: JSON у кожному рядку (для обробників журналів). +- `json`: JSON у кожному рядку (для обробників логів). ### Редагування конфіденційних даних -OpenClaw може маскувати чутливі токени до того, як вони потраплять у вивід консолі, файлові журнали, -записи журналів OTLP або збережений текст транскрипту сеансу: +OpenClaw може маскувати конфіденційні токени до того, як вони потраплять у вивід консолі, +файлові логи, записи логів OTLP або збережений текст транскрипту сеансу: - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: список рядків regex для перевизначення типового набору -Файлові журнали та транскрипти сеансів залишаються у форматі JSONL, але відповідні секретні значення -маскуються до того, як рядок або повідомлення буде записано на диск. Редагування конфіденційних даних працює -за принципом best-effort: воно застосовується до текстового вмісту повідомлень і рядків журналу, але не до кожного -ідентифікатора чи поля бінарного payload. +Файлові логи й транскрипти сеансів залишаються у форматі JSONL, але значення секретів, +що збігаються, маскуються до того, як рядок або повідомлення буде записано на диск. Маскування виконується в межах найкращих зусиль: +воно застосовується до текстового вмісту повідомлень і рядків логів, але не до кожного +ідентифікатора чи поля двійкового payload. ## Діагностика та OpenTelemetry Діагностика — це структуровані, машинозчитувані події для запусків моделей і -телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не** -замінюють журнали — вони живлять метрики, трасування та експортери. Події генеруються +телеметрії потоку повідомлень (Webhook, постановка в чергу, стан сеансу). Вони **не** +замінюють логи — вони живлять метрики, трасування й експортери. Події генеруються в процесі незалежно від того, чи експортуєте ви їх. Дві суміжні поверхні: -- **Експорт OpenTelemetry** — надсилайте метрики, трасування та журнали через OTLP/HTTP до +- **Експорт OpenTelemetry** — надсилання метрик, трасувань і логів через OTLP/HTTP до будь-якого колектора або бекенда, сумісного з OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, - назви метрик/span-ів, змінні середовища та модель конфіденційності описані на окремій сторінці: + назви метрик/span, змінні середовища та модель приватності наведені на окремій сторінці: [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -- **Прапорці діагностики** — цільові прапорці налагоджувального журналювання, які спрямовують додаткові журнали в +- **Прапорці діагностики** — цільові прапорці debug-логів, які спрямовують додаткові логи до `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру - і підтримують wildcard-и (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` - або через перевизначення змінної середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: + й підтримують шаблони з wildcard (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` + або через перевизначення середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: [Прапорці діагностики](/uk/diagnostics/flags). -Щоб увімкнути діагностичні події для плагінів або користувацьких приймачів без експорту OTLP: +Щоб увімкнути діагностичні події для Plugin або користувацьких приймачів без експорту OTLP: ```json5 { @@ -232,16 +241,16 @@ OpenClaw може маскувати чутливі токени до того, Для експорту OTLP до колектора див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -## Поради з усунення неполадок +## Поради з усунення несправностей - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Журнали порожні?** Перевірте, що Gateway запущено і він записує у шлях файлу, - вказаний у `logging.file`. +- **Логи порожні?** Перевірте, що Gateway запущено і він записує у шлях файлу, + указаний у `logging.file`. - **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. ## Пов’язане -- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span-ів, модель конфіденційності -- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці налагоджувального журналювання -- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі WS-журналів, префікси підсистем і захоплення консолі -- [Довідник із конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник по полях `diagnostics.*` +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span, модель приватності +- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці debug-логів +- [Внутрішня будова логування Gateway](/uk/gateway/logging) — стилі WS-логів, префікси підсистем і захоплення консолі +- [Довідник із конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`