1C Log Parser Service

Сервис для парсинга журналов регистрации и технологического журнала 1С:Предприятие с загрузкой в ClickHouse. Предоставляет визуализацию в Grafana и MCP-интерфейс для AI-агентов.

📘 Для AI-агентов: См. README_AI.md — детальная техническая информация для разработки и использования проекта.

---

📋 Содержание

• Обзор
• Возможности
• Архитектура
• Требования
• Быстрый старт
• Конфигурация
• Таблицы ClickHouse
• Дашборды Grafana
• Troubleshooting
• Документация
• TODO
• Благодарности

---

Обзор

Этот проект обеспечивает:

• Парсинг логов 1С (журнал регистрации .lgf/.lgp и технологический журнал)
• Хранение в ClickHouse с партиционированием и TTL
• Визуализацию в Grafana (дашборды активности, ошибок, новых проблем)
• MCP-интерфейс для AI-агентов (компактный/полный JSON)

---

Возможности

Журнал регистрации

• ✅ Чтение форматов .lgf, .lgp, .lgx
• ✅ Поддержка серверных и файловых баз
• ✅ Контроль дубликатов (опционально)
• ✅ Доп.колонка с Нормализованным текстом комментария
• ✅ Идентификация по GUID кластера и базы
• ✅ Журнал регистрации на 30Гб и 250млн строк ~50 минут (без дедупликации)
• ✅ Параллельное чтение всех файлов (всех баз)

Технологический журнал

• ✅ Парсинг текстового формата (иерархический/plain)
• ✅ Парсинг JSON формата
• ✅ Сохранение всех свойств событий
• ✅ Обработка ротации и сжатия (zip)
• на больших объемах пока не гонял, на тестах ~170 записей в секунду (при параллельном чтении файлов)
• ✅ Параллельное чтение всех файлов

ClickHouse

• ✅ Таблицы:
  • event_log, tech_log - для хранения результатов парсинга
  • file_reading_progress - информация о прогрессе чтения файлов логов
  • parser_metrics_extended - контроль/анализ производительности
• ✅ Партиционирование по дням
• ✅ Настраиваемый TTL (по умолчанию 30 дней)

Grafana

• ✅ Dashboard: 1C Event Log - Overview (Общая активность)
• ✅ Dashboard: 1C Event Log - Errors (новые ошибки за 24 часа, нормализация ошибок)
• ✅ Dashboard: 1C Event Log - Explorer (полный Журнал регистрации с фильтрами)
• ✅ Dashboard: 1C Event Log - Metadata Analysis (аналитика по методанным)
• ✅ Dashboard: 1C Event Log - Temporal Patterns (графики активности) Для удаления предустановленных дашбордов удалите файлы в каталоге /deploy/grafana/provisioning/dashborads/

MCP для AI-агентов

Чтение логов:

• ✅ logc_get_event_log: получение логов журнала регистрации
• ✅ logc_get_tech_log: получение технологического журнала
• ✅ logc_get_actual_log_timestamp: получение максимальной отметки времени в логах для базы

Настройка техжурнала:

• ✅ logc_save_techlog: сохранение текущей конфигурации как backup (.OLD)
• ✅ logc_configure_techlog: генерация logcfg.xml
• ✅ logc_restore_techlog: восстановление конфигурации из backup (.OLD)
• ✅ logc_disable_techlog: отключение техжурнала
• ✅ logc_get_techlog_config: чтение текущей конфигурации

Режимы вывода:

• ✅ minimal (компактный, экономия токенов)
• ✅ full (все поля для детального анализа)

---

Архитектура

Windows Host (1C Logs)
    ↓ (volume mount, read-only)
Docker Compose Stack
    ├── log-parser (Go)
    │   ├── Event Log Reader
    │   ├── Tech Log Tailer
    │   ├── Batch Writer
    │   └── Offset Storage (BoltDB)
    │
    ├── ClickHouse
    │   ├── event_log table
    │   └── tech_log table
    │
    ├── MCP Server (Go)
    │   ├── get_event_log tool
    │   └── get_tech_log tool
    │
    └── Grafana
        └── Auto-provisioned Dashboards

AI Agent (Claude, etc.) ← MCP protocol

Технологический стек

• Язык: Go 1.21+
• База данных: ClickHouse 23.8+
• Визуализация: Grafana 11.0+
• Контейнеризация: Docker + Docker Compose
• Offset Storage: BoltDB
• Observability: OpenTelemetry (трейсинг), zerolog (логирование)

---

Требования

