Перейти к содержанию

Сбор и анализ логов#

Инструкция по сбору логов#

Сбор логов необходим для:

  • Предоставления информации технической поддержки VisionLabs для составления тикета на поиск проблемы;
  • Самостоятельного поиска ошибок.

Для получения полной информации о нештатной ситуации при работе Access необходимо подготовить и передать информацию представителю VisionLabs о:

Файл настроек#

Файл настроек – JSON файл, который содержит информацию об используемых компонентах в Access.

Файл настроек становится доступен для экспорта после создания в Access компонента.

1． После создания любого из 4-х типов компонентов необходимо нажать на справа от аватара пользователя и нажать кнопку "Экспортировать настройки" (Рисунок 8).

Рисунок 8. Экспорт настроек
Рисунок 8. Экспорт настроек

При этом произойдет загрузка JSON файла с именем vl-access_setting.json.

2． Найдите JSON на локальной машине.

Для Linux-систем по умолчанию /home/<username>/Downloads.

3． Переименуйте файл настроек в зависимости от основных используемых сервисов и устройств, например: bolid+gate+fast.json.

Логи контейнеров#

Файлы логов контейнеров содержат всю информацию о работе Access от момента запуска (docker compose up) до создания логов, при условии активности контейнеров.

1． Откройте в консоли директорию Access.

Для самопроверки удостоверьтесь, что в этой директории есть /db и docker-compose.yml (Рисунок 9).

Рисунок 9. Корректная директория
Рисунок 9. Корректная директория

2． Выполните команды для записи логов контейнеров worker и fastapi:

В названии лог файла должны быть указаны названия основных компонентов.

docker-compose logs worker &> worker_<components_names>.log
docker-compose logs fastapi &> fastapi_<components_names>.log

3． Проверьте наличие созданных файлов .log в той же директории.

Файл .env#

Файл .env находится в корневой папке дистрибутива (там же где docker-compose.yml), но может не отображаться в UI по умолчанию.

Найдите файл .env для передачи представителю VisionLabs.

Информация о рабочем окружении#

Сверьте аппаратные и программные свойства рабочей машины с минимальными (см. Требования).

Для проверки требований выполните команды просмотра:

1． Версия ОС локальной машины:

hostnamectl

2． Версия docker/docker-compose:

docker --version
docker-compose --version

3． Информация о аппаратных характеристиках:

cat /proc/cpuinfo | grep "model name"

4． Объем свободной оперативной памяти:

free -h

5． Объем свободного дискового пространства:

df -h

Скриншоты UI#

Скриншоты необходимы только для поиска проблемы с UI:

  • неадекватно отображается статус is_alive компонента,
  • отображается компонент, которого не должно быть (удалили, но он "вернулся"),
  • появилась нечитаемая ошибка,
  • в списке в LUNA Clementine дубли - на скриншот должны попасть даты создания лиц в списке,
  • есть расхождения с событиями в LUNA Clementine, неверный тег события,
  • прочее проблемы с UI.

Отслеживание проходов с помощью trace_id#

В Access для каждого прохода через СКУД формируется уникальный идентификатор — trace_id. Данный идентификатор связывает все события, относящиеся к одному проходу конкретного лица: от момента детекции до предоставления доступа через турникет.

Использование trace_id позволяет быстро и точно отслеживать весь процесс прохода, анализировать задержки на разных этапах и выявлять возможные проблемы.

С помощью trace_id можно отследить:

  • Время получения и обработки событий в системе;
  • Информацию о результате распознавания: ФИО, номер карты, идентификаторы в СКУД и биометрической системе;
  • Время выполнения ключевых операций: детекция, распознавание, отправка данных на терминал и контроллер;
  • Другие технические детали, связанные с обработкой прохода.

Отслеживание проходов через события Luna Platform#

1． Откройте интерфейс Luna CLEMENTINE / Luna Platform и перейдите в раздел Последние события.

2． Найдите самое раннее успешное событие распознавания.

3． Перейдите в карточку этого события, нажав на стрелку в правом верхнем углу возле фотографии (Рисунок 10).

Рисунок 10. Событие успешного распознавания
Рисунок 10. Событие успешного распознавания

4． Скопируйте восьмизначный trace_id из поля Теги (Рисунок 11).

Рисунок 11. Расположение trace_id в карточке события
Рисунок 11. Расположение trace_id в карточке события

5． Убедитесь, что в Access включён режим отладки (debug), и в логе worker присутствуют сообщения уровня DEBUG.

6． Найдите все логи, относящиеся к этому проходу, выполнив команду:

docker-compose logs fastapi worker | grep "<trace_id>"

