Модель диагностики Принтум

Описание

Диагностика в Printum строится по трёхшаговой модели. Цель модели — не перебирать логи наугад, а сначала сузить зону поиска, потом определить конкретное звено в цепочке компонентов, и только затем смотреть логи именно там.

Главный принцип: сначала понять, где проблема — в системе или в инфраструктуре. Потом в какой части системы. Потом смотреть логи.

Четыре шага модели

Шаг	Вопрос	Результат
Шаг 1. Локализация	Система или инфраструктура?	Понимаем, стоит ли вообще смотреть в Printum
Шаг 2. Сценарий и условия	Что именно происходит, у кого, при каких условиях?	Паспорт инцидента: сценарий, масштаб, воспроизводимость
Шаг 3. Карта системы	Какие компоненты участвуют в этом сценарии?	Конкретный контейнер или служба, которую нужно проверить
Шаг 4. Логи	Что написано в логах целевого компонента?	Причина проблемы или следующая гипотеза

Почему именно в таком порядке

Если начать с логов без локализации — потратите время на правильные логи, в которых нет ошибки, потому что проблема вообще за пределами системы. Если не определить сценарий — непонятно, в каком именно контейнере из десятка искать.

Если инженер умеет читать поток данных, он сможет диагностировать систему в любом проекте — в самом лёгком и в самом сложном.

Шаг 1 — Локализация

Цель шага

Понять: проблема находится внутри системы Printum или вне её — в инфраструктуре, сети, настройке принтера, драйвере.

Если проблема вне системы — дальнейшая диагностика Printum не нужна.

Методы проверки

1. Печать в обход системы

Отправьте задание печати напрямую на принтер, минуя Printum: установите принтер как обычный сетевой принтер Windows/Linux и распечатайте тестовую страницу.

Печатает → принтер работает, проблема в системе Printum
Не печатает → проблема в принтере, драйвере или сети

2. Другой принтер

Воспроизведите то же действие на другом устройстве того же типа или в другом подразделении.

На другом работает → проблема связана именно с этим устройством: настройки, доступность по сети, драйвер
На всех не работает → системная причина или инфраструктурная: сеть, домен, конфигурация

3. Другой пользователь

Попросите другого сотрудника воспроизвести проблему под своей учётной записью.

У другого работает → проблема привязана к конкретной УЗ: права, правила печати, карта
У всех не работает → системная или групповая причина

4. SNMPwalk

Выполните опрос устройства по SNMP вручную, чтобы проверить доступность и ответ принтера.

snmpwalk -v2c -c public <IP_принтера> 1.3.6.1.2.1.1

Получено ожидаемое значение → принтер доступен по SNMP, отдает корректные данные
Нет ответа / timeout → проблема в сети, SNMP отключен, community-строка не совпадает, устройство недоступно

Сетевой агент Printum опрашивает устройства по порту 161 и получает ответ по порту 162 (протокол SNMP). Если snmpwalk не отвечает — агент тоже не получит данных.

Результат шага

После проверки становится ясно:

Проблема в инфраструктуре → передать в соответствующую команду
Проблема в системе Printum → переходим к Шагу 2.

Шаг 2 — Сценарий и условия

Цель шага

Точно описать, при каких условиях и у кого проявляется проблема, прежде чем искать её в системе. Чем точнее паспорт инцидента, тем быстрее находится нужный компонент.

Сценарий

Определите, какой именно процесс не работает:

Категория	Варианты
Печать	прямая / отложенная; с клиентом ПринтМенеджер / без клиента (бесклиентская)
Авторизация	PIN / карта / внешняя авторизация
Отчёты	веб / файл (Excel) / почта
Синхронизация	ручная / по расписанию (домен, М→ПМ)
Сканирование / Копирование	через встроенное приложение
Копирование	с сохранением образа / без сохранения образа
Мониторинг принтеров	поиск устройств / опрос устройств

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

Условия

