Prerequisites Access Stream Session Data Access CloudWatch Metrics Filter Streams by Health

Monitoring Amazon IVS Live Stream Health

This section explains how you can access stream-session data, including stream events and encoder configuration, as well as how you can monitor your ingest metrics with Amazon CloudWatch.

Note: Audio- and video-configuration data provided in the API is provided on a best-effort basis, as it depends on metadata provided by the encoder used.

This documentation takes you through the steps to get started.

Prerequisites

You must have an AWS account with sufficient IAM permissions to interface with the Stream Health APIs and CloudWatch metrics. For specific steps, see Getting Started with Amazon IVS in the Amazon IVS User Guide.
You must create a channel and start a stream. Relevant information is in the Amazon IVS User Guide:
- For instructions on creating a channel, see Create a Channel in Getting Started with Amazon IVS.
- For instructions on starting a stream, see Set Up Streaming Software in Getting Started with Amazon IVS.
- For encoder-configuration details, see Amazon IVS Streaming Configuration.

Access Stream Session Data

Using the listStreamSessions endpoint, you can access a list of streams that a channel has had for up to 60 days. This list may include a live stream session (denoted by an empty endTime).

You can get the session data for a specific stream through the getStreamSession endpoint. If you do not specify the streamId parameter, the endpoint returns the latest session. In addition, you can periodically call the endpoint to get your stream’s latest events (up to the most recent 500).

Console Instructions

Open the Amazon IVS console.

(You also can access the Amazon IVS console through the AWS Management Console.)
On the navigation pane, choose Channels. (If the nav pane is collapsed, first open it by choosing the hamburger icon.)
Choose the channel to go to its details page.
Scroll down the page until you see the Stream sessions section.
Select the Stream ID of the session you want to access to view its session details, including charts for the Amazon CloudWatch high-resolution metrics.

Alternatively, if one or more channels are already live:

Open the Amazon IVS console.
On the navigation pane, choose Live channels. (If the nav pane is collapsed, first open it by choosing the hamburger icon.)
Select a live channel from the list to access its session details inside a split view.

AWS SDK Instructions

Accessing stream-session data with the AWS SDK is an advanced option and requires that you first download and configure the SDK on your application. Below are instructions for the AWS SDK using JavaScript.

Prerequisite: To use the code sample below, you need to load the AWS JavaScript SDK into your application. For details, see Getting started with the AWS SDK for JavaScript.


// This first call lists up to 50 stream sessions for a given channel.
const AWS = require("aws-sdk");
const REGION = 'us-west-2';
let channelArn = USE_YOUR_CHANNEL_ARN_HERE;

AWS.config.getCredentials(function(err) {
  if (err) console.log(err.stack);
  // credentials not loaded
  else {
    console.log("Access key:", AWS.config.credentials.accessKeyId);
  }
});

AWS.config.update({region: REGION});
var ivs = new AWS.IVS();

// List Stream Sessions
async function listSessions(arn) {
  const result = await ivs.listStreamSessions({"channelArn": arn}).promise();
  console.log(result.streamSessions);
}
listSessions(channelArn);

// Get Stream Session
async function getSession(arn, id) {
  const result = await ivs.getStreamSession({"channelArn": arn, "streamId": id}).promise();
  console.log(result);

  // This function polls every 3 seconds and prints the latest IVS stream events.
  setInterval(function(){
    console.log(result.streamSession.truncatedEvents);
  }, 3000);
}
getSession(channelArn);

CLI Instructions

Accessing stream-session data with the AWS CLI is an advanced option and requires that you first download and configure the CLI on your machine. For details, see the AWS Command Line Interface User Guide.

List streams sessions:


aws ivs list-stream-sessions --channel-arn <arn>

Get stream session data for a specific stream using its streamId:


aws ivs get-stream-session --channel-arn <arn> --stream-id <streamId>

Here is a sample response to the get-stream-session call:


{
    "streamSession": {
        "startTime": "2021-10-22T00:03:57+00:00",
        "streamId": "st-1FQzeLONMT9XTKI43leLSo1",
        "truncatedEvents": [
            {
                "eventTime": "2021-10-22T00:09:30+00:00",
                "name": "Session Ended",
                "type": "IVS Stream State Change"
        	},
            {
                "eventTime": "2021-10-22T00:09:30+00:00",
                "name": "Stream End",
                "type": "IVS Stream State Change"
        	},
        	{
                "eventTime": "2021-10-22T00:03:57+00:00",
                "name": "Stream Start",
                "type": "IVS Stream State Change"
        	},
        	{
                "eventTime": "2021-10-22T00:03:50+00:00",
                "name": "Session Created",
                "type": "IVS Stream State Change"
        	}
        ],
        "endTime": "2021-10-22T00:09:31+00:00",
        "ingestConfiguration": {
            "audio": {
                "channels": 2,
                "codec": "mp4a.40.2",
                "sampleRate": 48000,
                "targetBitrate": 160000
        	},
            "video": {
                "avcLevel": "4.0",
                "avcProfile": "Baseline",
                "codec": "avc1.42C028",
                "encoder": "obs-output module (libobs version 27.0.1)",
                "targetBitrate": 3500000,
                "targetFramerate": 30,
                "videoHeight": 1080,
                "videoWidth": 1920
            }
        },
        "channel": {
            "name": "",
            "ingestEndpoint": "3f234d592b38.global-contribute.live-video.net",
            "authorized": false,
            "latencyMode": "LOW",
            "recordingConfigurationArn": "",
            "type": "STANDARD",
            "playbackUrl": "https://3f234d592b38.us-west-2.playback.live-video.net/api/video/v1/us-west-2.991729659840.channel.dY7LsluQX1gV.m3u8",
            "arn": "arn:aws:ivs:us-west-2:991729659840:channel/dY7LsluQX1gV"
        }
    }
}

