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) ресурсы, которые нужно создать до первого запуска:

# Создать сеть (если не существует):
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

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

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

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

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

• 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: настраиваем