• Docker Desktop 20+
• Docker Compose 3.8+
• Windows (для доступа к логам 1С)
• 1С:Предприятие 8.3+ (источник логов)

---

Быстрый старт

1. Клонирование репозитория

git clone <repository-url>
cd 1c-log-checker

2.1. Настройка путей и каталогов

Откройте /deploy/docker/ Скопируйте пример конфигурации: .env.example --> .env Отредактируйте deploy/docker/.env и укажите пути:

LOG_DIRS=C:\Program Files\1cv8\srvinfo
TECHLOG_CONFIG_DIR=D:\My Projects\FrameWork 1C\1c-log-checker\configs\techlog\
TECHLOG_DIRS=D:\My Projects\FrameWork 1C\1c-log-checker\tech_logs

#установите вашу тайм-зону (читай раздел специфика работы со временем)
TZ=Europe/Moscow

Переопределите место хранения конфигурации технологического журнала (сервис не может работать с системной директорией). По-умолчанию я предлагаю его поместить в каталоге проекта. Файл будет создан в /configs/techlog/logcfg.xml.

Согласно ИТС (https://its.1c.ru/db/v8311doc#bookmark:adm:TI000000376) в файл conf.cfg нужно добавить строку, указывающую где платформе искать файлы конфига, если их нет в "стандартном каталоге". conf.cfg хранится в нескольких местах - первично читается из каталога с платформой конкретной версии. В нем указана переадресация в каталог C:\Program Files\1cv8\conf, что бы для всех версий использовались одни настройки. Переопределить каталог еще раз из директории C:\Program Files\1cv8\conf\ НЕ удаётся (на 8.3.27 не сработало), поэтому переопределяем в каталоге каждой платформе, которую используем (Пример: C:\Program Files\1cv8\8.3.27.1719\bin\conf)

# Указываем тот же путь, что указали в файле deploy/docker/.env в параметре TECHLOG_CONFIG_DIR
ConfLocation=D:\ProjectCatalog\configs\techlog\

3. Настройки для работы через ИИ-агента

3.1. Подключить Skill для работы с ТЖ

Установить проект https://github.com/SteelMorgan/cursor-anthropic-skills/ или хотя бы отдельно навык /tree/main/custom-skills/TECHLOG_SKILL.md. Проект обеспечивает подхватывание навыка агентом самостоятельно, если ставите навык отдельно - то для Cursor подключайте как Project Rule, для Claude Cod как обычный навык. Что в навыке:

• объясняет агенту workflow для ТЖ
• ключевые знания по работе с ТЖ

3.2. Подключить МСР

Если MCP-клиент запускается в отдельном Docker-контейнере, ему нужен сетевой доступ к контейнеру 1c-log-mcp.

Специальный случай: если используется проект https://github.com/SteelMorgan/1c-ai-sandbox-client-server, контейнер 1c-log-mcp должен быть подключён к сети infra, чтобы локальный AI-контейнер мог обращаться к MCP по имени контейнера, например http://1c-log-mcp:8080.

Во всех остальных случаях управление сетевой связностью между Docker-контейнерами остаётся на вас и вашем AI-агенте: обеспечьте маршрут и DNS/hostname между контейнером с AI и контейнером 1c-log-mcp удобным для вашей инфраструктуры способом.

# HTTP
{
  "mcpServers": {
    "1c-log-checker": {
      "url": "http://localhost:8080",
      "transport": "http"
    }
  }
}

Примечание: если клиент работает не на хосте, а внутри Docker-сети, вместо localhost может понадобиться имя контейнера или иной адрес, доступный из сети этого клиента.

# STDIO
{
  "mcpServers": {
    "1c-log-checker": {
      "command": "docker",
      "args": [
        "exec", "-i", "1c-log-mcp",
        "/app/mcp"
      ],
      "env": {
        "MCP_MODE": "stdio",
        "CLICKHOUSE_HOST": "clickhouse",
        "CLICKHOUSE_PORT": "9000",
        "CLICKHOUSE_DB": "logs",
        "CLICKHOUSE_USER": "logchecker",
        "CLICKHOUSE_PASSWORD": "logchecker"
      }
    }
  }
}

Важно: в текущем Docker-окружении удалённые подключения под пользователем default могут завершаться AUTHENTICATION_FAILED. Для контейнерных подключений используйте сервисного пользователя logchecker.

4. Настройка GUID-маппинга

⚠️ ОБЯЗАТЕЛЬНО: Для работы сервиса требуется создать папку configs в корне проекта (если её нет) и разместить там файл cluster_map.yaml. Образец файла находится в configs/cluster_map.yaml.example. Подсказка агенту куда смотреть в описании инструментов.

Это необходимо, чтобы агент знал GUID базы/кластера, с которыми работает в проекте, и мог обращаться за логами конкретной базы.

Шаги:

1. Создайте папку configs в корне проекта (если её нет)
2. Скопируйте образец: configs/cluster_map.yaml.example → configs/cluster_map.yaml
3. Отредактируйте configs/cluster_map.yaml и укажите реальные GUID ваших кластеров и баз

clusters:
  "your-cluster-guid":
    name: "Production Cluster"

infobases:
  "your-infobase-guid":
    name: "ERP Production"
    cluster_guid: "your-cluster-guid"

Как получить GUIDы — см. docs/guides/get-guids.md или любой другой удобный для вас способ (в гугле много вариантов) Альтернативный вариант - посмотреть данные в таблице logs.file_reading_progress после запуска сервиса парсера

4. Подготовка внешних ресурсов Docker

docker-compose.yml использует внешние (external) ресурсы, которые нужно создать до первого запуска:

Ресурс	Тип	Откуда берётся	Зачем
infra	network	Общая сеть для связи между Docker-стеками	MCP-сервер доступен другим контейнерам по имени 1c-log-mcp
agent-work-sandbox-1c	volume	Devcontainer (создаётся автоматически)	SSH-ключ для sshfs в devcontainer-окружении

# Создать сеть (если не существует):
docker network create infra

# Volume agent-work-sandbox-1c нужен ТОЛЬКО в devcontainer-окружении.
# На обычном хосте (Windows/Linux) удалите секцию work_data из docker-compose.yml
# и укажите путь к SSH-ключу напрямую через ONEC_SSH_KEY в .env.

Примечание: если вы запускаете проект НЕ из devcontainer, уберите volume work_data из docker-compose.yml и замените mount SSH-ключа на прямой bind mount файла.

5. Запуск

cd deploy/docker
docker compose up -d
# или через Makefile:
make infra-up

6. Проверка

• ClickHouse: http://localhost:8123/play
• Grafana: http://localhost:3000 (без авторизации, если хотите - можно настроить, попросите агента)
• MCP Server: http://localhost:8080

---

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

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

Переменная	Описание	По умолчанию
LOG_DIRS	Пути к каталогам журнала регистрации (через ;)	-
TECHLOG_DIRS	Пути к каталогам технологического журнала (через ;)	-
CLICKHOUSE_HOST	Хост ClickHouse	localhost
CLICKHOUSE_PORT	Порт ClickHouse	9000
CLICKHOUSE_DB	База данных ClickHouse	logs
CLICKHOUSE_USER	Пользователь ClickHouse	logchecker
CLICKHOUSE_PASSWORD	Пароль ClickHouse	logchecker
LOG_RETENTION_DAYS	Срок хранения логов (дни)	30
READ_ONLY	Технический режим (только чтение, без записи в CH)	false
MCP_PORT	Порт MCP-сервера	8080
MAX_WORKERS	Количество параллельных потоков внутри каждого reader/tailer	4
MAX_GLOBAL_WORKERS	Глобальный лимит параллельных воркеров (<=0 отключает лимит)	0
BATCH_SIZE	Размер батча для записи в ClickHouse	5000
BATCH_FLUSH_TIMEOUT	Таймаут флуша батча в миллисекундах	1000
ENABLE_DEDUPLICATION	Включить проверку дубликатов записей	false
LOG_LEVEL	Уровень логирования: debug = дебаг-файл (/logs/parser_all_records.jsonl), info/warn/error = логи сервиса в файл (/logs/parser.log, /logs/mcp.log)	error

В принципе ключевые переменные указаны в разделе "Быстрый старт".

Файлы конфигурации

• deploy/docker/.env — переменные окружения (скопируйте из deploy/docker/.env.example)
• configs/cluster_map.yaml — маппинг GUID → имена кластеров/баз (размещается в папке configs в корне проекта, образец в configs/cluster_map.yaml.example)
• deploy/docker/docker-compose.yml — конфигурация Docker Compose

---

Таблицы ClickHouse

event_log

Хранит события журнала регистрации 1С (.lgf/.lgp форматы).

Основные поля:

• event_time — дата и время события
• level — уровень события (Error, Warning, Information, Note)
• infobase_name - имя базы
• event_presentation — Событие (например, "Данные. Изменение")
• user_name — имя пользователя
• metadata_presentation — представление объекта метаданных (Документ.УстановкаЦенНоменклатуры)
• data_presentation — представление данных (Установка цен номенклатуры -0000002228 от 01.11.2025)
• comment — комментарий к событию (это же текст ошибки)
• comment_normalized — нормализованный комментарий ошибки (для агрегации по видам ошибок). Заполняется асинхронно после записи записи в таблицу для записей с level = 'Error'. Динамические части (GUID, timestamp, числа, строки) заменяются на плейсхолдеры (<GUID>, <TIMESTAMP>, <NUMBER>, <STRING>)

Структура:

• Партиционирование по дням (event_date)
• TTL: настраиваемый через LOG_RETENTION_DAYS (по умолчанию 30 дней)
• Первичный ключ (ORDER BY): cluster_guid, infobase_guid, event_time, session_id, record_hash
• Вторичные индексы: на все основные поля (level, event, user_name, metadata и др.)

tech_log

Хранит события технологического журнала 1С (text и json форматы).

Основные поля:

• ts — временная метка события
• name — тип события (EXCP, DBMSSQL, TLOCK, CONN и др.)
• level — уровень (ERROR, WARN, INFO)
• duration — длительность операции в микросекундах
• session_id, transaction_id — идентификаторы сеанса и транзакции

Динамические свойства (зависят от типа события):

• sql, plan_sql_text — для SQL-запросов (DBMSSQL, DBPOSTGRS)
• exception, exception_descr — для исключений (EXCP)
• query, sdbl — для запросов к модели данных (SDBL)
• И другие свойства в зависимости от типа события (каждое свойство сохранено в отдельную колонку)

Структура:

• Партиционирование по дням
• TTL: настраиваемый через LOG_RETENTION_DAYS (по умолчанию 30 дней)
• Первичный ключ (ORDER BY): cluster_guid, infobase_guid, name, ts, record_hash
• Вторичные индексы: на все основные поля (level, duration, session_id, sql, exception и др.)

---

Дашборды Grafana

Activity (activity.json)

Общая активность системы

• Графики активности по времени (частота событий)
• Распределение по уровням (Error, Warning, Information, Note)
• Список последних событий с фильтрами
• Статистика по базам и кластерам

New Errors (new-errors.json)

Новые ошибки за последние 24 часа

• Ошибки, появившиеся впервые за период
• Автообновление каждую минуту
• Статистика по базам и кластерам
• Группировка по типам ошибок
• Примеры записей для каждой ошибки

Top Errors (top-errors.json)

Наиболее частые ошибки

• Топ ошибок по количеству повторений
• Группировка по типам событий
• Фильтры по базе, пользователю, временному диапазону
• Тренды появления ошибок

Tech Log (techlog.json)

Технологический журнал

• Длительные операции — события с duration > порога
• Блокировки — события TLOCK, TTIMEOUT, TDEADLOCK
• SQL запросы — события DBMSSQL, DBPOSTGRS с текстом запросов и планами
• Исключения — события EXCP с контекстом выполнения

---

Специфика работы со временем

• Записи в Кликхаус хранятся в таймзоне UTC
• Время в журнале регистрации

---

Troubleshooting

Контейнеры не стартуют

Проблема: Docker контейнеры не запускаются или падают сразу после старта.

Решение:

• Проверьте пути в deploy/docker/.env — они должны существовать на хосте
• Убедитесь, что Docker Desktop запущен
• Проверьте логи: docker logs 1c-log-parser, docker logs 1c-log-mcp
• Проверьте, что порты 8123, 9000, 3000, 8080 не заняты другими процессами

Нет данных в ClickHouse

Проблема: После запуска парсера таблицы в ClickHouse пустые.

Решение:

• Проверьте логи парсера: docker logs 1c-log-parser
• Убедитесь, что пути к логам в LOG_DIRS и TECHLOG_DIRS правильные и доступны
• Проверьте, что логи 1С действительно существуют по указанным путям
• Убедитесь, что парсер имеет права на чтение файлов логов
• Проверьте переменную READ_ONLY — она должна быть false для записи в ClickHouse

GUID не распознаются

Проблема: В логах и интерфейсе отображаются GUID вместо человекочитаемых имен.

Решение:

• Проверьте, что файл configs/cluster_map.yaml существует в корне проекта
• Убедитесь, что структура YAML правильная (см. configs/cluster_map.yaml.example)
• Проверьте, что GUID в файле соответствуют реальным GUID ваших кластеров и баз
• Перезапустите MCP-сервер после изменения cluster_map.yaml

MCP не отвечает

Проблема: AI-агент не может подключиться к MCP-серверу.

Решение:

• Проверьте, что MCP-сервер запущен: docker ps | grep mcp
• Проверьте порт 8080: curl http://localhost:8080/health (должен вернуть {"status":"ok"})
• Проверьте логи: docker logs 1c-log-mcp
• Убедитесь, что в mcp.json указан правильный URL или команда запуска
• Для STDIO режима проверьте переменную окружения MCP_MODE=stdio

Техжурнал не читается

Проблема: Парсер не находит файлы технологического журнала.

Решение:

• Проверьте путь в TECHLOG_DIRS в .env
• Убедитесь, что файл logcfg.xml существует и правильно настроен
• Проверьте, что 1С действительно создает файлы логов по указанному пути
• Проверьте права доступа к каталогу с логами

Техжурнал не формируется

Проблема: 1С не создает файлы технологического журнала.

Решение:

• Проверьте настройки conf.cfg — важно: первичный файл находится в каталоге конкретной версии платформы, например:

  C:\Program Files\1cv8\8.3.27.1719\bin\conf\conf.cfg
  

  А не в C:\Program Files\1cv8\conf\
• Убедитесь, что в conf.cfg указан параметр ConfLocation с правильным путем
• Проверьте, что путь в ConfLocation совпадает с TECHLOG_CONFIG_DIR из .env
• Убедитесь, что файл logcfg.xml существует по указанному пути
• Перезапустите сервер 1С после изменения конфигурации
• Проверьте логи сервера 1С на наличие ошибок чтения конфигурации

---

Документация

• README для AI-агентов — детальная техническая информация для разработки и использования
• Спецификация — полная спека проекта (Requirements/Design/Tasks)
• Исходный запрос — детальное описание требований
• Получение GUIDов — как узнать GUID кластера/базы
• Настройка logcfg.xml — конфигурация технологического журнала
• Использование MCP tools — примеры запросов, режимы, best practices

---

TODO

Навыки и база знаний:

• Сделать корректную нормализацию для tech_log (самому глазами проверить все поля или найти готовое)
• Добавить работу с логами PostgreSQL
• Добавить работу с логами MS SQL
• Создать навык для работы с "MS SQL/PostgreSQL в контексте 1С" (блокировки, RCSI, оптимизация)
• Для работы по Тех.журналу в среде нескольких кластеров нужно:
  • маунтить каталоги C:\Program Files\1cv8\srvinfo каждого сервера отдельно, а в коде реализовать параллельное чтение по всем каталогам с маской /mnt/logs_{ИмяСервераИлиИнойИдентификатор}
  • ✅ писать технологический журнал можно в один "общий" каталог, потому что имя формируется как /{clusterID}/{baseID}/
  • в настройки переменных окружения добавить указанием через запятую для всех путей, которые надо смаунтить в контейнер, а именно:
    • для LOG_DIRS формат записи должен быть LOG_DIRS={ПутьККаталогу_srvinfo_кластера}:/mnt/logs_{clusterID}
    • для TECHLOG_CONFIG_DIR формат записи должен быть TECHLOG_CONFIG_DIR={ПутьККаталогу_с_logcfg_ВажноНеСистемный}:/mnt/logcfg_{clusterID}
    • в идеале бы какую то софтину, в которую можно указать список адресов кластеров 1С, а она выдаст готовую строку для LOG_DIRS и TECH_CONFIG_DIRS (здесь нужно сперва указать путь к несистемной директории в которой платформа будет искать logcfg.xml). Уточнить, возможно проблема с доступом сервиса из докер-контейнера к системной директории только в Windows окружении!

См. подробнее:

• TODO: База знаний SQL

---

Благодарности

Логика парсинга файлов журнала регистрации (.lgp) заимствована из проекта OneSTools.EventLog (автор: akpaevj).

В частности, использованы:

• Структура полей записи журнала регистрации
• Алгоритм парсинга многострочных записей с отслеживанием баланса скобок
• Маппинг значений (уровни событий, приложения, типы событий)
• Парсинг транзакций из hex-формата
• Обработка сложных структур данных См. подробнее: docs/changelog/lgp-parser-enhancement.md

Стек и пример реализации hawkxtreme В частности:

• подбор стека для реализации задачи (Кликхаус и Графана)
• подход к пострению сервиса через парсинг файла журнала вместо "встроенных инструментов"

---

Лицензия

Проект распространяется под лицензией MIT, но если вы используете его в коммерческих целях и он помогает вам генерировать доход - можете отправить Донат. Автору будет приятно, что его труд оценили, а проект получит ресурсы для развития.