Getting Started

The HLS Stream Monitor is an open web service to monitor one or more HLS streams for manifest errors and inconsistencies. For example:

• Media sequence counter issues.
• Discontinuity sequence counter issues.
• Detect stale manifests. The default is at least 6000ms but can be configured.

This tutorial walks you through how to setup an HLS Stream Monitor and how to configure a Prometheus and Grafana to visualize the status of the streams.

Prerequisites

• If you have not already done so, sign up for an OSC account.

Step 1: Create a HLS Stream Monitor

Navigate to the HLS Stream Monitor in the Eyevinn Open Source Cloud web console. Click on "Create monitor" and enter a name of the instance.

When the instance is in state running you can click on the instance menu and the menu item "Open API Docs".

Step 2: Add a monitor and a stream to monitor

Now let us create a monitor that will monitor a live stream (actually a stream from a FAST Channel Engine).

The URL to the live stream to monitor is https://eyevinn.ce.prod.osaas.io/channels/www/master.m3u8. Select the POST /monitor accordion and press "Try it out". Enter the following in the body.

{
  "streams": [
    "https://eyevinn.ce.prod.osaas.io/channels/www/master.m3u8"
  ],
  "stale_limit": 8000,
  "monitor_interval": 3000
}

Then press Execute. It has now created a monitor that will monitor the stream you specified.

Step 3: Check metrics

Scroll down to the bottom to an accordion GET /metrics and press "Try it out" and then Execute. You will get current metrics in the OpenMetrics format.

This means that your monitor is continuously monitoring the streams it has been specified to monitor.

Local Prometheus and Grafana

To try this out we will now setup a local Grafana and Prometheus for visualizing the monitoring. This setup includes pre-configured dashboards and data sources.

Before we do that we need to deploy a Basic Auth adapter in a Web Runner. Create a new Web Runner in the web console or with the OSC command line tool.

% osc create eyevinn-web-runner myadapter \
  -o GitHubUrl=https://github.com/EyevinnOSC/basic-auth-adapter \
  -o GitHubToken="{{secrets.ghtoken}}" \
  -o OscAccessToken="{{secrets.osctoken}}"

Now you have an adapter that provides Basic Auth authentication to your HLS Stream Monitor metrics instance. Now it is time to setup Prometheus and Grafana.

Create a folder called grafana

% mkdir grafana
% cd Grafana

Create a file called prometheus.yml containing this:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'hls-monitor'
    metrics_path: '/tutorial/metrics'
    basic_auth:
      username: 'myuser'
      password: 'changeme'
    static_configs:
      - targets: ['eyevinnlab-myadapter.eyevinn-web-runner.auto.prod.osaas.io']

Replace the hostname in the target to the address of the Web Runner containing your Basic Auth adapter.

Create a file called docker-compose.yml that contains the following.

version: '3'
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
      - GF_INSTALL_PLUGINS=grafana-piechart-panel
    volumes:
      - ./grafana/provisioning:/etc/grafana/provisioning
    depends_on:
      - prometheus

Now we can start the Prometheus and Grafana containers.

% docker-compose up -d

Verify Prometheus setup

1. Open Prometheus in your browser: http://localhost:9090
2. Navigate to Status -> Targets
3. Verify that the hls-monitor target is showing as "UP"
   • If it's not UP, check that you can reach the metrics endpoint https://eyevinnlab-myadapter.eyevinn-web-runner.auto.prod.osaas.io/test/metrics where test is the name of the HLS Stream Monitor instance.
   • Verify the prometheus.yml configuration matches your setup

Configure Grafana

1. Open Grafana in your browser: http://localhost:3001
   • Default login is not required (anonymous access is enabled)
2. Add Prometheus Data Source:
   • Go to Configuration (⚙️) -> Data Sources
   • Click "Add data source"
   • Select "Prometheus"
   • Set URL to: http://prometheus:9090
   • Click "Save & Test"
   • You should see "Data source is working"

Import the dashboard

1. In Grafana, go to Dashboards (four squares icon)
2. Click "Import"
3. Paste into the "Import via panel json" field the contents of this example dashboard file.
4. Click "Load"
5. Select your Prometheus data source in the dropdown
6. Click "Import"

Verify the Dashboard

Your dashboard should now be loaded and showing metrics from your HLS monitor. You should see:

• Monitor status indicators
• Error counts and distributions
• Stream health metrics
• Various other monitoring panels