Skip to content

Log collection and analysis#

Logging guide#

Collecting logs is necessary for:

  • Providing VisionLabs technical support information for filing a ticket to find a problem;
  • Independent search for errors.

To receive complete information about an emergency situation when using Access, you must prepare and submit information to a VisionLabs representative about:

Settings file#

Settings file is a JSON file that contains information about the components used in Access.

The settings file becomes available for export after creating any component in Access.

1． After creating any of the 4 types of components, click on to the right of the user's avatar and click the "Export Settings" button (Figure 8).

Figure 8. Export settings
Figure 8. Export settings

This will download a JSON file called vl-access_settings.json.

2． Find the JSON on your local machine.

For Linux systems, the default is /home/\<username>/Downloads.

3． Rename the settings file depending on the main services and devices used, for example, bolid+gate+fast.json.

Container logs#

Container log files contain all information about the operation of Access from the moment of startup (docker compose up) to the creation of logs, provided that the containers are running.

1． Open the Access directory in the console.

For self-checking, make sure that this directory contains /db and docker-compose.yml (Figure 9).

Figure 9. Correct directory
Figure 9. Correct directory

2． Activate debug mode: in the .env file, set the value of the variable DEBUG=1.

3． Restart Access:

docker-compose down
docker-compose up

4． Run the commands to record worker and fastapi containers logs:

The name of the log file must contain the names of the main components.

docker-compose logs worker &> worker_<имена сервисов/устройств, bolid+gate+fast>.log
docker-compose logs fastapi &> fastapi_<имена сервисов/устройств, bolid+gate+fast>.log

5． Check for the generated .log files in the same directory.

Env file#

The .env file is located in the root folder of the distribution (in the same place as docker-compose.yml), but may not appear in the default UI.

1． Locate the .env file to provide to your VisionLabs representative.

Information about the working environment#

Check the hardware and software properties of the working machine with the minimum ones (see Requirements).

To check the requirements, run the view commands:

1． OS version of the local machine:

hostnamectl

2． Docker/docker-compose version:

docker --version
docker-compose --version

3． Information about hardware:

cat /proc/cpuinfo | grep "model name"

4． Amount of free RAM:

free -h

5． Amount of free physical memory:

df -h

Screenshots of UI#

Screenshots are only needed to find a problem with the UI:

  • the is_alive status of the component is displayed inadequately,
  • a component is displayed that should not exist (it was removed, but it “resurrected”),
  • an unreadable error appeared,
  • there are duplicates in the list in LUNA Clementine - the screenshot should include the dates of creation of the persons in the list,
  • in the events in LUNA Clementine something doesn’t match correctly, the event tag is incorrect,
  • other problems with the UI.

Tracking passages using trace_id#

A unique identifier, trace_id, is generated for each passage through the ACS. This identifier links all events related to one passage of a specific person: from the moment of detection to the provision of access through the turnstile.

Using trace_id allows you to quickly and accurately track the entire passage process, analyze delays at different stages and identify possible problems.

Using trace_id, you can track:

  • The time of receiving and processing events in the system;
  • Information about the recognition result: full name, card number, identifiers in the ACS and biometric system;
  • The time of execution of key operations: detection, recognition, sending data to the terminal and controller;
  • Other technical details related to processing the passage.

Tracking Luna Platform Event Passes#

1． Open the Luna CLEMENTINE / Luna Platform interface and go to the Latest Events section.

2． Find the oldest successful recognition event.

3． Go to the card of this event by clicking on the arrow in the upper right corner next to the photo (Figure 10).

Figure 10. Successful recognition event
Figure 10. Successful recognition event

4． Copy the eight-digit trace_id from the Tags field (Figure 11).

Figure 11. Location of trace_id in the event card
Figure 11. Location of trace_id in the event card

5． Make sure that debug mode (debug) is enabled in LUNA Access 2 and DEBUG-level messages are present in the worker log. 6． Find all logs related to this pass by running the command:

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

Example (Figure 12).

Figure 12. Example log
Figure 12. Example log

How to find trace_id by person's full name#

1． Make sure debug mode (debug) is enabled for LUNA Access 2 and there are DEBUG logs in the worker.

2． Find the required log by full name:

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

3． The found log will contain trace_id in the format trace <trace_id> (Figure 13).

Figure 13. Display trace_id in log
Figure 13. Display trace_id in log

4． Use this trace_id to search all related logs:

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

Search for an event in Luna Platform by trace_id#

The steps to display an event by trace_id in the UI are as follows (Figure 14).

Figure 14. Display trace_id in log
Figure 14. Display trace_id in log

1． In Luna CLEMENTINE / Luna Platform, go to Recent Events.

2． Click the filter icon on the right.

3． Enter the trace_id value in the Tags field.

4． Click the Filter button.

Logging during replication#

Replication logging in Access allows tracking the process of synchronizing user (face) data and controllers from the ACS to the LUNA PLATFORM 5 face recognition system.

Proper understanding of replication logs allows for quick identification and resolution of Access integration issues with ACS. Log analysis helps ensure reliable operation of the access control system and timely detection of potential data synchronization problems.

For additional information on tracking specific passage events and using Trace ID, refer to the section Tracking passages with trace_id.

Viewing replication logs#

To view replication logs, you need to perform the following steps:

1． Navigate to the product directory:

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

2． Output the logs of the FastAPI and Worker containers in real-time mode:

