Monitor Stream

Stream provides several monitoring mechanisms, depending on whether you need a visual dashboard, an automated health check, multi-site oversight, or log-based compatibility with older deployments.

Mechanism	Best For	Use It When
Web Dashboard	Human operators checking status visually	You want to inspect cameras, recent results, system status, and basic actions from a browser.
Heartbeat API	Automated system integration	You want another service, script, or monitoring platform to poll Stream health programmatically.
Online Monitoring	Remote management across multiple sites	You manage Stream licenses in the online dashboard and need activity status or inactivity notifications.
Monitoring Script	Legacy systems or log-based analysis	You need to monitor Stream through logs or support an older integration pattern.

Web Dashboard

Use the Web Dashboard when you have local access to Stream and need a visual, real-time view of the system. The dashboard helps operators inspect camera status, recent results, system information, webhook cache, API connectivity, and restart controls from a browser.

• Publish container port 8001 to the host when you start Stream.

Expose the Stream monitoring port

docker run ... -p 8001:8001 ...

• Open http://localhost:8001/ in your web browser. If Stream is installed on another machine in your local network, use that machine's local IP address, for example http://LOCAL_IP_ADDRESS:8001/.

Hover over underlined items, the status dot, and some links in the dashboard to view tooltips with more information.

The top navigation bar shows at a glance the running Stream version and status dot, as well as the following links:

New in version 1.61.0.

Cameras

The Cameras page shows the IDs of cameras configured in Stream, their status, health, last result time and image (see note), camera webhooks status, source URL and the last error message if any.

Clicking on any camera ID will open the Results page for that camera.

The page refreshes every 10 seconds unless you pause it with the play icon.

note

Last result time and image are only available if the jsonlines_file config parameter is set for the camera.

Results

The Results page shows the latest results, up to a maximum of 100 per camera, in sortable chronological order. 20 results are shown per page, with pagination controls.

The page refreshes every 10 seconds unless you pause it with the play icon or use the pagination controls.

Clicking on a camera ID (here or in the Cameras page) will filter the results for that camera only.

Each result shows the camera ID, timestamp, image, and, if any, the recognized license plates, regions, makes and models (if MMC available) and vehicle types.

Precise confidence scores are shown by hovering over items. They are also shown at a glance by the items' varying opacity.

The rightmost button (⎘) permits copying the full result in JSON format to the clipboard.

note

Results are only available if the jsonlines_file config parameter is set for the camera. Results images are only available if images have not been disabled by setting an empty image_format= config parameter for the camera.

System

The System page shows the running Stream version, video time used (for file processing), and the number of webhooks in cache.

The Check API Connectivity button allows you to check if Stream can connect to the snapshot cloud API.

The Restart Stream button allows you to restart Stream from the web interface.

note

The Stream container will only restart if the Docker container restart policy is set to always or unless-stopped. If not, you will need to manually restart the container via your Docker management tool.

Web-config

Opens the Plate Recognizer web configuration page in a new tab.

Guide

Opens this site in a new tab.

Heartbeat API

Use the Heartbeat API when another service needs to check Stream automatically. This approach fits uptime monitoring, alerting workflows, orchestration tools, and custom integrations that should not depend on a browser session.

Request Status

Publish container port 8001 to the host when you start Stream.

Expose the Stream monitoring port

docker run ... -p 8001:8001 ...

Send a GET request to the status endpoint.

Check Stream status

curl -i http://localhost:8001/status/

The server will return a status code 200 if all cameras are still functional, 500 otherwise.

New in version 1.51.0.

Status Response

The response body groups monitoring data by camera or file source. The example below shows the general response shape before the following sections explain specific values such as health, file progress, and network indicators.

Heartbeat API response