Пример (Рисунок 12).

Рисунок 12. Пример лога
Рисунок 12. Пример лога

Как найти trace_id по ФИО персоны#

1． Убедитесь, что включён режим отладки (debug) для Access и в worker есть DEBUG-логи.

2． Найдите нужный лог по ФИО:

docker-compose logs worker | grep -i "<name>"

3． В найденном логе будет указан trace_id в формате trace <trace_id> (Рисунок 13).

Рисунок 13. Отображение trace_id в логе
Рисунок 13. Отображение trace_id в логе

4． Используйте данный trace_id для поиска всех связанных логов:

   docker-compose logs fastapi worker | grep "<trace_id>"

Поиск события в Luna Platform по trace_id#

Порядок действий для отображения события по trace_id в UI (Рисунок 14).

Рисунок 14. Отображение trace_id в логе
Рисунок 14. Отображение trace_id в логе

1． В Luna CLEMENTINE / Luna Platform перейдите в раздел Последние события.

2． Нажмите на значок фильтра справа.

3． Введите значение trace_id в поле Теги.

4． Нажмите кнопку Отфильтровать.

Логирование при репликации#

Логирование репликации в Access позволяет отслеживать процесс синхронизации данных пользователей (лиц) и контроллеров из СКУД в систему распознавания лиц LUNA PLATFORM 5.

Правильное понимание логов репликации позволяет быстро идентифицировать и решать проблемы интеграции Access с СКУД. Анализ логов помогает обеспечить надежную работу системы контроля доступа и своевременно выявлять потенциальные проблемы с синхронизацией данных.

Для дополнительной информации о отслеживании конкретных событий прохода и использовании Trace ID обратитесь к разделу Отслеживание проходов с помощью trace_id.

Просмотр логов репликации#

Для просмотра логов репликации необходимо выполнить следующие действия:

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

cd /var/lib/vl-access-2/

2． Выведете логи контейнеров FastAPI и Worker в режиме реального времени: 

docker compose logs fastapi worker --follow

Каждая строка содержит информацию о событии репликации с временной меткой, уровнем логирования (INFO, ERROR и т.д.) и описанием события.

Для остановки просмотра логов и возврата к командной строке нажмите одну из следующих сочетаний клавиш:

Ctrl + Z / Ctrl + C / Ctrl + D

Фильтрация логов#

Логи можно фильтровать по различным критериям, добавив команду grep в команду вывода.

1． Для поиска по ФИО пользователя:

docker compose logs fastapi worker --follow | grep "ФИО"

Где: ФИО - данные в поле "Информация" целевого лица в CLEMENTINE

2． Для поиска по ID пользователя:

docker compose logs fastapi worker --follow | grep "external_id"

Где: external_id - идентификатор лица из СКУД

3． Для поиска по ID компонента:

docker compose logs fastapi worker --follow | grep "component_id"

Где: component_id - идентификатор компонента в Access.

Структура процесса репликации#

Процесс репликации состоит из следующих основных этапов:

1． Инициирование репликации - репликация запускается автоматически при создании или перезагрузке компонента СКУД, либо вручную в интерфейсе ПО СКУД;

2． Репликация контроллеров - синхронизация данных контроллеров СКУД (если применимо);

3． Репликация лиц - синхронизация данных пользователей с их фотографиями;

4． Обработка ошибок и исключений - логирование любых проблем, возникших в процессе;

5． Завершение репликации - финальное логирование статуса.

Ключевые логи репликации

1． Начало репликации контроллеров.

Когда компонент СКУД начинает репликацию, вы увидите логи следующего вида:

Start controller replication

Лог указывает на то, что система начинает синхронизировать контроллеры из СКУД.

2． Начало репликации лиц (Рисунок 15).

Рисунок 15. Пример начала репликации лиц в логе
Рисунок 15. Пример начала репликации лиц в логе

Лог:

Start face replication

Этот лог служит маркером начала основного процесса синхронизации пользователей.

3． Создание нового лица и сохранение в хранилище (Рисунок 16).

Рисунок 16. Пример создания записи о новом лице в логе
Рисунок 16. Пример создания записи о новом лице в логе

Когда система находит нового пользователя в СКУД, который еще не добавлен в хранилище лиц LP5, создается новая запись:

Create new face: [face_id], ID [UUID], external ID [external_id] to list [list_id]
Saved person in storage: [storage_name]: [external_id] | [additional_info]

Параметры лога:

  • face_id - внутренний ID лица в биометрической системе
  • UUID - уникальный идентификатор записи в системе Access
  • external_id - идентификатор лица из СКУД
  • list_id - идентификатор списка, в который добавляется лицо
  • storage_name - имя хранилища, в которое
  • additional_info - дополнительная информация о лице, например значение доп. поля MDM_ID

