Логування

Mayros веде логи в двох місцях:

Файлові логи (рядки JSON), записані Gateway.
Вивід консолі, показаний у терміналах та панелі керування.

Ця сторінка пояснює, де знаходяться логи, як їх читати та як налаштувати рівні логування та формати.

Де знаходяться логи

За замовчуванням Gateway записує ротаційний файл логу за адресою:

/tmp/mayros/mayros-YYYY-MM-DD.log

Дата використовує локальний часовий пояс хоста шлюзу.

Ви можете змінити це в ~/.mayros/mayros.json:

json
{
  "logging": {
    "file": "/path/to/mayros.log"
  }
}

Як читати логи

CLI: live tail (рекомендується)

Використовуйте CLI для відстеження файлу логу шлюзу через RPC:

bash
mayros logs --follow

Режими виводу:

Сесії TTY: гарні, кольорові, структуровані рядки логу.
Не-TTY сесії: простий текст.
--json: JSON, розділений рядками (одна подія логу на рядок).
--plain: примусовий простий текст у сесіях TTY.
--no-color: вимкнути кольори ANSI.

У режимі JSON CLI видає об'єкти з тегом type:

meta: метадані потоку (файл, курсор, розмір)
log: розібраний запис логу
notice: підказки про обрізку / ротацію
raw: нерозібраний рядок логу

Якщо Gateway недоступний, CLI виводить коротку підказку для запуску:

bash
mayros doctor

Панель керування (web)

Вкладка Logs панелі керування відстежує той самий файл, використовуючи logs.tail. Дивіться /web/control-ui, як її відкрити.

Логи лише каналів

Щоб фільтрувати активність каналів (WhatsApp/Telegram/тощо), використовуйте:

bash
mayros channels logs --channel whatsapp

Формати логів

Файлові логи (JSONL)

Кожен рядок у файлі логу — це JSON-об'єкт. CLI та панель керування розбирають ці записи для відображення структурованого виводу (час, рівень, підсистема, повідомлення).

Вивід консолі

Логи консолі враховують TTY та відформатовані для зручності читання:

Префікси підсистем (наприклад, gateway/channels/whatsapp)
Кольорове кодування рівня (info/warn/error)
Необов'язковий компактний або JSON режим

Форматування консолі контролюється logging.consoleStyle.

Налаштування логування

Вся конфігурація логування знаходиться під logging в ~/.mayros/mayros.json.

json
{
  "logging": {
    "level": "info",
    "file": "/tmp/mayros/mayros-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

Рівні логування

logging.level: рівень файлових логів (JSONL).
logging.consoleLevel: рівень деталізації консолі.

--verbose впливає лише на вивід консолі; він не змінює рівні файлових логів.

Стилі консолі

logging.consoleStyle:

pretty: зручний для людини, кольоровий, з мітками часу.
compact: щільніший вивід (найкраще для довгих сесій).
json: JSON на рядок (для процесорів логів).

Редагування

Підсумки інструментів можуть редагувати чутливі токени перед тим, як вони потраплять на консоль:

logging.redactSensitive: off | tools (за замовчуванням: tools)
logging.redactPatterns: список регулярних виразів для заміни типового набору

Редагування впливає тільки на вивід консолі та не змінює файлові логи.

Діагностика — це структуровані, машиночитані події для запусків моделі та телеметрії потоку повідомлень (вебхуки, черга, стан сесії). Вони не замінюють логи; вони існують для живлення метрик, трасувань та інших експортерів.

Події діагностики випромінюються в процесі, але експортери приєднуються лише тоді, коли увімкнені діагностика + плагін експортера.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): модель даних + SDK для трасувань, метрик та логів.
OTLP: дротовий протокол, що використовується для експорту даних OTel до збирача/бекенду.
Mayros експортує через OTLP/HTTP (protobuf) сьогодні.

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

Метрики: лічильники + гістограми (використання токенів, потік повідомлень, черга).
Трасування: проміжки для використання моделі + обробки вебхуків/повідомлень.
Логи: експортовані через OTLP, коли ввімкнено diagnostics.otel.logs. Обсяг логів може бути високим; майте на увазі logging.level та фільтри експортера.

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

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

model.usage: токени, вартість, тривалість, контекст, провайдер/модель/канал, ідентифікатори сесій.

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

webhook.received: вхід вебхуку на канал.
webhook.processed: вебхук оброблено + тривалість.
webhook.error: помилки обробника вебхуку.
message.queued: повідомлення в черзі для обробки.
message.processed: результат + тривалість + необов'язкова помилка.

Черга + сесія:

queue.lane.enqueue: постановка в чергу командної доріжки + глибина.
queue.lane.dequeue: виведення з черги командної доріжки + час очікування.
session.state: перехід стану сесії + причина.
session.stuck: попередження про застряглу сесію + вік.
run.attempt: метадані повторної спроби/спроби запуску.
diagnostic.heartbeat: агреговані лічильники (вебхуки/черга/сесія).

Увімкнути діагностику (без експортера)

Використовуйте це, якщо ви хочете, щоб події діагностики були доступні для плагінів або власних приймачів:

json
{
  "diagnostics": {
    "enabled": true
  }
}

Прапори діагностики (цільові логи)

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

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

Заміна env (одноразова):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Примітки:

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

Експорт до OpenTelemetry

Діагностика може бути експортована через плагін diagnostics-otel (OTLP/HTTP). Це працює з будь-яким збирачем/бекендом OpenTelemetry, який приймає OTLP/HTTP.

json
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "mayros-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}