Зафиксируйте технические характеристики окружения:

Версия системы — версия Мониторинга и/или ПринтМенеджера
ОС сервера — на чём развёрнута система
Контроллер домена — версия AD/LDAP
Конфигурация — single (один сервер) / cluster (с балансировкой) / филиальная сеть

Масштаб

Сколько объектов затронуто — это ключ к поиску общего знаменателя.

Объект	Варианты	Что искать при группе
Устройства	одно / группа / все	локация, вендор, модель, подсеть
Пользователи	один / группа / все	подразделение, OU, тип авторизации, роль
Документы	один / группа / все	формат, размер, программа-источник

Если проблема у группы — ищите что объединяет эту группу: одна локация, один вендор устройств, одна OU в домене.

Воспроизводимость

Всегда — ошибка стабильная, легче диагностировать: запускаем сценарий и сразу видим в логах
Иногда — нестабильная ошибка; нужно включить режим DEBUG и воспроизводить повторно, или смотреть частоту в логах за период

Результат шага

Заполненный Паспорт инцидента с описанием сценария, условий, масштаба и воспроизводимости. На основе этих данных строим карту системы.

Шаг 3 — Карта системы

Ключевая мысль

Проблема всегда находится в конкретном звене цепочки. После локализации и заполнения паспорта инцидента — определите цепочку компонентов для своего сценария, выберите предполагаемое звено и смотрите соответствующие логи.

Если инженер умеет читать поток данных, он сможет понять, где именно у нас в этом месте в потоке данных сломалась передача.

Пример 1: Задание не печатается

Элемент	Описание
Сценарий	Прямая или отложенная печать с клиентом ПринтМенеджер
Цепочка компонентов	АРМ → Клиент ПМ → Nginx (порт 8080) → Django (printmanager-app) → CUPS (printmanager-cups) → МФУ (порт 631)
Где искать	Проверьте: дошло ли задание до сервера ПМ; принял ли его CUPS; передал ли CUPS на МФУ
Какие логи	printmanager-app , printmanager-cups , printmanager-celery-print-queue

Типичные ошибки: CUPS: Unable to send job to printer, CUPS: Unable to write print data: Broken pipe

Пример 2: Нет данных по принтеру (не отображается в системе)

Элемент	Описание
Сценарий	Мониторинг — устройство не появляется в личном кабинете
Цепочка компонентов	МФУ → Сетевой агент (SNMP, порты 161/162) → Nginx → Django → ClickHouse → Celery (printum_worker) → PostgreSQL → Личный кабинет
Где искать	1) Устройство отвечает по SNMP? (snmpwalk) 2) Агент передал данные на сервер? 3) Данные попали в ClickHouse? 4) Celery обработал и записал в PostgreSQL?

Типичные ошибки: ERROR [apps.inv.services.sync]: Some snmp data missing for printer 1, Failed to connect to clickhouse:9000

Пример 3: Пользователь не авторизуется

Элемент	Описание
Сценарий	Авторизация на МФУ по карте или PIN через встроенное приложение
Цепочка компонентов (карта)	Карта → Картридер → Django (printmanager-app) → PostgreSQL (поиск пользователя)
Цепочка компонентов (PIN / внешняя)	МФУ → Встроенное приложение → Nginx → Django (printmanager-app) → PostgreSQL
Где искать	Пользователь существует в системе? Карта сопоставлена? Данные синхронизированы из домена?
Какие логи	printmanager-app , printmanager-converter-server

Типичные ошибки: AUTH_ERROR: Invalid credentials, User matching query does not exist

Как читать цепочку

Каждая стрелочка — это передача данных. Если пользователь не видит результат, значит разрыв произошёл где-то между звеньями в цепочке. Метод диагностики: двигайтесь по цепочке от начала до конца ~~к началу~~ (или отв ~~начала~~обратном ~~к концу)~~порядке) и проверяйте каждое звено по его логам.