{
  "version": "1.51.0",
  "cameras": {
    "camera-1": {
      "health": -1,
      "status": "starting",
      "last_checked": "2024-05-13 11:21:44.904403+00:00",
      "received_fps": -1.0, // starting from version 1.58.0
      "buffered_frames": 0, // starting from version 1.58.0
      "file_processing": {
        // starting from version 1.56.0
        "processed_seconds": -1.0,
        "total_seconds": -1.0
      }
    },
    "camera-2": {
      "health": 95,
      "status": "running",
      "last_checked": "2024-05-13 11:21:44.904623+00:00",
      "received_fps": 24.5,
      "buffered_frames": 3,
      "file_processing": {
        "processed_seconds": -1.0,
        "total_seconds": -1.0
      }
    },
    "camera-3": {
      "health": 0,
      "status": "stopped",
      "last_checked": "2024-05-13 11:21:44.904623+00:00",
      "received_fps": 0.1,
      "buffered_frames": 90,
      "file_processing": {
        "processed_seconds": -1.0,
        "total_seconds": -1.0
      }
    }
  }
}

All last_checked timestamps use the timezone parameter configured for each camera.

File processing

For files, the same Heartbeat API response can also include processing progress:

File processing progress

{
  "version": "1.56.0",
  "cameras": {
    "file-1": {
      "health": 95,
      "status": "running",
      "last_checked": "2024-05-13 11:21:44.904623+00:00",
      "received_fps": 0.1, // starting from version 1.58.0
      "buffered_frames": 90, // starting from version 1.58.0
      "file_processing": {
        // starting from version 1.56.0
        "processed_seconds": 10,
        "total_seconds": 100
      }
    }
  }
}

New in version 1.56.0.

Network

Heartbeat also provides useful information about network connection through received_fps and buffered_frames fields.

The received_fps field indicates how many frames of the original footage Stream is fetching per second. This value is not affected by the sample parameter and should be close to the actual FPS output of the camera. If not, it could indicate network problems.

The buffered_frames field is the percentage of received frames that were buffered by the video backend before being processed. Some buffering is acceptable, but 25% or more could indicate bandwidth or processing bottlenecks. Note that this value could be unreliable for Variable Bitrate videos.

New in version 1.58.0.

Online Monitoring

Online Monitoring is useful when you manage Stream remotely through the online dashboard, especially across multiple licenses or sites. Use it to review license activity, check the last activity time, compare direct and cloud licenses, and confirm whether webhooks and video feeds are active.

Open Stream Monitoring

Open the Stream Monitoring page from the left sidebar by selecting Stream and then Monitoring. The page lists your licenses with their check interval, last activity, status, and webhook details.

In the screenshot, number 1 highlights the Monitoring menu item. Click the icon in the Status column to open the activity status page for a license. Number 2 highlights the license interval, which can open the setup notification page for that license.

Activity Status

Use the Activity Status page to review license status and camera-level activity. This page shows the current check interval, each camera URL, last activity time, health score, active status, video feed status, and webhook status.

The following symbols and colors indicate the status of each stream:

• All Active: ✅
• Partially Active: ⚠️
• Inactive: ❌
• Not Installed: ✘

Setting Up Inactivity Notifications

Set up inactivity notifications to receive an email when a license has no activity for a defined period of time. On the Stream settings page, open the Manage menu for the license and select Setup Notification.

1. Navigate to the Stream settings page.
2. Open the Manage menu for the license.
3. Select Setup Notification.
4. Enable the inactivity email notification option.
5. Choose the inactivity interval.
6. Choose the notification interval. The minimum interval is 1 hour.
7. Click Save.

Use Stream Activity Status with inactivity notifications to monitor stream status and stay informed about potential issues.

Monitoring Script

The Monitoring Script is best for legacy systems or integrations that need to infer status from Stream logs.

Stream Monitor checks Stream status through its logs. It exposes a single API endpoint that returns the status of each camera (running or offline). The command python stream_monitor.py starts a web server that returns the status of each camera. For example:

Monitoring script response

{
  "active": true,
  "cameras": {
    "camera-1": {
      "status": "running"
    }
  }
}

See instructions and examples on our GitHub.