Настройка логирования

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

Kodel.AI использует иерархическую систему логирования на базе pino. Уровни задаются в YAML-конфиге — без перекомпиляции.

Конфигурация

Секция logging в config.override.yaml (или config/default.yaml):

logging:
  default: info        # уровень по умолчанию
  file:
    enabled: false     # запись в файл
    path: logs/app.log
  levels:
    kodel: info        # все сервисы сервера
    kodel.assistant: debug
    kodel.llm: warn

После изменения нужен перезапуск сервера:

docker compose up -d --no-deps server

Иерархия уровней

Принцип такой же, как в log4j/logback: более специфичный ключ переопределяет общий.

kodel: info
└── kodel.assistant: debug     ← все сервисы домена assistant получат DEBUG
    └── kodel.assistant.AssistantController: warn  ← только этот сервис — WARN

Поиск идёт от самого специфичного к общему:

kodel.assistant.AssistantService → нет
kodel.assistant → debug ✓

Уровни логирования

Уровень	Значение
`fatal`	Сервер не может продолжить работу
`error`	Ошибка операции, требует внимания
`warn`	Нештатная ситуация, работа продолжается
`info`	Бизнес-события (по умолчанию)
`debug`	Детали для отладки
`verbose`	Подробный трейс каждого шага

Домены

Каждый модуль сервера логирует под своим доменом:

Домен	Модули
`kodel.assistant`	AI-ассистент, agent-debug
`kodel.llm`	LLM вызовы и логи
`kodel.repo`	Индексация репозиториев
`kodel.tasks`	Задачи, workflow
`kodel.auth`	Авторизация, организации
`kodel.infra`	Инстансы, SSH-прокси
`kodel.ai`	AI-jobs, step-action-engine

Сценарии

Включить DEBUG для одного модуля

logging:
  levels:
    kodel.assistant: debug

Включить DEBUG для всего сервера

logging:
  default: debug

Заглушить шумный модуль

logging:
  levels:
    kodel: info
    kodel.repo: warn   # индексация слишком многословна

Включить запись в файл

logging:
  file:
    enabled: true
    path: logs/app.log

Файл содержит JSON-строки (формат pino). Stdout продолжает выводить pretty-формат.

```bash docker compose exec server tail -f logs/app.log | jq . ``` ```bash # pino level: error=50, fatal=60 cat logs/app.log | jq 'select(.level >= 50)' ``` ```bash cat logs/app.log | jq 'select(.context | startswith("kodel.assistant"))' ```

Формат вывода

stdout (pino-pretty, colorized):

[14:23:01.542] INFO: AssistantService Processing chat request for conversation abc123
[14:23:01.891] DEBUG: LlmCallService Calling anthropic claude-sonnet-4-5 with 1240 tokens
[14:23:03.210] INFO: AssistantService Chat complete, 3 tool calls executed

Файл (raw JSON от pino):

{"level":30,"time":1744380181542,"context":"AssistantService","msg":"Processing chat request"}
{"level":20,"time":1744380181891,"context":"LlmCallService","msg":"Calling anthropic..."}

Переменная окружения

Уровень по умолчанию можно задать через env (используется если секция logging не задана):

KODEL_LOGGING_DEFAULT=debug docker compose up -d server