chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
103be39a57
commit
63ed20e8bc
@ -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.*`
|
||||
|
||||
@ -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 <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці 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 <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
|
||||
Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level <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.*`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user