Access CloudWatch Metrics

Amazon CloudWatch collects and processes raw data from Amazon IVS into readable, near-real-time metrics. These statistics are kept for 15 months, so you can gain a historical perspective on how your web application or service performs. You can set alarms for certain thresholds and send notifications or take actions when those thresholds are met. For details, see Monitoring Amazon IVS with Amazon CloudWatch and the CloudWatch User Guide.

Note that CloudWatch metrics are rolled up over time. Resolution effectively decreases as the metrics age. Here is the schedule:

1-second metrics are available for 3 hours.
60-second metrics are available for 15 days.
5-minute metrics are available for 63 days.
1-hour metrics are available for 455 days (15 months).

When you call getMetricData you can specify a period of 1, 5 (recommended), 10, 30 or any multiple of 60 seconds for high-resolution metrics.

CloudWatch Console Instructions

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
In the side navigation, expand the Metrics dropdown, then select All metrics.
In the AWS Namespaces section, select IVS.
In the search bar, enter your resource ID (arn:::ivs:channel/<resource id>).
Select IVS > By Channel.
Add new metrics to the graph: IngestAudioBitrate, IngestFramerate, IngestVideoBitrate, and/or KeyframeInterval.
Under Graphed Metrics, make sure the period for your metrics is set to 5 Seconds.

You also can access your stream session’s CloudWatch chart from the stream session’s details page, by selecting the View in CloudWatch button.

AWS SDK Instructions

You also can access the CloudWatch metrics using the AWS SDK:


const AWS = require("aws-sdk");
const REGION = 'us-west-2';
let channelArn = USE_YOUR_CHANNEL_ARN_HERE;

AWS.config.getCredentials(function(err) {
  if (err) console.log(err.stack);
  // credentials not loaded
  else {
    console.log("Access key:", AWS.config.credentials.accessKeyId);
  }
});

AWS.config.update({region: REGION});
var ivs = new AWS.IVS();

// Get Stream Metrics
async function getMetrics(arn) {
  const sessionResult = await ivs.getStreamSession({"channelArn": arn}).promise();
  const cw = new AWS.CloudWatch({apiVersion: '2010-08-01'});

  const streamHealthMetrics = ["IngestAudioBitrate", "IngestVideoBitrate", "IngestFramerate", "KeyframeInterval"];
  const MetricDataQueries = streamHealthMetrics.map((MetricName) => ({
    Id: MetricName.toLowerCase(),
    MetricStat: {
      Metric: {
        MetricName,
        Namespace: "AWS/IVS",
        Dimensions: [{Name: "Channel", Value: arn.split("/")[1]}]
      },
      Period: 5,
      Stat: "Average",
    }
  }));
  
  const cwParams = {
    StartTime: sessionResult.streamSession.startTime,
    EndTime: sessionResult.streamSession.endTime,
    MetricDataQueries,
    // Remove below line to print full results
    MaxDatapoints: 20 
  };
  const cwResult = await cw.getMetricData(cwParams).promise();
  console.log(JSON.stringify(cwResult, null, 4));
}
getMetrics(channelArn);

Filter Streams by Health

To easily find which streams are experiencing issues, you can use listStreams to filter live streams by “health.”

Console Instructions

Open the Amazon IVS console.

(You also can access the Amazon IVS console through the AWS Management Console.)
On the navigation pane, choose Live channels. (If the nav pane is collapsed, first open it by choosing the hamburger icon.)
Select the search field for Filter by health.
In the drop-down list, select filtering by Health = STARVING.

After filtering, you can go to a channel’s details page and select the channel’s live-stream session, to access input-configuration details and stream events.

CLI Instructions

Using the AWS CLI is an advanced option and requires that you first download and configure the CLI on your machine. For details, see the AWS Command Line Interface User Guide.

To filter streams by health (e.g. STARVING):


aws ivs list-streams --filter-by health=STARVING

CloudWatch Health Dimension for ConcurrentStreams

You can filter ConcurrentStreams by a specific Health. For details, see Monitoring Amazon IVS with Amazon CloudWatch.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Chat Message Review Handler

Amazon IVS Broadcast SDK