Using Amazon EventBridge with Amazon Interactive Video Service - Amazon Interactive Video Service

Using Amazon EventBridge with Amazon Interactive Video Service

You can use Amazon EventBridge to monitor your Amazon Interactive Video Service (IVS) streams.

Amazon IVS sends change events about the status of your streams to Amazon EventBridge. All events that are delivered are valid. However, events are sent on a best-effort basis, which means there is no guarantee that:

  • Events are delivered — A designated event can occur (e.g., a stream starts) but it is possible that Amazon IVS will not send a corresponding change event to EventBridge. Amazon IVS tries to deliver events for several hours before giving up.

  • Events that are delivered will arrive in a specified timeframe — You may receive events up to a few hours old.

  • Events that are delivered are ordered correctly — Events may be out of order, especially if they are sent within a short time of each other. For example, you could see stream down before stream up.

While it's rare for events to be missing, late, or out of sequence, you should handle these possibilities if you write business-critical programs that depend on the order or existence of notification events.

You can create EventBridge rules for any of the following events.

Event Type Event Sent When ...
IVS Stream State Change Stream Start A stream is being processed and segments are available for the viewer to watch.
IVS Stream State Change Stream End A stream stops being processed and no longer produces segments for the viewer.
IVS Stream State Change Stream Failure A stream is not being processed and is not available because processing capacity was exceeded.
IVS Stream Health Change Starvation Start A stream is not receiving data from the streamer; the stream is said to be in “starvation.”
IVS Stream Health Change Starvation End A starving stream begins receiving data from the streamer and the stream is healthy again.
IVS Limit Breach Ingest Bitrate The incoming stream’s bitrate exceeds the Amazon IVS limit.
IVS Limit Breach Ingest Resolution The incoming stream’s resolution exceeds the Amazon IVS limit.
IVS Limit Breach Concurrent Broadcasts The total number of channels streaming at the same time exceeds the Amazon IVS limit.
IVS Limit Breach Concurrent Viewers The total number of viewers watching your channels at the same time exceeds the Amazon IVS limit.
IVS Recording State Change Recording Start A stream starts being processed and segments are being written to the storage location configured for the channel.
IVS Recording State Change Recording End A stream ends and recording stops for this channel.
IVS Recording State Change Recording Start Failure A stream starts but recording fails to start due to errors (for example, the S3 bucket does not exist or is not in the correct region). This live stream is not recorded.
IVS Recording State Change Recording End Failure Recording ends with failure, due to errors encountered during recording. Some objects may still be written to the configured storage location.

Note on stream IDs: The stream_id field (in many events) is a unique stream identifier assigned each time a channel goes live. For a given channel, each live stream has a new stream_id. Hence, each channel ARN can have many corresponding stream IDs. Stream IDs allow customers to distinguish different stream sessions on the same channel.

Note on latency of some events: Encoder-configuration settings, especially the IDR/keyframe interval, affect the timing of stream startup and the latency of related events (Stream Start and Recording Start). A shorter keyframe interval decreases this latency. See "Reducing Latency" in Amazon IVS Streaming Configuration for information on setting IDR/Keyframe.

Creating Amazon EventBridge Rules for Amazon IVS

You can create a rule that triggers on an event emitted by Amazon IVS. Follow the steps in Creating an EventBridge Rule That Triggers on an Event from an AWS Resource in the Amazon EventBridge User Guide. When you need to select a Service name, choose Interactive Video Service (IVS).

Examples: Stream State Change

Stream Start: This event is sent when a stream is being processed and segments are available for the viewer.

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Stream State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890" ], "detail": { "event_name": "Stream Start", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn" } }

Stream End: This event is sent when a stream stops being processed and no longer produces segments for the viewer.

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Stream State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890" ], "detail": { "event_name": "Stream End", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn" } }

Stream Failure: This event is sent when a stream is not being processed and is not available because processing capacity was exceeded.

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Stream State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890" ], "detail": { "event_name": "Stream Failure", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn", "reason": "Transcode capacity exceeded. Please try again." } }

Examples: Stream Health Change

Starvation Start: This event is sent when a stream is not receiving data from the streamer; the stream is said to be in “starvation.”

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Stream Health Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890" ], "detail": { "event_name": "Starvation Start", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn" } }

Starvation End: This event is sent when a starving stream begins receiving data from the streamer and the stream is healthy again.

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Stream Health Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890" ], "detail": { "event_name": "Starvation End", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn" } }

