Monitoring Amazon IVS Live Stream Health - Amazon Interactive Video Service

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

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

  1. Open the Amazon IVS console.

    (You also can access the Amazon IVS console through the AWS Management Console.)

  2. In the top left, choose the hamburger icon to open the navigation pane, then choose Channels.

  3. Choose the channel to go to its details page.

  4. Scroll down the page until you see the Stream sessions section.

  5. 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.

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.

  1. List streams sessions:

    aws ivs list-stream-sessions --channel-arn <arn>
  2. 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

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. In the side navigation, expand the Metrics dropdown, then select All metrics.

  3. In the AWS Namespaces section, select IVS.

  4. In the search bar, enter your resource ID (arn:::ivs:channel/<resource id>).

  5. Select IVS > By Channel.

  6. Add new metrics to the graph: IngestAudioBitrate, IngestFramerate, IngestVideoBitrate, and/or KeyframeInterval.

  7. 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

  1. Open the Amazon IVS console.

    (You also can access the Amazon IVS console through the AWS Management Console.)

  2. In the top left, choose the hamburger icon to open the navigation pane, then choose Live channels.

  3. Select the search field for Filter by health.

  4. 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 name=STARVING

CloudWatch Health Dimension for ConcurrentStreams

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