Логирование

Mayros ведет логи в двух местах:

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

Эта страница объясняет, где находятся логи, как их читать и как настраивать уровни логирования и форматы.

Где находятся логи

По умолчанию Gateway записывает ротирующийся файл лога:

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

Дата использует локальный часовой пояс хоста gateway.

Вы можете переопределить это в ~/.mayros/mayros.json:

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

Как читать логи

CLI: живой tail (рекомендуется)

Используйте CLI для tail файла лога gateway через 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

Панель управления (веб)

Вкладка Logs панели управления делает tail того же файла, используя 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: список regex строк для переопределения набора по умолчанию

Редактирование влияет только на вывод консоли и не изменяет файловые логи.

Диагностика - это структурированные, машиночитаемые события для запусков моделей и телеметрии потока сообщений (вебхуки, очереди, состояние сессии). Они не заменяют логи; они существуют для метрик, трейсов и других экспортеров.

События диагностики генерируются внутри процесса, но экспортеры подключаются только когда диагностика + плагин экспортера включены.

OpenTelemetry против OTLP

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

Экспортируемые сигналы

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

Каталог событий диагностики

Использование модели:

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

Поток сообщений:

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
  }
}

Флаги диагностики (целевые логи)

Используйте флаги для включения дополнительных, целевых debug логов без повышения logging.level. Флаги нечувствительны к регистру и поддерживают маски (например, telegram.* или *).

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

Переопределение через окружение (разовое):

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
    }
  }
}