docker compose logs fastapi worker --follow

Each line contains information about a replication event with a timestamp, logging level (INFO, ERROR, etc.), and event description.

To stop viewing logs and return to the command line, press one of the following key combinations:

Ctrl + Z / Ctrl + C / Ctrl + D

Log filtering#

Logs can be filtered by various criteria by adding the grep command to the output command.

1． To search by user's full name:

docker compose logs fastapi worker --follow | grep "Full name"

Where: Full name - data in the "Information" field of the target person in CLEMENTINE

2． To search by user ID:

3． Enter the trace_id value in the Tags field.

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

Where: external_id - person identifier from ACS

3． To search by component ID:

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

Where: component_id - component identifier in Access.

Replication Process Structure#

The replication process consists of the following main stages:

1． Replication initiation - replication is launched automatically upon creation or reboot of the ACS component, or manually in the ACS software interface;

2． Controller replication - synchronization of ACS controller data (if applicable);

3． Face replication - synchronization of user data with their photos;

4． Error and exception handling - logging any problems that arise during the process;

5． Completion of replication - final logging of status.

Key replication logs

1． Start of controller replication.

When the ACS component starts replication, you will see logs of the following type:

Start controller replication

The log indicates that the system is starting to synchronize controllers from the ACS.

2． Start of face replication (Figure 15).

Figure 15. Example of face replication start in the log
Figure 15. Example of face replication start in the log

Log:

Start face replication

This log serves as a marker for the start of the main user synchronization process.

3． Creating a new face and saving it to storage (Figure 16).

Figure 16. Example of creating a new face record in the log
Figure 16. Example of creating a new face record in the log

When the system finds a new user in the ACS who has not yet been added to the LP5 face storage, a new record is created:

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]

Log parameters:

  • face_id - internal face ID in the biometric system
  • UUID - unique identifier of a record in the Access system
  • external_id - person identifier from ACS
  • list_id - the identifier of the list to which the face is added
  • storage_name - the name of the storage into which
  • additional_info - additional information about the person, for example the value of the additional field MDM_ID

The log informs that a new user record has been successfully created in the system and confirms that the user data has been successfully synchronized and saved in the local Access storage.

4． User data modification (Figure 17).

Figure 17. Example of editing user data in the log
Figure 17. Example of editing user data in the log

When user data is changed in the ACS (for example, a change in full name, photo, or other attributes), the system may perform a "delete and recreate" operation, and you will see the following logs:

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

Log parameters:

  • face_id - internal face ID in the biometric system
  • name - Full name of the person in the ACS
  • external_id - identifier of a person from the ACS
  • storage_name - the name of the storage into which
  • additional_info - additional information about the person, for example, the value of the additional field MDM_ID

This operation can occur not only during full replication, but also during system operation when the ACS administrator makes changes to user data.

5． Completion of replication (Figure 18).

Figure 18. Example of replication completion in the log
Figure 18. Example of replication completion in the log

When all users have been processed, the system logs the completion of replication:

End face replication

The log indicates the successful completion of the face synchronization process.

Recommendations for log analysis#

In case of replication issues:

1． Define the time range:

  • Find the logs "Start face replication" and "End face replication", this will give you the exact time frame of the problem

2． Filter logs by component:

  • Use search commands with the component ID to focus on a specific ACS (see Log filtering)

3． Find errors/warnings:

  • Look for lines containing "ERROR" or "WARNING"

4． Check a specific user:

  • Use search commands by full name or face ID from the ACS (see Log filtering)
  • Ensure that the user has been successfully replicated

5． Check the sequence of operations:

  • Ensure that the logs are in the correct order
  • Check for both successful save logs and potential errors

Solving typical problems#

When analyzing replication logs, you may encounter various errors and warnings. The table below serves as a quick reference for diagnosing issues and finding solutions. Each scenario corresponds to a specific type of error you might see in the logs and indicates possible causes and actions to fix it (Table 10).

Table 10. Solving typical problems

Scenario Key Logics Solution
Multiple faces on photo Multiple faces found in image Update photo in ACS
Missing photo Person has no photo Add photo to ACS
Face missing on photo The face hasn't been created due to wrong handler policies Update photo in ACS
Incorrect photo The face hasn't been created due to wrong handler policies Update the photo in the ACS
User is blocked Person is blocked Unblock in ACS
Long-term replication Large time range Check data volume and system load

Multiple Faces Error in Image#

When the LUNA biometric system detects multiple faces in a single photograph, an error is logged.

ERROR: LUNA API ERROR 11038 Multiple faces found in image

Possible reasons:

  • The photo contains several people;
  • The photo quality is low, and the biometric system incorrectly interprets parts of the image as separate faces.

Face does not meet requirements#

If the photo does not meet the facial recognition system requirements, a corresponding error is logged:

ERROR: LUNA API ERROR [code] [error_description]

OR

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

Typical validation errors include:

  • Face is too small;
  • The face is turned at a large angle;
  • Insufficient lighting;
  • Part of the face is covered;
  • Incorrect photo: flipped/blurry, etc.

Possible causes:

  • The photo does not meet the quality requirements of LUNA PLATFORM;
  • The photo does not meet the processor's policy requirements;
  • Incorrect photo processing before sending.

User Blocking#

If a user is blocked in the ACS, the system logs:

Person is blocked

Possible reasons:

  • The user is blocked in the ACS.