When an analytics plugin generates metadata, such as events and objects, it passes through the internal pipeline of the Media Server. The Media Server then dispatches this metadata to destinations like the Video Archive or live video streams.

The Desktop Client receives this metadata inside the video stream and passes it to its video rendering engine to draw object bounding boxes over video frames.

Why use Analytics Logs?

Sometimes object bounding boxes do not appear on live camera views in the Desktop Client. This usually happens when:

• Delayed processing: There is a significant delay between when the frame was analyzed and the timestamp produced for the object. By the time the Desktop Client receives the metadata, the corresponding video frame has already passed.

• Incorrect timestamps: The plugin generates timestamps using current system time rather than the timestamp of the analyzed frame.

Analytics Logs capture metadata at various stages of the Media Server and the Desktop Client pipelines, saving the data to text files in a readable format. You can inspect these files directly or use the built-in desktop visualizer to overlay log data onto video streams to identify delay gaps.

Pipeline logging points

You can capture metadata at several points in the internal pipeline. Pipeline branches and downstream stages are nested below:

• Media Server

  • outgoing_metadata: Metadata received directly from the plugin.

    • analytics_event_receptor: Metadata heading to the server database.

    • live_stream_provider: Primary server hub for the stream.

      • spush_media_stream_provider: Secondary processing in the stream hub.

        • rtsp_consumer_put_data: Stream preparation stage before feeding the desktop client.

        • rtsp_consumer_process_data: Final stage feeding the stream to the desktop client.

• Desktop Client

  • rtp_parser: Metadata extracted from the incoming server stream.

    • widget_analytics_controller: Metadata selected for video display.

Enable metadata logging

To set up metadata logging:

1. Open analytics_logging.ini.

2. Set analyticsLogPath to the target log directory (relative to the .ini file location or as an absolute path):

   analyticsLogPath=analytics_log_dir

3. (Optional) To include object bounding box coordinates in the logs, add:

   logObjectMetadataDetails=true

4. Restart the Media Server or Desktop Client to apply the changes.

Generated log files use names that contain the pipeline stage prefix, the camera device ID, and stream details (such as _high or _low suffixes).

Visualize recorded metadata

The Desktop Client can read a log file and overlay its recorded bounding boxes as translucent overlays on the video stream. You can compare these overlays against regular colored bounding boxes to pinpoint timing delays.

Because video frames and log timestamps must match, you cannot visualize old log files on a live video feed. To align timestamps properly, use one of the following methods:

• Archive playback: Play back the historical video archive for the exact timeframe when you recorded the log file.

• Virtual camera: Use a test camera configured to produce consistent timestamps on every run. Record the log during the first run, then replay the test camera with the same settings to visualize the overlay.

Step-by-step visualization setup

1. Open desktop_client.ini.

2. Set debugAnalyticsVideoOverlayFromLogFile to the absolute path of your log file:

   debugAnalyticsVideoOverlayFromLogFile=analytics_log_file

3. Restart the Desktop Client.

Additional debugging options

You can add these optional settings to desktop_client.ini to gather more timing data:

• displayAnalyticsObjectsDebugInfo=true: Displays timestamps and metadata directly next to object boxes in the camera window.

• showDebugTimeInformationInRibbon=true: Shows precise event start and end times, along with preview frame timestamps, in the right panel.

• showPreciseItemTimestamps=true: Replaces standard human-readable dates with precise system timestamps in the camera window.