diff --git a/docs/uk/logging.md b/docs/uk/logging.md index c36b7fe26..74ff8dd2d 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-26T21:17:02Z" + generated_at: "2026-04-26T22:05:00Z" model: gpt-5.4 provider: openai - source_hash: ece4fe127194144fccda44d42903cdbb989183b6e87aedf9ac2470704be26bdb + source_hash: 6fb71b94a5c4fb8db9c704552f73f364b45c9d19bfb74c92abe1f22576fe1480 source_path: logging.md workflow: 15 --- -OpenClaw має дві основні поверхні логування: +OpenClaw має дві основні поверхні журналювання: -- **Файлові логи** (рядки JSON), які записує Gateway. +- **Файлові журнали** (рядки 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 МБ). -OpenClaw зберігає до п’яти пронумерованих архівів поруч з активним файлом, наприклад -`openclaw-YYYY-MM-DD.1.log`, і продовжує писати в новий активний лог, а не -приглушує діагностичні дані. +Кожен файл ротується, коли досягає `logging.maxFileBytes` (типово: 100 MB). +OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом, наприклад +`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,32 @@ 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-кольори. +- `--no-color`: вимкнути кольори ANSI. Коли ви передаєте явний `--url`, CLI не застосовує автоматично конфігурацію чи -облікові дані із середовища; додайте `--token` самостійно, якщо цільовий Gateway -потребує автентифікації. +облікові дані середовища; якщо цільовий Gateway +вимагає автентифікацію, вкажіть `--token` самостійно. -У режимі JSON CLI виводить об’єкти з тегом `type`: +У режимі JSON CLI виводить об’єкти з міткою `type`: - `meta`: метадані потоку (файл, курсор, розмір) -- `log`: розібраний запис логу +- `log`: розібраний запис журналу - `notice`: підказки про обрізання / ротацію -- `raw`: нерозібраний рядок логу +- `raw`: нерозібраний рядок журналу -Якщо Gateway на local loopback запитує pairing, `openclaw logs` автоматично -перемикається на налаштований локальний файл логу. Для явних цілей `--url` -цей резервний варіант не використовується. +Якщо локальний loopback Gateway запитує сполучення, `openclaw logs` автоматично +перемикається на налаштований локальний файл журналу. Явні цілі `--url` не +використовують цей резервний варіант. Якщо Gateway недоступний, CLI виводить коротку підказку виконати: @@ -94,38 +94,49 @@ openclaw doctor Вкладка **Logs** у Control UI відстежує той самий файл за допомогою `logs.tail`. Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як її відкрити. -### Логи лише каналів +### Журнали лише каналу -Щоб відфільтрувати активність каналів (WhatsApp/Telegram тощо), використовуйте: +Щоб відфільтрувати активність каналу (WhatsApp/Telegram тощо), використовуйте: ```bash openclaw channels logs --channel whatsapp ``` -## Формати логів +## Формати журналів -### Файлові логи (JSONL) +### Файлові журнали (JSONL) -Кожен рядок у файлі логу — це об’єкт JSON. CLI і Control UI розбирають ці -записи, щоб показувати структурований вивід (час, рівень, підсистема, повідомлення). +Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI розбирають ці +записи для відображення структурованого виводу (час, рівень, підсистема, повідомлення). + +Записи JSONL файлового журналу також містять машинно-фільтровані поля верхнього рівня, коли вони доступні: + +- `hostname`: ім’я хоста gateway. +- `message`: зведений текст повідомлення журналу для повнотекстового пошуку. +- `agent_id`: id активного агента, коли виклик журналу містить контекст агента. +- `session_id`: id/ключ активної сесії, коли виклик журналу містить контекст сесії. +- `channel`: активний канал, коли виклик журналу містить контекст каналу. + +OpenClaw зберігає оригінальні структуровані аргументи журналу поряд із цими полями, +щоб наявні парсери, які читають нумеровані ключі аргументів tslog, продовжували працювати. ### Вивід консолі -Логи консолі **враховують TTY** і форматуються для зручності читання: +Журнали консолі **з урахуванням TTY** і відформатовані для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) -- Кольорове позначення рівнів (info/warn/error) +- Кольорове виділення рівнів (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` Приклади: @@ -136,9 +147,9 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## Налаштування логування +## Налаштування журналювання -Усі налаштування логування зберігаються в `logging` у `~/.openclaw/openclaw.json`. +Усі налаштування журналювання розміщені в `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -153,85 +164,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`), щоб зовнішні обробники журналів могли співвідносити рядок +із діапазонами OTEL та поширенням `traceparent` у провайдера. -HTTP-запити Gateway і WebSocket-фрейми Gateway створюють внутрішню область трасування запиту. -Логи й діагностичні події, згенеровані в межах цієї асинхронної області, успадковують -трасування запиту, якщо не передано явний контекст трасування. Трасування запуску агента й -виклику моделі стають дочірніми до активного трасування запиту, тому локальні логи, -діагностичні знімки, span OTEL і довірені заголовки провайдера `traceparent` можна -пов’язати через `traceId` без логування сирого вмісту запиту або моделі. +HTTP-запити Gateway і кадри WebSocket Gateway створюють внутрішню область трасування запиту. +Журнали й діагностичні події, створені в межах цієї асинхронної області, успадковують +трасування запиту, якщо їм не передано явний контекст трасування. Трасування запуску агента й +виклику моделі стають дочірніми для активного трасування запиту, тому локальні журнали, +діагностичні знімки, діапазони OTEL і довірені заголовки `traceparent` провайдера можна +об’єднати за `traceId` без журналювання сирого вмісту запиту чи моделі. -### Розмір і час виклику моделі +### Розмір і тривалість виклику моделі -Діагностика викликів моделі записує обмежені вимірювання запиту/відповіді без -захоплення сирого вмісту prompt або відповіді: +Діагностичні дані виклику моделі фіксують обмежені вимірювання запиту/відповіді без +захоплення сирого вмісту запиту або відповіді: -- `requestPayloadBytes`: розмір у байтах UTF-8 фінального payload запиту до моделі +- `requestPayloadBytes`: розмір у байтах UTF-8 фінального корисного навантаження запиту до моделі - `responseStreamBytes`: розмір у байтах UTF-8 подій потокової відповіді моделі -- `timeToFirstByteMs`: затримка до першої події потокової відповіді +- `timeToFirstByteMs`: минулий час до першої події потокової відповіді - `durationMs`: загальна тривалість виклику моделі -Ці поля доступні для діагностичних знімків, hook-ів Plugin для викликів моделі та -span/метрик OTEL для викликів моделі, коли ввімкнено експорт діагностики. +Ці поля доступні для діагностичних знімків, хуків Plugin виклику моделі та +діапазонів/метрик виклику моделі OTEL, коли ввімкнено експорт діагностики. ### Стилі консолі `logging.consoleStyle`: -- `pretty`: зручний для людини, кольоровий, з часовими мітками. +- `pretty`: зручний для читання людиною, кольоровий, із часовими мітками. - `compact`: щільніший вивід (найкраще для довгих сеансів). -- `json`: JSON у кожному рядку (для обробників логів). +- `json`: JSON на рядок (для обробників журналів). ### Редагування конфіденційних даних -OpenClaw може маскувати конфіденційні токени до того, як вони потраплять у вивід консолі, -файлові логи, записи логів OTLP або збережений текст транскрипту сеансу: +OpenClaw може маскувати конфіденційні токени до того, як вони потраплять у вивід консолі, файлові журнали, +записи журналів OTLP або збережений текст стенограми сесії: - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: список рядків regex для перевизначення типового набору -Файлові логи й транскрипти сеансів залишаються у форматі JSONL, але значення секретів, -що збігаються, маскуються до того, як рядок або повідомлення буде записано на диск. Маскування виконується в межах найкращих зусиль: -воно застосовується до текстового вмісту повідомлень і рядків логів, але не до кожного -ідентифікатора чи поля двійкового payload. +Файлові журнали й стенограми сесій залишаються у форматі JSONL, але значення секретів, які збігаються, +маскуються до того, як рядок або повідомлення буде записано на диск. Маскування виконується за принципом best-effort: +воно застосовується до текстового вмісту повідомлень і рядків журналу, але не до кожного +ідентифікатора чи поля двійкового корисного навантаження. ## Діагностика та OpenTelemetry -Діагностика — це структуровані, машинозчитувані події для запусків моделей і -телеметрії потоку повідомлень (Webhook, постановка в чергу, стан сеансу). Вони **не** -замінюють логи — вони живлять метрики, трасування й експортери. Події генеруються -в процесі незалежно від того, чи експортуєте ви їх. +Діагностичні дані — це структуровані, машинозчитувані події для запусків моделей і +телеметрії потоку повідомлень (Webhooks, постановка в чергу, стан сесії). Вони **не** +замінюють журнали — вони живлять метрики, трасування та експортери. Події створюються +в процесі незалежно від того, експортуєте ви їх чи ні. Дві суміжні поверхні: -- **Експорт OpenTelemetry** — надсилання метрик, трасувань і логів через OTLP/HTTP до +- **Експорт OpenTelemetry** — надсилає метрики, трасування та журнали через OTLP/HTTP до будь-якого колектора або бекенда, сумісного з OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, - назви метрик/span, змінні середовища та модель приватності наведені на окремій сторінці: + назви метрик/діапазонів, змінні середовища й модель конфіденційності описані на окремій сторінці: [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -- **Прапорці діагностики** — цільові прапорці debug-логів, які спрямовують додаткові логи до +- **Прапорці діагностики** — цільові прапорці налагоджувальних журналів, які спрямовують додаткові журнали до `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру - й підтримують шаблони з wildcard (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` - або через перевизначення середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: + і підтримують шаблони з підстановками (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` + або через перевизначення змінною середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: [Прапорці діагностики](/uk/diagnostics/flags). -Щоб увімкнути діагностичні події для Plugin або користувацьких приймачів без експорту OTLP: +Щоб увімкнути діагностичні події для Plugins або власних приймачів без експорту OTLP: ```json5 { @@ -239,18 +250,18 @@ OpenClaw може маскувати конфіденційні токени д } ``` -Для експорту OTLP до колектора див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry). +Щоб налаштувати експорт OTLP до колектора, див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry). ## Поради з усунення несправностей - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Логи порожні?** Перевірте, що Gateway запущено і він записує у шлях файлу, - указаний у `logging.file`. -- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. +- **Журнали порожні?** Переконайтеся, що Gateway запущено і він записує у шлях до файла, + вказаний у `logging.file`. +- **Потрібно більше деталей?** Встановіть `logging.level` у `debug` або `trace` і повторіть спробу. ## Пов’язане -- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span, модель приватності -- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці debug-логів -- [Внутрішня будова логування Gateway](/uk/gateway/logging) — стилі WS-логів, префікси підсистем і захоплення консолі -- [Довідник із конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/діапазонів, модель конфіденційності +- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці налагоджувальних журналів +- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`