Examples: Limit Breach

All limit-breach events include the name of the limit that is breached, the value of the limit, and the number by which the limit was exceeded (value at breach subtracted by the limit).

Ingest Bitrate: This event is sent when the incoming stream’s bitrate exceeds the Amazon IVS limit.

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Limit Breach", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890" ], "detail": { "limit_name": "Ingest Bitrate", "limit_value": 1234, "exceeded_by": 3, "limit_unit": "bits per second", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn" } }

Ingest Resolution: This event is sent when the incoming stream’s resolution (total pixels or pixels per edge) exceeds the Amazon IVS limits.

Maximum total pixels exceeded:

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Limit Breach", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890" ], "detail": { "limit_name": "Ingest Resolution", "limit_value": 495000, "exceeded_by": 426600, "limit_unit": "total pixels", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn" } }

Maximum pixels per edge exceeded:

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Limit Breach", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:channel/12345678-1a23-4567-a1bc-1a2b34567890"TBD ], "detail": { "limit_name": "Ingest Resolution", "limit_value": 855, "exceeded_by": 45, "limit_unit": "pixels per edge", "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn" } }

Concurrent Broadcasts: This event is sent when the total number of channels streaming at the same time exceeds the Amazon IVS limit.

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Limit Breach", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [], "detail": { "limit_name": "Concurrent Broadcasts", "limit_value": 2, "exceeded_by": 3, "limit_unit": "active streams" } }

Concurrent Viewers: This event is sent when the total number of viewers watching your channels at the same time exceeds the Amazon IVS limit.

{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Limit Breach", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [], "detail": { "limit_name": "Concurrent Viewers", "limit_value": 10, "exceeded_by": 11, "limit_unit": "viewers" } }

Examples: Recording State Change

For all recording state change events, The top-level path where all objects for this live stream are stored is recording_s3_key_prefix. In the case of failures, the reason for the failure is in recording_status_reason. The recording_duration_ms field is the number of milliseconds of recording duration.

Recording Start: This event is sent when a stream starts being processed and segments are being written to the storage location configured for the channel.

{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2020-06-23T20:12:36Z", "region": "us-west-2", "resources": [ "arn:aws:ivs:us-west-2:123456789012:channel/AbCdef1G2hij" ], "detail": { "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn", "recording_status": "Recording Start", "recording_status_reason": "", "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings", "recording_s3_key_prefix": "ivs/v1/123456789012/AbCdef1G2hij/2020/6/23/20/12/j8Z9O91ndcVs", "recording_duration_ms": 0 } }

Recording End: This event is sent when a stream ends and recording stops for this channel.

{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2020-06-24T07:51:32Z", "region": "us-west-2", "resources": [ "arn:aws:ivs:us-west-2:123456789012:channel/AbCdef1G2hij" ], "detail": { "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn", "recording_status": "Recording End", "recording_status_reason": "", "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings", "recording_s3_key_prefix": "ivs/v1/123456789012/AbCdef1G2hij/2020/6/23/20/12/j8Z9O91ndcVs", "recording_duration_ms": 99370264 } }

Recording Start Failure: This event is sent when a stream starts but recording fails to start due to errors (for example, the S3 bucket does not exist or is not in the correct region). This live stream is not recorded.

{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2020-06-23T20:12:36Z", "region": "us-west-2", "resources": [ "arn:aws:ivs:us-west-2:123456789012:channel/AbCdef1G2hij" ], "detail": { "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn", "recording_status": "Recording Start Failure", "recording_status_reason": "ValidationException", "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings", "recording_s3_key_prefix": "", "recording_duration_ms": 0 } }

Recording End Failure: This event is sent when recording ends with failure, due to errors encountered during recording. Some objects may still be written to the configured storage location.

{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2020-06-24T07:51:32Z", "region": "us-west-2", "resources": [ "arn:aws:ivs:us-west-2:123456a7-ab1c-2d34-e5f6-1a2b3c4d5678" ], "detail": { "channel_name": "Your Channel", "stream_id": "st-1A2b3c4D5e6F78ghij9Klmn", "recording_status": "Recording End Failure", "recording_status_reason": "InternalServerException", "recording_s3_bucket_name": "r2s3-dev-channel-1-recordings", "recording_s3_key_prefix": "ivs/v1/123456789012/AbCdef1G2hij/2020/6/23/20/12/j8Z9O91ndcVs", "recording_duration_ms": 0 } }