Диагностика и сбор логов

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

Что такое модель диагностики

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

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

Три шага модели

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

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

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

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

Связанные страницы

Шаг 1 — Локализация: система или инфраструктура?

Цель шага

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

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

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

1. Печать мимо системы

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

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

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

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

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

4. snmpwalk

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

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

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

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

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

Связанные страницы

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

Цель шага

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

Сценарий

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

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

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

Условия

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

Масштаб

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

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

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

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

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

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

Связанные страницы

Классификация инцидентов и мониторинг состояния системы

Назначение

Инструкция описывает порядок действий дежурных администраторов при возникновении инцидентов в системе Принтум и связанных компонентах. Основана на отказоустойчивой архитектуре системы и процессах мониторинга.

Классификация инцидентов

События уровня инфраструктуры

События уровня сервисов Принтум

Обнаружение инцидента

Обнаружение инцидента происходит в панели администратора балансировщика HAProxy (https://<адрес_сервера>:7000).

Строки компонентов окрашиваются в цветные статусы в зависимости от результата проверки healthcheck:

Цвет Значение
Ярко-зелёный Компонент работает стабильно, проверка healthcheck прошла успешно.
Светло-зелёный Компонент уходит в отказ, проверка healthcheck прошла успешно.
Жёлтый Компонент восстанавливается из отказа, проверка healthcheck прошла успешно.
Красный Компонент находится в отказе, либо проверка healthcheck прошла не успешно.

При ярко-зелёном статусе компонентов дополнительное внимание не требуется. При светло-зелёном, жёлтом и красном статусе рекомендуется проверить состояние конкретного компонента на соответствующем сервере ПринтМенеджера.

Время реакции и решения

Инфраструктурные события

События, связанные с инфраструктурой, относятся к критическим неисправностям, напрямую влияющим на сервис печати.

Признаки остановки сервиса печати ПринтМенеджера

Недоступность сервисов admin_8080, admin_8010, cups_1631 на панели администратора HAProxy:

В панели администратора HAProxy существует колонка, отвечающая за мониторинг времени последнего ответа от сервиса. Лимит ответа — 10 секунд. Если за это время сервис не дал ответ, статус изменит цвет.

Параметр Значение
Время реакции до 5 минут
Время решения до 30 минут
Эскалация сразу при обнаружении

Сервисные события

События, связанные с сервисом Принтум, относятся к уровню предупреждение и могут быть переквалифицированы в критичные в ходе диагностики. Данные события могут напрямую не отображаться в панели администратора HAProxy.

Параметр Значение
Время реакции до 15 минут
Время решения до 2 часов
Эскалация при ухудшении состояния

Проверка доступности сервисов

  1. Подключиться по SSH.
  2. Перейти в каталог нужного сервера:

ПринтМенеджер:

cd /opt/printmanager/

Мониторинг:

cd /opt/printum/

Балансировщик:

cd /opt/printum_balancer/
  1. Проверить контейнеры:
docker ps

Шаг 4 — Сбор и чтение логов

Уровни логов

Уровень Значение Что делать
ERROR Произошла ошибка, операция не выполнена Искать причину — читать сообщение и контекст вокруг
WARNING Подозрительное состояние, система продолжает работать Оценить как подозрение — может быть предвестником ошибки
INFO Штатное событие, контекст происходящего Использовать как фон для понимания последовательности
DEBUG Детальные данные для диагностики Включается вручную — даёт максимум деталей

Как читать запись лога

Каждая строка лога имеет структуру:

[container_name] [timestamp] [LEVEL] [message]

Пример:

printum_worker-default | 2024-01-15 10:23:41,012 ERROR [apps.inv.services.sync:302]: Some snmp data missing for printer 1

Ключевые сигналы

Режимы логирования

Два типа логов:

Два режима:

Команды сбора логов

Архивный сбор логов (рекомендуется при обращении в поддержку)

Если установлен Мониторинг и ПринтМенеджер, или только Мониторинг:

bash /opt/printum/logs.sh

Если установлен только ПринтМенеджер:

bash /opt/printmanager/logs.sh

Если файл .env зашифрован:

sudo -E ENV_VAULT_PASSWORD=<password> bash /opt/printum/logs.sh

Архив сохраняется в /opt/.../ALL_LOGS/logs-<YYYY-MM-DD-HH-MM-SS>.tar.gz

Просмотр логов в реальном времени

Все контейнеры сразу:

cd /opt/printum
sudo docker-compose logs -f --tail=1

Или для ПМ:

cd /opt/printmanager
sudo docker-compose logs -f --tail=1

Узнать названия контейнеров:

sudo docker-compose ps --services

Логи конкретного контейнера:

sudo docker-compose logs -f converter_server

Включение режима DEBUG

Перейдите в директорию продукта:

cd /opt/printum/
# или
cd /opt/printmanager/

Откройте файл конфигурации:

sudo nano .env

Измените параметры:

DEBUG=True
LOG_LEVEL=DEBUG

Перезапустите контейнеры:

sudo docker-compose down
sudo docker-compose up -d

После сбора логов обязательно верните параметры в исходное состояние (DEBUG=False, LOG_LEVEL=WARNING) и перезапустите контейнеры, чтобы избежать снижения производительности.

Сетевой агент

Текущий лог:

cat /opt/printum-agent/agent.log

Включение DEBUG для агента:

sudo nano /opt/printum-agent/config.env
# Установите: LOG_LEVEL=DEBUG
sudo systemctl restart printum-agent.service

Архивные логи агента:

/opt/printum-agent/agent-<datetime>.log.gz

Локальный агент Linux

sudo journalctl -u printum-jtm.service

Клиент ПМ для Linux

sudo journalctl -u printum-printmanager-client.service

Файлы логов клиента:

/var/log/printum/printmanager_client.log

Клиент ПМ для Windows и локальный агент Windows

Откройте Просмотр событий: Win+R → eventvwr. В левой панели: «Журналы Windows» → «Приложение». Источник для клиента ПМ: ПринтМенеджер Client. Источник для локального агента: ServicePrintum.

Связанные страницы

Паспорт инцидента

Назначение

Паспорт инцидента — шаблон для сбора всей необходимой информации до начала диагностики. Заполняется на Шаге 2 модели диагностики. Позволяет быстро передать инцидент коллеге или в поддержку без потери контекста.

Шаблон паспорта инцидента

Поле Что указать Пример
Сценарий Что не работает и в каком режиме Отложенная печать с клиентом ПринтМенеджер
Версия системы Версия Мониторинга и/или ПринтМенеджера Мониторинг 4.5.1, ПринтМенеджер 3.2.0
ОС сервера Операционная система, на которой развёрнута система Ubuntu 22.04
Конфигурация Тип развёртывания single / cluster / филиал
Контроллер домена Используется или нет, тип и версия Active Directory, Windows Server 2019
Масштаб — устройства Одно / группа / все. Если группа — что объединяет Два принтера Kyocera в офисе №3
Масштаб — пользователи Один / группа / все. Если группа — что объединяет Все пользователи из OU=Бухгалтерия
Масштаб — документы Один / группа / все. Если группа — что объединяет Только PDF-файлы из Adobe Reader
Воспроизводимость Всегда / иногда. Если иногда — при каких условиях Иногда, обычно после 17:00
Симптомы Что именно видит пользователь, сообщение об ошибке «Задание отправлено, но не печатается», ошибки нет
Уже проверено Какие шаги диагностики уже выполнены Печать мимо системы работает, другой пользователь — та же ошибка
Логи приложены Какие логи собраны и приложены logs-2024-01-15-10-30-00.tar.gz (архив /opt/printum/logs.sh)

Как использовать

  1. Заполните шаблон до начала диагностики — это займёт 5 минут и сэкономит часы
  2. Используйте как чек-лист: все поля заполнены → можно переходить к Шагу 3
  3. При передаче в поддержку — приложите заполненный паспорт и архив логов

Связанные страницы

Как диагностировать проблемы печати по этапам

Кратко

Проблемы печати нужно диагностировать не по общему описанию «не печатает», а по этапу, на котором остановилось задание. Правильная диагностика начинается с определения сценария и поиска точки отказа в цепочке обработки.

Первичные вопросы для локализации

Вопрос Зачем нужен
Клиент ПМ или бесклиентская печать? Разные точки входа и места диагностики
Прямая или отложенная печать? Разный путь после обработки задания
Какой пользователь и на какое устройство? Проверка прав, правил, лицензий, PIN/карты
Проблема у одного или у всех? Помогает понять: системная проблема или локальная
Проблема стабильно воспроизводится? Отличить системный сбой от случайного

Шаг 1. Определить, появилось ли задание в Принтум

Откройте раздел Управление → Задания.

Если задания нет

Искать проблему до попадания задания в ПринтМенеджер:

Сценарий Где искать
Клиент ПМ Локальная очередь, служба Клиента ПМ, подключение к ПринтМенеджеру
Бесклиентская печать Виртуальный принтер, универсальный драйвер, доступность CUPS ПринтМенеджера

Если задание есть

Искать проблему после попадания в ПринтМенеджер: правила, лицензии, CUPS, драйвер устройства, протокол, Встроенное приложение, физическое устройство.

Шаг 2. Для Клиента ПринтМенеджер — проверить рабочую станцию

Windows

  1. Откройте eventvwr.
  2. Перейдите в Журналы Windows → Приложение.
  3. Найдите события с источником ПринтМенеджер Client.
  4. Проверьте красные и жёлтые ошибки.

Дополнительно проверьте:

Linux

sudo systemctl status printum-printmanager-client.service
sudo journalctl -u printum-printmanager-client.service

Шаг 3. Для бесклиентской печати — проверить CUPS

Проверьте:

  1. виртуальный принтер на рабочей станции;
  2. универсальный PostScript-драйвер;
  3. адрес сервера Принтум в настройках принтера;
  4. поступление задания в CUPS ПринтМенеджера.

Шаг 4. Если задание появилось, но не печатается

Проверьте CUPS ПринтМенеджера:

  1. Откройте: https://<ip_сервера>:1631
  2. Перейдите на вкладку Задания.
  3. Найдите задание и проверьте его статус.

Если статус не «напечатано» — проблема может быть в сетевой доступности принтера, протоколе подключения, драйвере, настройках CUPS или самом устройстве.

Шаг 5. Для отложенной печати — дополнительные проверки

Шаг 6. Проверить правила печати

Проверьте персональные и групповые правила пользователя:

Важно для бесклиентской печати: настройка USE_PS_PRINTING влияет на конвертацию. Если есть правила по страницам, цветности или автоудалению — задание принудительно конвертируется в PDF.

Шаг 7. Проверить лицензии

Сценарий Лицензия
Мониторинг устройства M
Управление печатью PM
Встроенное приложение EMB
Внешняя авторизация EXT

Шаг 8. Проверить синхронизацию с Мониторингом

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

Типовые развилки диагностики

Наблюдение Вероятная зона проблемы
Задания нет в Принтум Рабочая станция, Клиент ПМ, виртуальный принтер, CUPS входящего задания
Задание есть, но не печатается CUPS, драйвер, протокол, устройство
Задание есть, пользователь не видит его на МФУ Авторизация, принадлежность задания, Встроенное приложение
Работает у одного, не работает у другого Пользователь, права, правила, карта, PIN
Работает на одном принтере, не работает на другом Устройство, лицензии, драйвер, протокол
Не работает ни у кого Сервер, сеть, ПринтМенеджер, CUPS, синхронизация

Что собрать перед эскалацией

Связанные страницы

Диагностика отказа Мониторинга

Назначение

Инструкция описывает диагностику отказа Мониторинга в Принтум. Мониторинг отвечает за: управление системой, SNMP-мониторинг, пользователей, синхронизацию, статистику и отчеты.

Признаки проблемы

Последовательность диагностики SSH → гипервизор → перезагрузка → backup

Шаг 1. Проверка SSH-доступа

Попробуйте подключиться к серверу по SSH. Если подключение успешно, проверьте состояние контейнеров:

sudo docker ps -a

Шаг 2. SSH недоступен — подключение через гипервизор

Подключитесь к виртуальной машине через гипервизор. Если вход выполнен:

Шаг 3. В терминал войти не удалось — перезагрузка ВМ

  1. Выполните перезапуск виртуальной машины.
  2. Дождитесь загрузки ОС.
  3. Проверьте контейнеры:
sudo docker ps -a

Шаг 4. ОС не загрузилась — восстановление из резервной копии

  1. Выполните попытки связи с ответственным инженером.
  2. При отсутствии результата восстановите ВМ из резервной копии.

Диагностика при успешном SSH-доступе

Проверка логов контейнеров

cd /opt/printum

docker-compose logs -f --tail=100

Проверить: ошибки PostgreSQL, ошибки DNS, SSL errors, traceback, connection refused.

Проверка ресурсов

htop

df -h

Проверка DNS

ping monitoring.local

cat /etc/resolv.conf

Перезапуск контейнеров Мониторинга

Если ошибок инфраструктуры нет:

cd /opt/printum
docker-compose down
docker-compose up -d

Если проблема сохраняется — перезагрузите ОС. Если проблема сохраняется после перезагрузки — обратитесь к Руководству администратора, раздел «Работа с логами».

Высокая загрузка CPU / RAM

  1. Подключиться по SSH.
  2. Определить процесс с высокой нагрузкой:
htop

Если нагружает вспомогательный сервис (например, антивирус):

systemctl stop <имя_сервиса>

Если остановка не выполнена, найти PID:

ps aux | grep <имя_сервиса>

Завершить принудительно:

kill -9 <PID>

Проверить, что статусы сервисов в HAProxy зелёные.

Типовые проблемы

Симптом Возможная причина
restart loop DNS/NFS
Нет UI Контейнер API не работает
Ошибки sync PostgreSQL
SSL errors Сертификаты
timeout Network issue

Что важно помнить

Диагностика проблем NFS и DNS

Назначение

DNS и NFS являются критическими зависимостями Принтум. Проблемы с ними могут вызывать: restart loop контейнеров, отказ ПринтМенеджера, ошибки синхронизации, недоступность очередей, проблемы Встроенного приложения.

Диагностика проблем DNS

Проверка resolv.conf

cat /etc/resolv.conf

Убедиться: DNS-серверы доступны, нет ошибочных записей. При необходимости скорректировать файл /etc/resolv.conf.

Проверка hostname resolution

Проверить: hostname резолвится, IP корректный.

Типовые признаки DNS-проблем

Симптом Возможная причина
restart loop hostname не резолвится
timeout DNS unavailable
sync errors неверный hostname
SSL errors mismatch hostname

Диагностика проблем NFS

Проверка доступности порта

telnet <hostname_nfs> 2049

Проверка stunnel:

telnet <hostname_nfs> 20490

Проверка mount

df -h

Проверить точку монтирования:

ls /var/lib/docker/volumes/printmanager_media/_data

Убедиться: volume mounted, нет stale mount, нет readonly mode.

Проверка volumes

ls /var/lib/docker/volumes/

Проверка сервисов на сервере NFS

Подключиться по SSH к серверу NFS.

Проверить место:

df -h

Проверить сервисы:

systemctl status nfs-server.service

systemctl status stunnel.service

Перезапуск сервисов NFS

systemctl restart nfs-server.service

systemctl restart stunnel.service

Проверить зелёный статус сервисов в HAProxy.

Что делать при restart loop контейнеров

Проверить: DNS, NFS и stunnel, точки монтирования, сетевую связность.

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

sudo docker-compose down
sudo docker-compose up -d

Если проблема на нескольких серверах ПринтМенеджера — остановку и запуск выполнить на всех нодах. Убедиться, что статусы в HAProxy зелёные. Если проблема сохраняется — восстановить сервер из резервной копии.

Нехватка места на диске

Очистка журналов ОС

sudo journalctl --vacuum-size 1M

sudo rm -rf /var/log/messages-*

df -h

Поиск больших логов Docker

sudo du -ch /var/lib/docker/containers/*/*-json.log

sudo truncate -s 0 <путь_к_файлу>

sudo df -h

Что важно помнить

Чек-лист перед обращением в техническую поддержку

Описание

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

Чек-лист корректности настройки системы мониторинга

Как определить версии компонентов

Мониторинг и ПринтМенеджер

В терминале сервера введите команды:

cat /opt/printum/.version

cat /opt/printmanager/.version

Клиент ПМ (Windows)

  1. Перейдите в папку с Клиентом ПМ: C:\Program Files\printum\printmanager_client\
  2. Откройте свойства файла as_service.exe.
  3. Перейдите во вкладку «Подробно». В графе «Версия файла» указана версия программы.

Сбор логов

Мониторинг и ПМ

Если установлен Мониторинг и ПринтМенеджер или только Мониторинг:

bash /opt/printum/logs.sh

Если установлен только ПринтМенеджер:

bash /opt/printmanager/logs.sh

Если Мониторинг или ПринтМенеджер установлен с включённым шифрованием .env:

sudo -E ENV_VAULT_PASSWORD=<password> bash /opt/printum/logs.sh

или

sudo -E ENV_VAULT_PASSWORD=<password> bash /opt/printmanager/logs.sh

После завершения выводится сообщение вида:

Логи успешно собраны и сохранены в /путь_к_каталогу/ALL_LOGS/logs-2023-12-06-17-14-44.tar.gz

Собранные логи сохраняются в папке ALL_LOGS в виде архивов. При повторном запуске команды создаются новые архивы — ранее сформированные файлы не перезаписываются.

Включение режима DEBUG

  1. Перейдите в директорию нужного продукта:
    • Мониторинг: cd /opt/printum/
    • ПринтМенеджер: cd /opt/printmanager/
  2. Откройте файл .env: sudo nano .env
  3. Измените параметры:
DEBUG=True
LOG_LEVEL=DEBUG
  1. Перезапустите контейнеры:
sudo docker-compose down
sudo docker-compose up -d
  1. После снятия логов верните параметры в исходное состояние (DEBUG=False, LOG_LEVEL=WARNING), чтобы избежать снижения производительности.
  2. Перезагрузите систему.
  3. Проанализируйте логи. Для этого распакуйте полученный архив и получите ряд лог-файлов:

image24.png

Что указать в обращении

Справочник контейнеров — когда и что смотреть в логах

Контейнеры Мониторинга

Команды выполняются из директории /opt/printum.

Контейнер Описание Когда анализировать (симптомы) Цель анализа Команда
printum_nginx HTTP-сервер и обратный прокси-сервер. Проксирует все HTTP-соединения от/до приложения, отдаёт статику. - Ошибки при загрузке Личного кабинета или он не загружается.
- Ошибки при загрузке панели администратора Мониторинга или она не загружается.
- Принтеры не добавляются в Мониторинг или не обновляют данные.
- Не происходит синхронизация между Мониторингом и ПринтМенеджером.		 - Выявить какие именно URL вызывают ошибки.
- Выявить коды ошибок.
- Выявить коды ошибок при запросах от сетевого агента.
- Выявить коды ошибок при запросах от ПринтМенеджера.		 cd /opt/printum docker-compose logs -f --tail=200 printum_nginx
printum_dashboard Логи Личного кабинета. - При загрузке Личного кабинета происходят ошибки.
- Пользователь не может открыть страницу ЛК в браузере.		 - Выявить какие именно URL вызывают ошибки.
- Выявить коды ошибок.
- Выявить какой IP-адрес пытается получить данные.		 cd /opt/printum docker-compose logs -f --tail=200 printum_dashboard
printum_worker-default
printum_worker-high
printum_worker-low		 Воркеры мониторинга. Три очереди Celery для выполнения фоновых задач: отправка писем, обработка данных от принтеров. - Проблемы с отправкой писем.
- Проблемы с обработкой данных от принтеров.
- Не обновляется статус принтера.
- Не обновляется история замен.
- Проблемы с синхронизацией Мониторинга и ПринтМенеджера.
- Не обновляется информация по принтерам.
- Не загружаются справочники.
- Не приходят уведомления на почту.
- Данные в Мониторинге появляются с большой задержкой.
- Фоновые операции выполняются нестабильно или не завершаются.		 - Выявить в какое время была запущена очередная задача.
- Выявить в какое время была завершена очередная задача.
- Выявить время выполнения задачи.
- Выявить наличие ошибок по периодическим задачам.		 cd /opt/printum docker-compose logs -f --tail=200 printum_worker-default docker-compose logs -f --tail=200 printum_worker-high docker-compose logs -f --tail=200 printum_worker-low
printum_scheduler Планировщик задач для Celery. Выполняет задачи мониторинга по расписанию. - Не выполняются задачи по расписанию (например, не запускается синхронизация с доменом).
- Не приходят уведомления на почту.
- Не обновляются данные, которые должны обновляться по расписанию.		 - Выявить, запускается ли задача по расписанию.
- Выявить ошибки планировщика при постановке задач в очередь.		 cd /opt/printum docker-compose logs -f --tail=200 printum_scheduler
printum_backend API мониторинга. Все не фоновые задачи. - Не работает отправка писем.
- Проблемы с созданием локаций.
- Проверка обмена данными с Локальным агентом.
- Ошибки при работе Личного кабинета (действия не выполняются).		 - Выявить ошибки обработки API-запросов.
- Определить причины возврата кодов 4xx/5xx.
- Выявить некорректные входные данные запросов.
- Определить, на каком этапе происходит ошибка (валидация / логика / БД).		 cd /opt/printum docker-compose logs -f --tail=200 printum_backend
printum_clickhouse Столбцовая система управления базами данных. Обычно смотреть не нужно. - Проверка запуска сервиса.
- Наличие ошибок запуска БД.		 - Проверить наличие ошибок запуска БД. cd /opt/printum docker-compose logs -f --tail=200 printum_clickhouse
printum_redis Брокер сообщений мониторинга. - Проверка запуска сервиса.
- Наличие ошибок запуска сервиса.		 - Проверить наличие ошибок запуска сервиса. cd /opt/printum docker-compose logs -f --tail=200 printum_redis
printum_postgres База данных мониторинга. - Проверка запуска сервиса.
- Наличие ошибок запуска БД.		 - Проверить наличие ошибок запуска БД. cd /opt/printum docker-compose logs -f --tail=200 printum_postgres

Контейнеры ПринтМенеджера

Команды выполняются из директории /opt/printmanager.

Контейнер Описание Когда анализировать (симптомы) Цель анализа Команда
printmanager_web Админка ПМ, nginx. Проксирует все HTTP-соединения для ПринтМенеджера. - Не происходит синхронизация между Мониторингом и ПринтМенеджером. - Выявить какие именно URL вызывают ошибки.
- Выявить коды ошибок.		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager_web
printmanager-celery Все фоновые задачи ПМ. Обрабатывает интеграцию с Мониторингом, задания печати, встроенные приложения. - Не импортируются принтеры из Мониторинга.
- Не отправляется статистика печати в Мониторинг.
- Задания печатаются с большой задержкой или не печатаются вовсе.
- Печатается только часть задания.
- Ошибки установки или деинсталляции встроенного приложения.		 - Выявить ошибки при интеграции с Мониторингом.
- Выявить ошибки при печати заданий.
- Выявить ошибки при установке встроенного приложения.
- Выявить ошибки при соединении с CUPS.		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-celery
printmanager-celery-print-queue Очередь бесклиентской печати. Проверяет CUPS на наличие новых заданий и отправляет их на обработку и печать. - Задания не попадают в очередь печати или попадают с большой задержкой. - Выявить ошибки соединения с CUPS.
- Выявить ошибки при обработке заданий из CUPS.
- Выявить ошибки соединения с принтерами.		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-celery-print-queue
printmanager-scheduler Планировщик задач для Celery ПМ. Механизм отправки задач по расписанию. - Задания перестали приходить в очередь печати.
- Задания гостевой печати перестали приходить в очередь.
- Задания печати через почту перестали приходить в очередь.
- У заданий образы документов не появляются.		 - Выявить, запускается ли задача по расписанию.
- Выявить ошибки планировщика при постановке задач в очередь.		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-scheduler
printmanager-app Основной контейнер ПМ. Django-приложение административной панели. Обрабатывает все HTTP-обращения, принтеры, клиентов. - Проблемы с печатью / копированием / сканированием.
- Проблемы с авторизацией.
- Задания не приходят на устройство, хотя в ПринтМенеджере есть.
- Проверка обмена данными с Клиентом ПМ.		 - Выявить ошибки обработки API-запросов.
- Определить причины возврата кодов 4xx/5xx.
- Выявить некорректные входные данные запросов.
- Определить, на каком этапе происходит ошибка (валидация / логика / БД).		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-app
printmanager-converter-server TCP-конвертер-сервер. Принимает запросы по TCP и передаёт их в app по HTTP. - Проблемы с авторизацией по TCP. - Выявить, приходит ли сообщение от конвертера.
- Выявить какой номер карты приходит от конвертера.		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-converter-server
printmanager-ftpd Временное хранилище для обмена файлами сканирования/копирования с принтерами. - Проблема с заданием копирования (сканирование выполнялось, но документ не распечатался).
- Задание сканирования не появилось в ПМ или нет его образа.		 - Выявить ошибки при выполнении процесса обработки образа документа заданий сканирования и копирования. cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-ftpd
printmanager-db База данных ПринтМенеджера. - Проверка запуска сервиса.
- Наличие ошибок запуска БД.		 - Проверить наличие ошибок запуска БД. cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-db
printmanager-cups Контейнер сервера печати. Обрабатывает всю отложенную печать (клиентская, бесклиентская, через почту). - Задания не распечатываются.
- Недоступна панель CUPS по порту 1631.		 - Выявить ошибки работы сервиса.
- Выявить ошибки принтеров в CUPS.

Примечание: Unable to encrypt connection: A TLS fatal alert has been received. — не является ошибкой системы.		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-cups
printmanager-redis Redis ПринтМенеджера. Брокер сообщений. - Сингл: проверка запуска сервиса.
- Отказоустойчивая конфигурация: ноды ПринтМенеджера недоступны.		 - Сингл: наличие ошибок запуска сервиса.
- Отказоустойчивая конфигурация: ошибки при переключении с master на slave.		 cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-redis
printmanager-redis-sentinel Redis Sentinel ПМ. Существует только в схеме с балансировкой нагрузки. - Ноды ПринтМенеджера недоступны. - Выявить наличие ошибок при переключении с master на slave. cd /opt/printmanager docker-compose logs -f --tail=200 printmanager-redis-sentinel

Агенты и Клиент ПМ

Агенты и клиенты ПМ не являются Docker-контейнерами. Логи доступны через системный журнал или файлы логов.

Компонент Описание Когда анализировать (симптомы) Цель анализа Команда / расположение логов
Сетевой агент Сканирование сети и сбор данных с сетевых устройств. - Устройство не появляется в разделе «Инвентаризация — Устройства». - Выявить ошибки запуска сервиса.
- Выявить ошибки опроса устройства.
- Выявить ошибки сканирования сети.		 cat /opt/printum-agent/agent.log
Локальный агент Windows Мониторинг заданий печати на ОС Windows. - Устройство не появляется в Личном кабинете.
- Не передаётся статистика по устройству.		 - Выявить ошибки запуска сервиса.
- Выявить ошибки передачи данных.		 eventvwr → Журналы Windows → Приложение → источник ServicePrintum
Локальный агент Linux Мониторинг заданий печати на ОС Linux. - Устройство не появляется в Личном кабинете.
- Не передаётся статистика по устройству.		 - Выявить ошибки запуска сервиса.
- Выявить ошибки передачи данных.		 sudo journalctl -u printum-jtm.service
Клиент ПМ Windows Отправка заданий на печать на ОС Windows. - Задание не появляется в очереди или не печатается на принтере для прямой печати.
- Принтеры не появляются на АРМ.		 - Выявить ошибки запуска сервиса.
- Выявить ошибки передачи данных.		 eventvwr → Журналы Windows → Приложение → источник Print Manager Client
Клиент ПМ Linux Отправка заданий на печать на ОС Linux. - Задание не появляется в очереди или не печатается на принтере для прямой печати.
- Принтеры не появляются на АРМ.		 - Выявить ошибки запуска сервиса.
- Выявить ошибки передачи данных.		 sudo journalctl -u printum-printmanager-client.service

Ошибка «Provided license key instead of activation key»

Симптомы

При попытке активировать лицензию в Личный кабинет → Настройки → Общие → Организации система или в Личный кабинет → Первый запуск → Активация лицензии показывает ошибку:

Provided license key instead of activation key

Или в письме от Технической поддержки приходит лицензионнвй ключ, но при вводе система его не принимает.

Причина

Перепутаны два разных значения:

Ошибка возникает когда в поле лицензионного ключа вводится токен активации (или наоборот), либо когда вводится токен активации из другой системы или организации.

Решение

Шаг 1. В Личный кабинет → Настройки → Общие → Организации нажать «Токен активации» и скопировать актуальный токен именно этой системы.

Шаг 2. Отправить этот токен в Техническую поддержку (support@printum.io) с названием организации.

Шаг 3. Полученный от Технической поддержки ключ ввести в поле «Указать лицензионный ключ» → «Сохранить».

Как проверить результат

В списке лицензий карточки организации отображаются типы лицензий, количество и срок действия.

Когда эскалировать

Связанные страницы

Счётчики не обновляются после обновления Мониторинга

Симптомы

Причина

Две наиболее частые:

  1. Агент не перезапустился корректно после обновления — продолжает работать старая версия или агент завис.
  2. Ошибка чтения данных в ClickHouse — при крупном обновлении (например, 4.1 → 4.3) формат хранения данных изменился, агент получает ошибку при записи или чтении.

Диагностика

Проверить статус контейнера агента:

sudo systemctl status printum-agent.service

Проверить логи агента в интерактивном режиме:

cd /opt/printum-agent/
tail agent.log -f

Признак проблемы 1 (агент завис):

# Ошибки по запуску периодических задач на опрос и сканирование:
level=error msg="get /agent/poll_tasks failed
level=error msg="get /agent/scan_tasks failed

Проверить работу периодической задачи по обработке регистров принтеров (periodic_update_register_of_printers_in_snmp):

cd /opt/printum/
sudo docker-compose logs -f --tail=5 worker-low

Признак проблемы 2 (ClickHouse):

[<date_time>: ERROR/ForkPoolWorker-26] Task apps.printer.tasks.periodic_update_register_of_printers_in_snmp[<UUID>] raised unexpected: ServerException('DB::Exception: Unknown codec family code: 0...

Решение

Агент не перезапустился

sudo systemctl restart printum-agent.service

Подождать 2–3 минуты, проверить счётчики в ЛК.

Ошибка ClickHouse

Не устраняется самостоятельно. Требует вмешательства на уровне БД.

Передать в ТП:

Как проверить результат

Когда эскалировать

Связанные страницы

Скан не приходит на email

Симптомы

Диагностика

Шаг 1. Проверить SMTP-настройки ПринтМенеджера

Примечание Типичные ошибки в логах при неверных SMTP-настройках:

Email message to <адрес> was not sent: authentication error

Шаг 2. Проверить email пользователя

Шаг 3. Проверить задание в ПринтМенеджере

Панель администратора ПринтМенеджера → Управление печатью → Задания печати: найти задание сканирования. Если задания нет — файл не дошёл с МФУ до ПринтМенеджера (проблема в приложении или сети, а не в email).

Шаг 4. Проверить логи

cd /opt/printmanager
sudo docker-compose logs -f --tail=100

Шаг 5. Проверить логи FTP-контейнера

cd /opt/printmanager
sudo docker-compose logs printmanager-ftpd --tail=100

Контейнер printmanager-ftpd отвечает за временное хранилище файлов сканирования. Ошибки здесь означают, что файл не был сохранён перед отправкой на email.

Шаг 6. Проверить правила пользователя

Личный кабинет → Управление → Пользователи → карточка пользователя → Принтеры и правила. Правило «Запретить сканирование в почту» блокирует отправку.

Шаг 7. Проверить параметр сканирования на email другого сотрудника

Если сканирование выполняется на email другого сотрудника (Xerox, Sharp, Konica Minolta) — проверить, включён ли параметр SCAN_TO_ANOTHER_MAIL в https://<ip_pm>:8080/config/constance/config/ → раздел «Настройки сканирования».

Шаг 8. Проверка ограничения на размер вложений на SMTP-сервере

Проверьте отправку письма со сканом одного листа в чёрно-белом режиме и с низким DPI. Если такое письмо доставляется, а письмо с более «тяжёлым» вложением — нет, то, вероятно, на SMTP-сервере установлено ограничение на размер файлов или писем.

Решение

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

Как проверить результат

Выполнить сканирование на email тестового пользователя с корректно заполненным email. Письмо приходит в течение 1-2 минут.

Когда эскалировать

Приложить: логи printmanager-app, настройки SMTP (без пароля), версии Мониторинга и ПринтМенеджера, вывод команды bash /opt/printmanager/logs.sh и версию cat /opt/printmanager/.version.

Связанные страницы

Скан не сохраняется в сетевую папку

Симптомы

Диагностика

Шаг 1. Проверить SMB-настройки в ПринтМенеджере

Панель администратора ПринтМенеджера → https://<ip_pm>:8080/config/constance/config/ → раздел «Настройки сканирования»:

Если hostname не резолвится — попробовать заменить на IP-адрес.

Шаг 2. Проверить путь к папке пользователя

Панель администратора Мониторинга → Настройка → Пользователи → карточка пользователя → поле «Путь к папке».

Если путь не заполнен — то система не будет понимать куда отправить файл после сканирования.

Путь указывается в формате \\ИмяСервера\Папка или с шаблонными переменными. Поддерживаемые переменные:

Пример: \\ИмяСервера\$DEPARTMENT$\$USERNAME$.

Шаг 3. Проверить права доступа

Пользователь SMB_USERNAME должен иметь права на запись в папку пользователя. Проверить: попробовать записать файл в папку от имени SMB_USERNAME с другого компьютера.

Шаг 4. Проверить задание в ПринтМенеджере

Панель администратора ПринтМенеджера → Управление печатью → Задания печати: задание сканирования должно появиться. Если его нет — файл не дошёл с МФУ до ПринтМенеджера.

Шаг 5. Проверить логи

Заупстить логи в интерактивном режиме

cd /opt/printmanager
sudo docker-compose logs -f --tail=100"

Выполнить задание сканирования и проверить логи.

Шаг 6. Проверить правила

Личный кабинет → Управление → Пользователи → карточка пользователя → Принтеры и правила. Правило «Запретить сканирование в папку» блокирует операцию.

Частые ситуации

Hostname SMB-сервера не резолвится с сервера ПринтМенеджера

Заменить SMB_HOSTNAME на IP-адрес в настройках ПринтМенеджера.

Ошибка прав доступа

В логах: Permission denied или Access denied.

Проверить: пользователь SMB_USERNAME должен иметь права на запись именно в ту папку, которая указана в карточке пользователя. Права на родительскую папку без прав на дочернюю — не работает.

Шифрование SMB несовместимо

Если включён SCAN_SMB_ENCRYPT, SMB-сервер должен поддерживать SMBv3 или выше. На старых серверах (Windows Server 2008, Samba старых версий) шифрование может не работать. Отключить SCAN_SMB_ENCRYPT для проверки.

Сканирование на папку другого сотрудника (Konica Minolta)

Проверить, включён ли параметр SCAN_TO_ANOTHER_SMB в Настройках сканирования ПринтМенеджера (https://<ip_pm>:8080/config/constance/config/ → раздел «Настройки сканирования»).

Как проверить результат

Выполнить сканирование в папку тестового пользователя. Файл появляется в указанной сетевой папке в течение 1-2 минут.

Когда эскалировать

Приложить: логи системы Printum (bash /opt/printmanager/logs.sh), настройки SMB (без пароля), путь к папке пользователя, версии Мониторинга и ПринтМенеджера (cat /opt/print*/.version).