Лог информирует о том, что новая запись о пользователе успешно создана в системе и подтверждает, что данные пользователя успешно синхронизированы и сохранены в локальном хранилище Access.

4． Изменение данных пользователя (Рисунок 17).

Рисунок 17. Пример изменения данных пользователя в логе
Рисунок 17. Пример изменения данных пользователя в логе

Когда данные пользователя изменяются в СКУД (например, изменение ФИО, фотографии или других атрибутов), система может выполнить операцию "удаление и пересоздание", вы увидите следующие логи:

Successfully updated face [face_id] name: [name] in list Luna
Saved person in storage: [storage_name]: [external_id] | [additional_info]

Параметры лога:

  • face_id - внутренний ID лица в биометрической системе
  • name - ФИО персоны в СКУД
  • external_id - идентификатор лица из СКУД
  • storage_name - имя хранилища, в которое
  • additional_info - дополнительная информация о лице, например значение доп. поля MDM_ID

Эта операция может происходить не только во время полной репликации, но также и во время работы системы, когда администратор СКУД вносит изменения в данные пользователя.

5． Завершение репликации (Рисунок 18).

Рисунок 18. Пример завершения репликации в логе
Рисунок 18. Пример завершения репликации в логе

Когда все пользователи обработаны, система логирует завершение репликации:

End face replication

Лог обозначает успешное завершение процесса синхронизации лиц.

Рекомендации по анализу логов#

При возникновении проблем с репликацией:

1． Определите временной диапазон:

  • Найдите логи "Start face replication" и "End face replication", это даст вам точные временные рамки проблемы

2． Отфильтруйте логи по компоненту:

  • Используйте команды поиска с ID компонента для фокусировки на конкретном СКУД (см. Фильтрация логов)

3． Найдите ошибки/предупреждения:

  • Ищите строки, содержащие "ERROR" или "WARNING"

4． Проверьте конкретного пользователя:

  • Используйте команды поиска по ФИО или ID лица из СКУД (см. Фильтрация логов)
  • Убедитесь, что пользователь реплицировался успешно

5． Проверьте последовательность операций:

  • Убедитесь, что логи идут в правильном порядке
  • Проверьте наличие как логов успешного сохранения, так и потенциальных ошибок

Решение типовых проблем#

При анализе логов репликации вы можете столкнуться с различными ошибками и предупреждениями. Таблица ниже служит быстрым справочником для диагностики проблем и поиска решений. Каждый сценарий соответствует конкретному типу ошибки, которую вы можете увидеть в логах, и указывает на возможные причины и действия для исправления (Таблица 10).

Таблица 10. Решение типовых проблем

Сценарий Ключевые логи Решение
Множественные лица на фото Multiple faces found in image Обновить фотографию в СКУД
Отсутствует фотография Person has no photo Добавить фото в СКУД
Отсутствует лицо на фотографии The face hasn't been created due to wrong handler policies Обновить фотографию в СКУД
Некорректное фото The face hasn't been created due to wrong handler policies Обновить фотографию в СКУД
Пользователь заблокирован Person is blocked Разблокировать в СКУД
Длительная репликация Большой временной диапазон Проверить объем данных и нагрузку на систему

Ошибка множественных лиц в изображении#

Когда биометрическая система LUNA обнаруживает несколько лиц на одной фотографии, логируется ошибка:

ERROR: LUNA API ERROR 11038 Multiple faces found in image

Возможные причины:

  • Фотография содержит несколько человек;
  • Качество фотографии низкое, и биометрическая система неправильно интерпретирует части изображения как отдельные лица.

Лицо не соответствует требованиям#

Если фотография не соответствует требованиям системы распознавания, логируется соответствующая ошибка:

ERROR: LUNA API ERROR [code] [error_description]

или

LUNA CLIENT ERROR The face hasn't been created due to wrong handler policies. <details>

Типичные ошибки валидации включают:

  • Лицо слишком маленькое;
  • Лицо повернуто под большим углом;
  • Освещение недостаточное;
  • Часть лица закрыта;
  • Некорректное фото: перевернуто/размыто и проч.

Возможные причины:

  • Фотография не соответствует требованиям качества LUNA PLATFORM;
  • Фотография не соответствует требованиям политик обработчика;
  • Некорректная обработка фотографии перед отправкой.

Блокировка пользователя#

Если пользователь заблокирован в СКУД система логирует:

Person is blocked

Возможные причины:

  • Пользователь заблокирован в СКУД.