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

## Описание

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

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

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

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

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

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

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

---

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

### Цель шага

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

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

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

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

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

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

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

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

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

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

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

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

#### 4. Сетевая доступность

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

```
# Для socket
telnet <IP_принтера> 9100
# Для ipp
telnet <IP_принтера> 80
# Для ipps
telnet <IP_принтера> 443
```

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

CUPS системы ПринтМенеджера устанавливает соединение с устройством по стандартным протоколам печати. Если устройство недоступно, то и печать не будет выполнена.

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

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

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

---

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

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

#### Сценарий

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

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

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

#### Условия

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

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

#### Масштаб

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

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

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

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

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

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

Заполненный [паспорт инцидента](https://wiki.printum.io/books/7-ustranenie-neispravnostei/page/pasport-incidenta) с описанием сценария, условий, масштаба и воспроизводимости. На основе этих данных строим карту системы.

---

## Шаг 3 — Карта системы
### Ключевая мысль

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

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

Для ориентирования в компонентах и процессах обработки данных опирайтесь на [карту системы Printum](https://wiki.printum.io/books/8-spravocnik/page/karta-sistemy-printum).

#### Пример 1: Задание не печатается
- Типичные ошибки: `CUPS: Unable to send job to printer`, `CUPS: Unable to write print data: Broken pipe`

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

#### Пример 2: Нет данных по принтеру (не отображается в системе)
- Типичные ошибки: `ERROR [apps.inv.services.sync]: Some snmp data missing for printer 1`, `Failed to connect to clickhouse:9000`

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

#### Пример 3: Пользователь не авторизуется
- Типичные ошибки: `AUTH_ERROR: Invalid credentials`, `User matching query does not exist`

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

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

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

---

## Связанные страницы
- [Карта системы Printum](https://wiki.printum.io/books/8-spravocnik/page/karta-sistemy-printum)