Связанные страницы

Белый экран или приложение не открывается на МФУ

Симптомы

Причины и решения

МФУ не может подключиться к серверу ПринтМенеджер

Белый экран — наиболее частый признак того, что приложение не получает ответ от ПринтМенеджера.

Проверить сетевой доступ МФУ к ПринтМенеджеру:

Несовместимая версия прошивки

На некоторых моделях (особенно Pantum) после обновления прошивки приложение перестаёт открываться. Или, наоборот, устаревшая прошивка несовместима с текущей версией приложения.

Решение: запросить у ТП информацию о поддерживаемой и совместимой версии прошивки для конкретной модели. Пригласить сервисного инженера для прошивки.

Приложение не переустановлено после смены прошивки

После обновления прошивки МФУ встроенное приложение необходимо переустановить.

Решение:

  1. Личный кабинет → Управление → Устройства → МФУ → «Удалить приложение».
  2. Перезагрузить МФУ.
  3. Установить приложение заново.

Конфликт со сторонним ПО на МФУ

Белый экран при авторизации по PIN-коду может быть вызван сторонними приложениями, установленными на МФУ (например, Device Software Manager).

Решение:

  1. Открыть веб-интерфейс МФУ → раздел установленных приложений.
  2. Удалить сторонние приложения, не связанные с Printum.
  3. Перезагрузить МФУ.

Как проверить результат

После перезагрузки МФУ открыть приложение — экран авторизации отображается корректно. Авторизация по PIN или карте выполняется успешно.

Когда эскалировать

Приложить к заявке: вендор, модель, версия прошивки, версии М и ПринтМенеджер, версия приложения, логи системы Printum.

Связанные страницы