Monitoring Amazon IVS Low-Latency Streaming
You can monitor Amazon Interactive Video Service (IVS) resources using Amazon CloudWatch. 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 the CloudWatch User Guide.
The timestamp on a metric represents the start of the period during which metric data is
accumulated. For example, suppose you get a per-minute LiveDeliveredTime
metric
sum of 300 seconds at 01:02:00. This would mean that 5 minutes’ worth of video was served to
viewers during the 1-minute period from 01:02:00 to 01:02:59.
For metrics designated as high resolution, the first data point appears several seconds after stream start. We recommend you specify a 5-second period when making the metric requests. (See Resolution in the Amazon CloudWatch User Guide.) For other metrics, data is emitted within 1 minute of the timestamp to which it refers.
The high-resolution 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).
For current information on data retention, search for "retention period" in Amazon CloudWatch FAQs
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 IVS Low-Latency Streaming.
-
You must create a channel and start a stream. Relevant information is in the IVS Low-Latency Streaming User Guide:
-
For instructions on creating a channel, see Create a Channel in Getting Started with IVS Low-Latency Streaming.
-
For instructions on starting a stream, see Set Up Streaming Software in Getting Started with IVS Low-Latency Streaming.
-
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" } } }
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
.
See CloudWatch Metrics: IVS Low-Latency Streaming.
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 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.
-
On the Browse tab, using the unlabeled dropdown at the left, select your “home” region, where your channel(s) was(were) created. For more on regions, see Global Solution, Regional Control. For a list of supported regions, see the Amazon IVS page in the AWS General Reference.
-
At the bottom of the Browse tab, select the IVS namespace.
-
Do one of the following:
-
In the search bar, enter your resource ID (part of the ARN,
arn:::ivs:channel/<resource id>
).Then select IVS > By Channel.
-
If IVS appears as a selectable service under AWS Namespaces, select it. It will be listed if you use Amazon IVS and it is sending metrics to Amazon CloudWatch. (If IVS is not listed, you do not have any Amazon IVS metrics.)
Then choose a dimension grouping as desired; available dimensions are listed in CloudWatch Metrics below.
-
-
Choose metrics to add to the graph. Available metrics are listed in CloudWatch Metrics below.
You also can access your stream session’s CloudWatch chart from the stream session’s details page, by selecting the View in CloudWatch button.
CLI Instructions
You also can access the metrics using the AWS CLI. This requires that you first download and configure the CLI on your machine. For details, see the AWS Command Line Interface User Guide.
Then, to access Amazon IVS low-latency streaming metrics using the AWS CLI:
-
At a command prompt, run:
aws cloudwatch list-metrics --namespace AWS/IVS
For more information, see Using Amazon CloudWatch Metrics in the Amazon CloudWatch User Guide.
CloudWatch Metrics: IVS Low-Latency Streaming
Amazon IVS provides the following metrics in the AWS/IVS namespace.
Metric | Dimension | Description |
---|---|---|
|
None |
A count of concurrent views across all your live channels. A view is a unique viewing session which is actively downloading or playing video. (For a more detailed definition, see the IVS Glossary.) If channels are live but in aggregate have no views, the value of this metric is 0. If no channels are live, the metric has no data points. Unit: Count Valid statistics: Average, Maximum, Minimum — Average number, largest number, or smallest number (respectively) of concurrent views over the configured interval. |
|
|
Filters This metric provides data for a channel, not a stream. To see
concurrent views for a particular streaming session on a given
channel, evaluate the Unit: Count Valid statistics: Average, Maximum, Minimum — Average number, largest number, or smallest number (respectively) of concurrent views over the configured interval. |
|
None |
A count of your channels which are streaming live. If no channels are live, this metric has no data points. Unit: Count Valid statistics: Average, Maximum, Minimum — Average number, largest number, or smallest number (respectively) of concurrent streams over the configured interval. |
|
|
Filters Unit: Count Valid statistics: Average, Maximum, Minimum — Average number,
largest number, or smallest number (respectively) of concurrent
streams for a specific |
|
|
(High-resolution metric) The amount of audio data Amazon IVS receives when you stream. A higher bitrate takes up more of your available internet bandwidth. Unit: Bits/second Valid statistics: Average, Maximum, Minimum — Average number, largest number, or smallest number (respectively) of ingest audio bitrates over the configured interval |
|
|
(High-resolution metric) How often video frames are received by Amazon IVS when you stream. Unit: Count/second Valid statistics: Average, Maximum, Minimum — Average number, largest number, or smallest number (respectively) of ingest framerates over the configured interval |
|
|
(High-resolution metric) The amount of video data Amazon IVS receives when you stream. A higher bitrate takes up more of your available internet bandwidth. Higher bitrate can improve video quality, but only up to a certain point. Unit: Bits/second Valid statistics: Average, Maximum, Minimum — Average number, largest number, or smallest number (respectively) of ingest video bitrates over the configured interval |
|
|
(High-resolution metric) The point in the video stream where the entire frame is sent instead of just the differences from the previous frame. Unit: Seconds Valid statistics: Average, Maximum, Minimum — Average number, largest number, or smallest number (respectively) of keyframe intervals over the configured interval |
|
None | Total real-time duration of video served to all viewers. Unit: Seconds Valid statistic: Sum |
|
|
Filters Unit: Seconds Valid statistic: Sum |
|
|
Filters Unit: Seconds Valid statistic: Sum |
|
None | Real-time duration of video stream. Unit: Seconds Valid statistic: Sum |
|
|
Filters Unit: Seconds Valid statistic: Sum |
|
None | Real-time duration of recorded video. Unit: Seconds Valid statistic: Sum |
|
|
Filters Unit: Seconds Valid statistic: Sum |