# Monitoring and tagging AWS Elemental MediaTailor resources Monitoring is an important part of maintaining the reliability, availability, and performance of AWS Elemental MediaTailor and your other AWS solutions. AWS provides the following monitoring tools to watch MediaTailor, report when something is wrong, and take automatic actions when appropriate: + *Amazon CloudWatch* monitors your AWS resources and the applications that you run on AWS in real time. You can collect and track metrics, create customized dashboards, and set alarms that notify you or take actions when a specified metric reaches a threshold that you specify. For example, you can have CloudWatch track CPU usage or other metrics of your Amazon EC2 instances and automatically launch new instances when needed. For more information, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). + *Amazon CloudWatch Logs* enables you to monitor, store, and access your log files from all interactions with your ad decision server (ADS). AWS Elemental MediaTailor emits logs for ad requests, redirects, responses, and reporting requests and responses. Errors from the ADS and origin servers are also emitted to log groups in Amazon CloudWatch. MediaTailor also provides information about skipped ads and the reasons they were skipped. For more information, see [Ad skipping troubleshooting](troubleshooting-ad-skipping-overview.md). You can also archive your log data in highly durable storage. For general information, see the [Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/). For information on the ADS logs and how to access them for analysis through Amazon CloudWatch Logs Insights, see [AWS Elemental MediaTailor ADS log analysis in Amazon CloudWatch Logs Insights](monitor-cloudwatch-ads-logs.md). **Topics** + [ # Viewing AWS Elemental MediaTailor logs ](monitoring-through-logs.md) + [ # Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics ](monitoring-cloudwatch-metrics.md) + [ # Recording AWS Elemental MediaTailor API calls ](logging-using-cloudtrail.md) + [ # Receiving AWS Elemental MediaTailor channel assembly alerts ](channel-assembly-alerts.md) + [ # Tagging AWS Elemental MediaTailor resources ](tagging.md) + [ # Monitoring AWS media services with workflow monitor ](monitor-with-workflow-monitor.md) # Viewing AWS Elemental MediaTailor logs MediaTailor emits logs that describe a variety of milestones and activities in channels and playback configurations. You can use these logs to gain visibility into your workflow and to troubleshoot issues with the service. The following topics describe logs and logging options. **Topics** + [ADS logs](ads-log-format.md) + [Manifest logs](log-types.md) + [Transcode logs](tm-log-format.md) + [Using vended logs](vended-logs.md) + [Writing logs to CloudWatch Logs](monitoring-cw-logs.md) + [Controlling the volume of ad insertion session logs](log-configuration.md) + [Filtering logs and events](logs-filter.md) + [Generating debug logs](debug-log-mode.md) # AWS Elemental MediaTailor ADS logs description and event types The following sections describe the logs that MediaTailor emits to describe events with the ad decision server (ADS). These are `AdDecisionServerInteractions` logs. **Topics** + [ ## AdDecisionServerInteractions events ](#log-types-adsinteraction) + [ ## ADS log description ](#ads-log-description) + [ ## ADS log JSON schema ](#ads-log-json-schema) ## AdDecisionServerInteractions events The following events are emitted during MediaTailor interactions with the ad decision server (ADS). | Log | Description | | --- | --- | | AD\$1MARKER\$1FOUND | MediaTailor found an ad marker in the manifest. | | BEACON\$1FIRED | A tracking beacon was fired to report ad events. In server-side reporting mode (default), MediaTailor fires the beacon. In client-side reporting mode, the playback device fires the beacon. | | EMPTY\$1VAST\$1RESPONSE | The ADS returned an empty VAST response containing zero ads. | | EMPTY\$1VMAP\$1RESPONSE | The ADS returned an empty VMAP response. | | ERROR\$1ADS\$1INVALID\$1RESPONSE | The ADS returned a non-200 status code. | | ERROR\$1ADS\$1IO | MediaTailor encountered an error while trying to communicate with the ADS. | | ERROR\$1ADS\$1RESPONSE\$1PARSE | MediaTailor encountered an error while parsing the ADS response. | | ERROR\$1ADS\$1RESPONSE\$1UNKNOWN\$1ROOT\$1ELEMENT | The ADS response contains an invalid root element. | | ERROR\$1ADS\$1TIMEOUT | The MediaTailor request to the ADS timed out. | | ERROR\$1DISALLOWED\$1HOST | The ADS host is not allowed. | | ERROR\$1FIRING\$1BEACON\$1FAILED | MediaTailor failed at firing the tracking beacon. | | ERROR\$1PERSONALIZATION\$1DISABLED | Ad insertion is disabled for this session. | | ERROR\$1UNKNOWN | MediaTailor encountered an unknown error during the ADS request. | | ERROR\$1UNKNOWN\$1HOST | The ADS host is unknown. | | ERROR\$1VAST\$1INVALID\$1MEDIA\$1FILE | The VAST Ad has an invalid or missing MediaFile element. | | ERROR\$1VAST\$1INVALID\$1VAST\$1AD\$1TAG\$1URI | The VAST response contains an invalid VASTAdTagURI. | | ERROR\$1VAST\$1MISSING\$1CREATIVES | The VAST Ad contains zero or multiple Creatives elements. Exactly one Creatives element is required. | | ERROR\$1VAST\$1MISSING\$1IMPRESSION | The VAST Ad contains zero Impression elements. At least one Impression element is required. | | ERROR\$1VAST\$1MISSING\$1MEDIAFILES | The VAST Ad contains zero or multiple MediaFiles elements. Exactly one MediaFiles element is required. | | ERROR\$1VAST\$1MISSING\$1OVERLAYS | MediaTailor didn't receive any non-linear creatives from the ad server. | | ERROR\$1VAST\$1MULTIPLE\$1LINEAR | The VAST Ad contains multiple Linear elements. | | ERROR\$1VAST\$1MULTIPLE\$1TRACKING\$1EVENTS | The VAST Ad contains multiple TrackingEvents elements. | | ERROR\$1VAST\$1REDIRECT\$1EMPTY\$1RESPONSE | The VAST redirect request returned an empty response. | | ERROR\$1VAST\$1REDIRECT\$1FAILED | The VAST redirect request encountered an error. | | ERROR\$1VAST\$1REDIRECT\$1MULTIPLE\$1VAST | The VAST redirect request returned multiple ads. | | FILLED\$1AVAIL | MediaTailor successfully filled the avail. | | FILLED\$1OVERLAY\$1AVAIL | MediaTailor successfully filled the overlay avail. | | INTERSTITIAL\$1VOD\$1FAILURE | The ADS request or response encountered a problem while filling interstitial avails for the VOD playlist. No ads will be inserted. | | INTERSTITIAL\$1VOD\$1SUCCESS | MediaTailor successfully filled interstitial avails for the VOD playlist. | | MAKING\$1ADS\$1REQUEST | MediaTailor is requesting advertisements from the ADS. | | MODIFIED\$1TARGET\$1URL | MediaTailor modified the outbound target URL. | | NON\$1AD\$1MARKER\$1FOUND | MediaTailor found a non-actionable ad marker in the manifest. | | RAW\$1ADS\$1RESPONSE | MediaTailor received a raw ADS response. | | REDIRECTED\$1VAST\$1RESPONSE | MediaTailor received a VAST response after following the VAST redirect. | | VAST\$1REDIRECT | The VAST ad response contains a redirect. | | VAST\$1RESPONSE | MediaTailor received a VAST response. | | VOD\$1TIME\$1BASED\$1AVAIL\$1PLAN\$1SUCCESS | MediaTailor successfully created a time-based avail plan for the VOD template. | | VOD\$1TIME\$1BASED\$1AVAIL\$1PLAN\$1VAST\$1RESPONSE\$1FOR\$1OFFSET | MediaTailor is creating a time-based avail plan for the VOD template. MediaTailor received a VAST response for the time offset. | | VOD\$1TIME\$1BASED\$1AVAIL\$1PLAN\$1WARNING\$1NO\$1ADVERTISEMENTS | The ADS request or response encountered a problem while creating a time-based avail plan for the VOD template. No ads will be inserted. | | WARNING\$1NO\$1ADVERTISEMENTS | MediaTailor encountered a problem while filling the avail. No ads are inserted. | | WARNING\$1URL\$1VARIABLE\$1SUBSTITUTION\$1FAILED | MediaTailor can't substitute dynamic variables in the ADS URL. Check the URL configuration. | | WARNING\$1VPAID\$1AD\$1DROPPED | A VPAID ad dropped due to a missing slate, or the session uses server-side reporting. | ## ADS log description This section describes the structure and contents of the ADS log description. To explore on your own in a JSON editor, use the listing at [ADS log JSON schema](#ads-log-json-schema). Each event in the ADS log contains the standard fields that are generated by CloudWatch Logs. For information, see [Analyze log data with CloudWatch Logs insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). ### ADS logs properties This section describes the properties of the ADS logs. | Property | Type | Required | Description | | --- | --- | --- | --- | | adsRequestUrl | string | false | The full URL of the ADS request made by MediaTailor. | | avail | object of type [avail](#ads-logs-avail) | false | Information about an avail that MediaTailor fills with ads. Currently, for the FILLED\$1AVAIL event type, this is the plan created by MediaTailor when it first encounters the avail. How the avail is eventually filled may vary from this plan, depending on how the content plays out. | | awsAccountId | string | true | The AWS account ID for the MediaTailor configuration that was used for the session. | | customerId | string | true | The hashed version of the AWS account ID, which you can use to correlate multiple log entries. | | eventDescription | string | true | A short description of the event that triggered this log message, provided by the MediaTailor service. By default, this is empty. Example: Got VAST response. | | eventTimestamp | string | true | The date and time of the event. | | eventType | string | true | The code for the event that triggered this log message. Example: VAST\$1RESPONSE. | | originId | string | true | The configuration name from the MediaTailor configuration. This is different from the video content source, which is also part of the configuration. | | prefetchScheduleName | string | false | The name of the prefetch schedule associated with this ad event. | | requestHeaders | array of type [requestheaders](#ads-logs-requestheaders) | false | The headers that MediaTailor included with the ADS request. Typically, the logs include these when a request to the ADS fails, to help with troubleshooting. | | requestId | string | true | The MediaTailor request ID, which you can use to correlate multiple log entries for the same request. | | sessionId | string | true | The unique numeric identifier that MediaTailor assigned to the player session. All requests that a player makes for a session have the same session ID. Example: e039fd39-09f0-46b2-aca9-9871cc116cde. | | sessionType | string (legal values: [DASH, HLS]) | true | The player's stream type. | | vastAd | object of type [vastAd](#ads-logs-vastAd) | false | Information about a single ad parsed from the VAST response. | | vastResponse | object of type [vastResponse](#ads-logs-vastResponse) | false | Information about the VAST response that MediaTailor received from the ADS. | | vodCreativeOffsets | object of type [vodCreativeOffsets](#ads-logs-vodCreativeOffsets) | false | A map that indicates the time offsets in the manifest where MediaTailor will insert avails, based on the VMAP response. | | vodVastResponseTimeOffset | number | false | The VMAP specific time offset for VOD ad insertion. | ### adContent This section describes the properties of the ADS logs adContent. **ADS Logs adContent Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | adPlaylistUris | object of type [adPlaylistUris](#ads-logs-adPlaylistUris) | false | The mapping from the origin manifest for a variant to the ad manifest for the variant. For DASH, this contains a single entry, because all variants are represented in a single DASH manifest. | ### adPlaylistUris This section describes the properties of the ADS logs adPlaylistUris. **ADS Logs adPlaylistUris Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | | string | false | The URL of the ad manifest for the specific variant. | ### avail This section describes the properties of the ADS logs avail. **ADS Logs avail Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | availId | string | true | The unique identifier for this avail. For HLS, this is the media sequence number where the avail begins. For DASH, this is the period ID. | | creativeAds | array of type [creativeAd](#ads-logs-creativeAd) | true | The ads that MediaTailor inserted into the avail. | | fillRate | number | true | The rate at which the ads fill the avail duration, from 0.0 (for 0%) to 1.0 (for 100%). | | filledDuration | number | true | The sum of the durations of all the ads inserted into the avail. | | numAds | number | true | The number of ads that MediaTailor inserted into the avail. | | originAvailDuration | number | true | The duration of the avail as specified in the content stream from the origin (CUE\$1OUT or SCTE). | | skippedAds | array of type [skippedAd](#ads-logs-skippedAd) | false | The ads that MediaTailor didn't insert, for reasons like TRANSCODE\$1IN\$1PROGRESS and TRANSCODE\$1ERROR. For a list of skipped ad reasons, see [Ad skipping troubleshooting](troubleshooting-ad-skipping-overview.md). | | slateAd | object of type [slateAd](#ads-logs-slateAd) | true | Information about the slate ad, which MediaTailor uses to fill any unfilled segments in the avail. | ### creativeAd This section describes the properties of the ADS logs creativeAd. **ADS Logs creativeAd Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | adContent | object of type [adContent](#ads-logs-adContent) | true | Information about the content of the inserted ad. | | creativeUniqueId | string | true | The unique identifier for the ad, used as a key for transcoding. This is the ID field for the creative in the VAST response, if available. Otherwise, it's the mezzanine URL of the ad. | | trackingEvents | object of type [trackingEvents](#ads-logs-trackingEvents) | true | The tracking beacon URLs for the various tracking events for the ad. The keys are the event names, and the values are a list of beacon URLs. | | transcodedAdDuration | number | true | The duration of the ad, calculated from the transcoded asset. | | uri | string | true | The URL of the mezzanine version of the ad, which is the input to the transcoder. | | vastDuration | number | true | The duration of the ad, as parsed from the VAST response. | ### requestheaders This section describes the properties of the ADS logs requestheaders. **ADS Logs requestheaders Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | name | string | true | The name of the header. | | value | string | true | The value of the header. | ### skippedAd This section describes the properties of the ADS logs skippedAd. **ADS Logs skippedAd Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | adMezzanineUrl | string | true | The mezzanine URL of the skipped ad. | | creativeUniqueId | string | true | The unique identifier for the ad, used as a key for transcoding. This is the ID field for the creative in the VAST response, if available. Otherwise, it's the mezzanine URL of the ad. | | skippedReason | string | true | The code that indicates why the ad wasn't inserted. Example: TRANSCODE\$1IN\$1PROGRESS. For a list of skipped ad reasons, see [Ad skipping troubleshooting](troubleshooting-ad-skipping-overview.md). | | transcodedAdDuration | number | false | The duration of the ad, calculated from the transcoded asset. | | vastDuration | number | true | The duration of the ad, as parsed from the VAST response. | ### slateAd This section describes the properties of the ADS logs slateAd. **ADS Logs slateAd Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | adContent | object of type [adContent](#ads-logs-adContent) | true | Information about the content of the inserted ad. | | creativeUniqueId | string | true | The unique identifier for the ad, used as a key for transcoding. This is the ID field for the creative in the VAST response, if available. Otherwise, it's the mezzanine URL of the ad. | | transcodedAdDuration | number | true | The duration of the ad, calculated from the transcoded asset. | | uri | string | true | The URL of the mezzanine version of the ad, which is the input to the transcoder. | ### trackingEvents This section describes the properties of the ADS logs trackingEvents. **ADS Logs trackingEvents Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | | array of type string | false | The list of beacon URLs for the specified tracking event (impression, complete, and so on) | ### vastAd This section describes the properties of the ADS logs vastAd. **ADS Logs vastAd Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | adSystem | string | true | The value of the AdSystem tag in the VAST response. | | adTitle | string | true | The media files that are available for the ad in the VAST response. | | creativeAdId | string | true | The value of the adId attribute of the Creative tag in the VAST response. | | creativeId | string | true | The value of the id attribute of the Creative tag in the VAST response. | | duration | number | true | The approximate duration of the ad, based on the duration tag in the linear element of the VAST response. | | trackingEvents | object of type [trackingEvents](#ads-logs-trackingEvents) | true | The tracking beacon URLs for the various tracking events for the ad. The keys are the event names, and the values are a list of beacon URLs. | | vastAdId | string | true | The value of the id attribute of the Ad tag in the VAST response | | vastAdTagUri | string | false | The VMAP-specific redirect URI for an ad. | | vastMediaFiles | array of type [vastMediaFile](#ads-logs-vastMediaFile) | true | The list of available media files for the ad in the VAST response. | ### vastMediaFile This section describes the properties of the ADS logs vastMediaFile. **ADS Logs vastMediaFile Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | apiFramework | string | true | The API framework needed to manage the media file. Example: VPAID. | | bitrate | number | true | The bitrate of the media file. | | delivery | string | true | The protocol used for the media file, set to either progressive or streaming. | | height | number | true | The pixel height of the media file. | | id | string | true | The value of the id attribute of the MediaFile tag. | | type | string | true | The MIME type of the media file, taken from the type attribute of the MediaFile tag. | | uri | string | true | The URL of the mezzanine version of the ad, which is the input to the transcoder. | | width | number | true | The pixel width of the media file. | ### vastResponse This section describes the properties of the ADS logs vastResponse. **ADS Logs vastResponse Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | errors | array of type string | true | The error URLs parsed from the Error tags in the VAST response. | | vastAds | array of type [vastAd](#ads-logs-vastAd) | true | The ads parsed from the VAST response. | | version | string | true | The VAST specification version, parsed from the version attribute of the VAST tag in the response. | ### vodCreativeOffsets This section describes the properties of the ADS logs vodCreativeOffsets. **ADS Logs vodCreativeOffsets Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | | array of type [vodCreativeOffset](#ads-logs-vodCreativeOffset) | false | A mapping from a time offset in the manifest to a list of ads to insert at this time. | ### vodCreativeOffset This section describes the properties of the ADS logs vodCreativeOffset. **ADS Logs vodCreativeOffset Properties** | Property | Type | Required | Description | | --- | --- | --- | --- | | adContent | object of type [adContent](#ads-logs-adContent) | true | Information about the content of the inserted ad. | | creativeUniqueId | string | true | The unique identifier for the ad, used as a key for transcoding. This is the ID field for the creative in the VAST response, if available. Otherwise, it's the mezzanine URL of the ad. | | trackingEvents | object of type [trackingEvents](#ads-logs-trackingEvents) | true | The tracking beacon URLs for the various tracking events for the ad. The keys are the event names, and the values are a list of beacon URLs. | | transcodedAdDuration | number | true | The duration of the ad, calculated from the transcoded asset. | | uri | string | true | The URL of the mezzanine version of the ad, which is the input to the transcoder. | | vastDuration | number | true | The duration of the ad, as parsed from the VAST response. | ## ADS log JSON schema The following lists the JSON schema for the AWS Elemental MediaTailor ADS log. ``` { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://amazon.com/elemental/midas/mms/adsLogSchema.json", "type": "object", "title": "AWS Elemental MediaTailor ADS Log JSON Schema", "required": [ "eventType", "eventTimestamp", "requestId", "sessionType", "eventDescription", "awsAccountId", "customerId", "originId", "sessionId" ], "additionalProperties": false, "properties": { "eventType": { "$id": "#/properties/eventType", "type": "string", "description": "The code for the event that triggered this log message. Example: VAST_RESPONSE.", "examples": [ "FILLED_AVAIL" ] }, "eventTimestamp": { "$id": "#/properties/eventTimestamp", "type": "string", "description": "The date and time of the event.", "examples": [ "1970-01-01T00:00:00Z" ], "format": "date-time" }, "requestId": { "$id": "#/properties/requestId", "type": "string", "description": "The MediaTailor request ID, which you can use to correlate multiple log entries for the same request.", "examples": [ "c7c7ae8c-a61e-44e0-8efd-7723995337a1" ], "pattern": "^(.*)$" }, "sessionType": { "$id": "#/properties/sessionType", "type": "string", "enum": [ "HLS", "DASH" ], "description": "The player's stream type." }, "eventDescription": { "$id": "#/properties/eventDescription", "type": "string", "description": "A short description of the event that triggered this log message, provided by the MediaTailor service. By default, this is empty. Example: Got VAST response.", "default": "", "examples": [ "Got VAST response" ], "pattern": "^(.*)$" }, "awsAccountId": { "$id": "#/properties/awsAccountId", "type": "string", "description": "The AWS account ID for the MediaTailor configuration that was used for the session." }, "customerId": { "$id": "#/properties/customerId", "type": "string", "description": "The hashed version of the AWS account ID, which you can use to correlate multiple log entries.", "pattern": "^(.*)$" }, "originId": { "$id": "#/properties/originId", "type": "string", "description": "The configuration name from the MediaTailor configuration. This is different from the video content source, which is also part of the configuration.", "examples": [ "external-canary-dash-serverside-reporting-onebox" ], "pattern": "^(.*)$" }, "sessionId": { "$id": "#/properties/sessionId", "type": "string", "description": "The unique numeric identifier that MediaTailor assigned to the player session. All requests that a player makes for a session have the same session ID. Example: e039fd39-09f0-46b2-aca9-9871cc116cde.", "examples": [ "120b9873-c007-40c8-b3db-0f1bd194970b" ], "pattern": "^(.*)$" }, "avail": { "$id": "#/properties/avail", "type": "object", "title": "avail", "description": "Information about an avail that MediaTailor fills with ads. Currently, for the FILLED_AVAIL event type, this is the plan created by MediaTailor when it first encounters the avail. How the avail is eventually filled may vary from this plan, depending on how the content plays out. ", "required": [ "creativeAds", "originAvailDuration", "filledDuration", "fillRate", "driftMillisecondsAtAvailStart", "numAds", "slateAd", "availId" ], "additionalProperties": false, "properties": { "originAvailDuration": { "$id": "#/properties/avail/originAvailDuration", "type": "number", "description": "The duration of the avail as specified in the content stream from the origin (CUE_OUT or SCTE)." }, "filledDuration": { "$id": "#/properties/avail/filledDuration", "type": "number", "description": "The sum of the durations of all the ads inserted into the avail." }, "fillRate": { "$id": "#/properties/avail/fillRate", "type": "number", "description": "The rate at which the ads fill the avail duration, from 0.0 (for 0%) to 1.0 (for 100%)." }, "driftMillisecondsAtAvailStart": { "$id": "#/properties/avail/driftMillisecondsAtAvailStart", "type": "number", "description": "The cumulative drift at the beginning of this avail. A positive value implies that we are moving away from the live edge, a negative value implies that we are moving towards the live edge." }, "creativeAds": { "$id": "#/properties/avail/creativeAds", "type": "array", "description": "The ads that MediaTailor inserted into the avail.", "items": { "type": "object", "title": "creativeAd", "description": "Information about a single inserted ad.", "required": [ "uri", "creativeUniqueId", "adSystem", "adContent", "trackingEvents", "vastDuration", "transcodedAdDuration" ], "additionalProperties": false, "properties": { "uri": { "$ref": "#/definitions/adMezzanineUri" }, "creativeUniqueId": { "$ref": "#/definitions/creativeUniqueId" }, "adSystem": { "$ref": "#/definitions/adSystem" }, "adContent": { "$ref": "#/definitions/adContent" }, "trackingEvents": { "$ref": "#/definitions/trackingEvents" }, "vastDuration": { "$ref": "#/definitions/vastDuration" }, "transcodedAdDuration": { "$ref": "#/definitions/transcodedAdDuration" } } } }, "numAds": { "$id": "#/properties/avail/numAds", "type": "number", "description": "The number of ads that MediaTailor inserted into the avail." }, "slateAd": { "$id": "#/properties/avail/slateAd", "type": ["object", "null"], "title": "slateAd", "description": "Information about the slate ad, which MediaTailor uses to fill any unfilled segments in the avail.", "additionalProperties": false, "required": [ "uri", "creativeUniqueId", "adContent", "transcodedAdDuration" ], "properties": { "uri": { "$ref": "#/definitions/adMezzanineUri" }, "creativeUniqueId": { "$ref": "#/definitions/creativeUniqueId" }, "adContent": { "$ref": "#/definitions/adContent" }, "transcodedAdDuration": { "$ref": "#/definitions/transcodedAdDuration" } } }, "availId": { "$id": "#/properties/avail/availId", "type": "string", "description": "The unique identifier for this avail. For HLS, this is the media sequence number where the avail begins. For DASH, this is the period ID." }, "skippedAds": { "$id": "#/properties/avail/skippedAds", "type": "array", "description": "The ads that MediaTailor didn't insert, for reasons like TRANSCODE_IN_PROGRESS and TRANSCODE_ERROR.", "items": { "type": "object", "title": "skippedAd", "description": "Information about a single skipped ad.", "required": [ "creativeUniqueId", "adMezzanineUrl", "skippedReason", "vastDuration" ], "additionalProperties": false, "properties": { "creativeUniqueId": { "$ref": "#/definitions/creativeUniqueId" }, "adMezzanineUrl": { "type": "string", "description": "The mezzanine URL of the skipped ad." }, "skippedReason": { "type": "string", "description": "The code that indicates why the ad wasn't inserted. Example: TRANSCODE_IN_PROGRESS." }, "vastDuration": { "$ref": "#/definitions/vastDuration" }, "transcodedAdDuration": { "$ref": "#/definitions/transcodedAdDuration" }, "targetVariant": { "type": "object", "title": "targetVariant", "description": "The target variant of the source content. This key is present when an ad wasn't inserted due to the source content containing a variant that could not match to any variants present in this ad.", "required": [ "mediaProtocol", "mediaType", "bitrate", "mediaResolution", "codecs" ], "additionalProperties": false, "properties": { "mediaProtocol": { "type": "string", "description": "The media protocol of this variant, such as HLS.", "enum": [ "HLS", "DASH" ] }, "mediaType": { "type": "array", "description": "The media type of this variant, such as VIDEO.", "items": { "type": "string", "enum": [ "VIDEO", "AUDIO", "SUBTITLES", "TRICK_PLAY" ], "description": "Media type, such as VIDEO." } }, "bitrate": { "$ref": "#/definitions/bitrate" }, "mediaResolution": { "type": "object", "title": "mediaResolution", "description": "The media resolution of this variant.", "required": [ "width", "height" ], "additionalProperties": false, "properties": { "width": { "$ref": "#/definitions/width" }, "height": { "$ref": "#/definitions/height" } } }, "codecs": { "type": "array", "description": "The codecs of this variant.", "items": { "type": "string", "description": "Codec, such as avc1." } } } } } } }, "adBreakTrackingEvents": { "$id": "#properties/avail/adBreakTrackingEvents", "type": "object", "title": "adBreakTrackingEvents", "description": "VMAP/ad break tracking events and corresponding URL", "properties": { "items": { "$ref": "#/definitions/adBreakTrackingEvents" } } } } }, "vastResponse": { "$id": "#/properties/vastResponse", "type": "object", "title": "vastResponse", "description": "Information about the VAST response that MediaTailor received from the ADS.", "required": [ "version", "vastAds", "errors", "nonLinearAdsList" ], "additionalProperties": false, "properties": { "version": { "$id": "#/properties/vastResponse/version", "type": "string", "description": "The VAST specification version, parsed from the version attribute of the VAST tag in the response.", "examples": [ "3.0" ], "pattern": "^(.*)$" }, "vastAds": { "$id": "#/properties/vastResponse/vastAds", "type": "array", "description": "The ads parsed from the VAST response.", "items": { "$ref": "#/definitions/vastAd" } }, "errors": { "$id": "#/properties/vastResponse/errors", "type": "array", "description": "The error URLs parsed from the Error tags in the VAST response.", "items": { "type": "string", "description": "A single error URL." } }, "nonLinearAdsList": { "$id": "#/properties/vastResponse/nonLinearAds", "type": "array", "description": "A list of NonLinearAds as they are read from the VAST response.", "items": { "$ref": "#/definitions/nonLinearAds" } } } }, "vastAd": { "$ref": "#/definitions/vastAd" }, "vodVastResponseTimeOffset": { "$id": "#/properties/vodVastResponseTimeOffset", "type": "number", "description": "The VMAP specific time offset for VOD ad insertion.", "examples": [ 5.0 ] }, "vodCreativeOffsets": { "$id": "#/properties/vodCreativeOffsets", "type": "object", "title": "vodCreativeOffsets", "description": "A map that indicates the time offsets in the manifest where MediaTailor will insert avails, based on the VMAP response.", "additionalProperties": { "type": "array", "$id": "#/properties/vodCreativeOffsets/entry", "description": "A mapping from a time offset in the manifest to a list of ads to insert at this time.", "items": { "type": "object", "$id": "#/properties/vodCreativeOffsets/entry/items", "title": "vodCreativeOffset", "description": "The list of ads to insert at the specified time offset.", "additionalProperties": false, "required": [ "uri", "creativeUniqueId", "vastDuration", "transcodedAdDuration", "adContent", "trackingEvents" ], "properties": { "uri": { "$ref": "#/definitions/adMezzanineUri" }, "creativeUniqueId": { "$ref": "#/definitions/creativeUniqueId" }, "vastDuration": { "$ref": "#/definitions/vastDuration" }, "transcodedAdDuration": { "$ref": "#/definitions/transcodedAdDuration" }, "adContent": { "$ref": "#/definitions/adContent" }, "trackingEvents": { "$ref": "#/definitions/trackingEvents" } } } } }, "adsRequestUrl": { "$id": "#/properties/adsRequestUrl", "type": "string", "description": "The full URL of the ADS request made by MediaTailor." }, "adMarkers": { "$id": "#/properties/adMarkers", "type": "string", "description": "Found Ad Marker in the Manifest." }, "segmentationUpid": { "$id": "#/properties/segmentationUpid", "type": "string", "description": "Value of segmentation upid parsed from ad markers in manifest." }, "segmentationTypeId": { "$id": "#/properties/segmentationTypeId", "type": "integer", "description": "Value of segmentation typeId parsed from ad markers in manifest." }, "requestHeaders": { "$id": "#/properties/requestHeaders", "type": "array", "description": "The headers that MediaTailor included with the ADS request. Typically, the logs include these when a request to the ADS fails, to help with troubleshooting.", "items": { "type": "object", "title": "requestheaders", "description": "The name and value for a single header included in the ADS request.", "required": [ "name", "value" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The name of the header." }, "value": { "type": "string", "description": "The value of the header." } } } }, "originalTargetUrl": { "$id": "#/properties/originalTargetUrl", "type": "string", "description": "The old URL to which MediaTailor was going to make a request." }, "prefetchScheduleName": { "$id": "#/properties/prefetchScheduleName", "type": "string", "description": "The name of the prefetch schedule associated with this ad event.", "examples": [ "PrefetchScheduleName" ], "pattern": "^(.*)$" }, "updatedTargetUrl": { "$id": "#/properties/updatedTargetUrl", "type": "string", "description": "The new URL to which MediaTailor is making a request." }, "rawAdsResponse": { "$id": "#/properties/rawAdsResponse", "type": "string", "description": "Paginated ADS response as it's exactly returned to MediaTailor." }, "rawAdsResponseIndex": { "$id": "#/properties/rawAdsResponseIndex", "type": "integer", "description": "Integer value denoting this rawAdsResponse's index into the full ADS response. This value is used to order the paginated messages for this ADS response." } }, "__COMMENT_oneOf": "The oneOf section defines subtypes for our events. Subtypes can have different rules, including which fields are required. For more information, see https://json-schema.org/understanding-json-schema/reference/combining.html#oneof ", "oneOf": [ { "$ref": "#/definitions/eventAdMarkersFound" }, { "$ref": "#/definitions/eventNonAdMarkerFound" }, { "$ref": "#/definitions/eventMakingAdsRequest" }, { "$ref": "#/definitions/eventModifiedTargetUrl" }, { "$ref": "#/definitions/eventRawAdsResponse" }, { "$ref": "#/definitions/eventVastResponse" }, { "$ref": "#/definitions/eventFilledAvail" }, { "$ref": "#/definitions/eventFilledOverlayAvail" }, { "$ref": "#/definitions/eventErrorFiringBeaconFailed" }, { "$ref": "#/definitions/eventWarningNoAdvertisements" }, { "$ref": "#/definitions/eventUnknownHost" }, { "$ref": "#/definitions/eventErrorAdsTimeout" }, { "$ref": "#/definitions/eventErrorVastMissingOverlays" }, { "$ref": "#/definitions/eventPlannedAvail" }, { "$ref": "#/definitions/eventEmptyVastResponse" }, { "$ref": "#/definitions/eventEmptyVmapResponse" }, { "$ref": "#/definitions/eventErrorUnknown" }, { "$ref": "#/definitions/eventVastRedirect" }, { "$ref": "#/definitions/eventRedirectedVastResponse" }, { "$ref": "#/definitions/eventErrorAdsMissingImpression" }, { "$ref": "#/definitions/eventErrorAdsResponseParse" }, { "$ref": "#/definitions/eventErrorAdsInvalidResponse" }, { "$ref": "#/definitions/eventErrorDisallowedHost"}, { "$ref": "#/definitions/eventPersonalizationDisabled"}, { "$ref": "#/definitions/eventWarningDynamicVariableSubFailed"}, { "$ref": "#/definitions/eventVodTimeBasedAvailPlanVastResponseForOffset" }, { "$ref": "#/definitions/eventVodTimeBasedAvailPlanSuccess" } ], "definitions": { "eventAdMarkersFound": { "$id": "#/definitions/eventAdMarkersFound", "required": [ "eventType", "adMarkers" ], "properties": { "eventType": { "type": "string", "const": "AD_MARKER_FOUND" } } }, "eventNonAdMarkerFound": { "$id": "#/definitions/eventNonAdMarkerFound", "required": [ "eventType", "adMarkers" ], "properties": { "eventType": { "type": "string", "const": "NON_AD_MARKER_FOUND" } } }, "eventMakingAdsRequest": { "$id": "#/definitions/eventMakingAdsRequest", "required": [ "eventType", "adsRequestUrl" ], "properties": { "eventType": { "type": "string", "const": "MAKING_ADS_REQUEST" } } }, "eventModifiedTargetUrl": { "$id": "#/definitions/eventModifiedTargetUrl", "required": [ "eventType", "originalTargetUrl", "updatedTargetUrl" ], "properties": { "eventType": { "type": "string", "const": "MODIFIED_TARGET_URL" } } }, "eventRawAdsResponse": { "$id": "#/definitions/eventRawAdsResponse", "required": [ "eventType", "rawAdsResponse", "rawAdsResponseIndex" ], "properties": { "eventType": { "type": "string", "const": "RAW_ADS_RESPONSE" } } }, "eventVastResponse": { "$id": "#/definitions/eventVastResponse", "_comment": "NOTE: the vastResponse property should ideally be marked as a required field for this event, but unfortunately, in the case of an empty vast response, we currently emit an EMPTY_VAST_RESPONSE followed by a VAST_RESPONSE, and the vastResponse property is not present in the latter. We need to fix this so that we don't emit both of those events in the empty response case, and update this schema to flag vastResponse as required for VAST_RESPONSE.", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "VAST_RESPONSE" } } }, "eventFilledAvail": { "$id": "#/definitions/eventFilledAvail", "required": [ "eventType", "avail" ], "properties": { "eventType": { "type": "string", "const": "FILLED_AVAIL" } } }, "eventFilledOverlayAvail": { "$id": "#/definitions/eventFilledOverlayAvail", "required": [ "eventType", "avail" ], "properties": { "eventType": { "type": "string", "const": "FILLED_OVERLAY_AVAIL" } } }, "eventErrorVastMissingOverlays": { "$id": "#/definitions/eventErrorVastMissingOverlays", "required": [ "eventType", "adsRequestUrl", "requestHeaders" ], "properties": { "eventType": { "type": "string", "const": "ERROR_VAST_MISSING_OVERLAYS" } } }, "eventErrorFiringBeaconFailed": { "$id": "#/definitions/eventErrorFiringBeaconFailed", "required": [ "eventType", "error", "beaconInfo" ], "properties": { "eventType": { "type": "string", "const": "ERROR_FIRING_BEACON_FAILED" } } }, "eventWarningNoAdvertisements": { "$id": "#/definitions/eventWarningNoAdvertisements", "required": [ "eventType" ], "_comment": "We should really have a more descriptive error field for these events", "properties": { "eventType": { "type": "string", "const": "WARNING_NO_ADVERTISEMENTS" } } }, "eventUnknownHost": { "$id": "#/definitions/eventUnknownHost", "required": [ "eventType", "requestHeaders" ], "properties": { "eventType": { "type": "string", "const": "ERROR_UNKNOWN_HOST" } } }, "eventErrorAdsTimeout": { "$id": "#/definitions/eventErrorAdsTimeout", "required": [ "eventType", "adsRequestUrl", "requestHeaders" ], "properties": { "eventType": { "type": "string", "const": "ERROR_ADS_TIMEOUT" } } }, "eventPlannedAvail": { "$id": "#/definitions/eventPlannedAvail", "required": [ "eventType" ], "_comment": "TODO: Flesh this out as we implement it", "properties": { "eventType": { "type": "string", "const": "PLANNED_AVAIL" } } }, "eventEmptyVastResponse": { "$id": "#/definitions/eventEmptyVastResponse", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "EMPTY_VAST_RESPONSE" } } }, "eventEmptyVmapResponse": { "$id": "#/definitions/eventEmptyVmapResponse", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "EMPTY_VMAP_RESPONSE" } } }, "eventErrorUnknown": { "$id": "#/definitions/eventErrorUnknown", "required": [ "eventType" ], "_comment": "TODO: we should have a field for the exception message or something", "properties": { "eventType": { "type": "string", "const": "ERROR_UNKNOWN" } } }, "eventVastRedirect": { "$id": "#/definitions/eventVastRedirect", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "VAST_REDIRECT" } } }, "eventRedirectedVastResponse": { "$id": "#/definitions/eventRedirectedVastResponse", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "REDIRECTED_VAST_RESPONSE" } }, "_comment": "NOTE that the property vastResponse is not required because empty vast responses do not contain a vastResponse." }, "eventErrorAdsResponseParse": { "$id": "#/definitions/eventErrorAdsResponseParse", "required": [ "eventType" ], "_comment": "We should have a field with an error message here", "properties": { "eventType": { "type": "string", "const": "ERROR_ADS_RESPONSE_PARSE" } } }, "eventErrorAdsInvalidResponse": { "$id": "#/definitions/eventErrorAdsInvalidResponse", "required": [ "eventType", "additionalInfo" ], "properties": { "eventType": { "type": "string", "const": "ERROR_ADS_INVALID_RESPONSE" } } }, "eventErrorAdsMissingImpression": { "$id": "#/definitions/eventErrorAdsMissingImpression", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "ERROR_VAST_MISSING_IMPRESSION" } } }, "eventErrorDisallowedHost": { "$id": "#/definitions/eventErrorDisallowedHost", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "ERROR_DISALLOWED_HOST" } } }, "eventPersonalizationDisabled": { "$id": "#/definitions/eventPersonalizationDisabled", "required": [ "eventType" ], "properties": { "eventType": { "type": "string", "const": "ERROR_PERSONALIZATION_DISABLED" } } }, "eventWarningDynamicVariableSubFailed": { "$id": "#/definitions/eventWarningDynamicVariableSubFailed", "required": [ "eventType", "adsRequestUrl" ], "properties": { "eventType": { "type": "string", "const": "WARNING_URL_VARIABLE_SUBSTITUTION_FAILED" } } }, "eventVodTimeBasedAvailPlanVastResponseForOffset": { "$id": "#/definitions/eventVodTimeBasedAvailPlanVastResponseForOffset", "required": [ "eventType", "vastResponse" ], "properties": { "eventType": { "type": "string", "const": "VOD_TIME_BASED_AVAIL_PLAN_VAST_RESPONSE_FOR_OFFSET" } } }, "eventVodTimeBasedAvailPlanSuccess": { "$id": "#/definitions/eventVodTimeBasedAvailPlanSuccess", "required": [ "eventType", "vodCreativeOffsets" ], "properties": { "eventType": { "type": "string", "const": "VOD_TIME_BASED_AVAIL_PLAN_SUCCESS" } } }, "creativeUniqueId": { "type": "string", "description": "The unique identifier for the ad, used as a key for transcoding. This is the ID field for the creative in the VAST response, if available. Otherwise, it's the mezzanine URL of the ad. " }, "adSystem": { "type": "string", "description": "The value of the AdSystem tag in the VAST response. " }, "vastDuration": { "type": "number", "description": "The duration of the ad, as parsed from the VAST response." }, "transcodedAdDuration": { "type": "number", "description": "The duration of the ad, calculated from the transcoded asset." }, "adContent": { "$id": "#/properties/adContent", "type": ["object", "null"], "title": "adContent", "description": "Information about the content of the inserted ad.", "additionalProperties": false, "properties": { "adPlaylistUris": { "$id": "#/properties/adContent/adPlaylistUris", "type": "object", "title": "adPlaylistUris", "description": "The mapping from the origin manifest for a variant to the ad manifest for the variant. For DASH, this contains a single entry, because all variants are represented in a single DASH manifest. ", "additionalProperties": { "$id": "#/properties/adContent/adPlaylistUris/adPlaylistUri", "type": "string", "description": "The URL of the ad manifest for the specific variant." } } } }, "adMezzanineUri": { "type": "string", "description": "The URL of the mezzanine version of the ad, which is the input to the transcoder." }, "bitrate": { "type": "integer", "examples": [ 533 ], "description": "The bitrate." }, "width": { "type": "integer", "examples": [ 1280 ], "description": "Width in pixels." }, "height": { "type": "integer", "examples": [ 720 ], "description": "Height in pixels." }, "trackingEvents": { "type": "object", "title": "trackingEvents", "description": "The tracking beacon URLs for the various tracking events for the ad. The keys are the event names, and the values are a list of beacon URLs.", "additionalProperties": { "type": "array", "description": "The list of beacon URLs for the specified tracking event (impression, complete, and so on)", "items": { "type": "string", "description": "The beacon URLs for this tracking event." } } }, "nonLinearAds": { "$id": "#/properties/nonLinearAds", "type": "object", "title": "nonLinearAds", "description": "A NonLinearAds as it appears in the VAST response.", "required": [ "nonLinearAdList", "nonLinearTrackingEvents" ], "properties": { "nonLinearAdList": { "type": "array", "description": "List of non linear ads as they exist within one NonLinearAds.", "items": { "type": "object", "title": "nonLinearAdList", "description": "List of NonLinearAd as they are parsed from its parent NonLinearAds.", "properties": { "nonLinearAdId": { "type": "string", "description": "Ad ID of this non linear ad." }, "nonLinearAdSystem": { "type": "string", "description": "Ad system of this non linear ad's parent Inline ad." }, "nonLinearAdTitle": { "type": "string", "description": "Ad title of this non linear ad's parent Inline ad." }, "nonLinearCreativeId": { "type": "string", "description": "Creative ID of this non linear ad's parent Creative ad." }, "nonLinearCreativeAdId": { "type": "string", "description": "Creative ad ID of this non linear ad." }, "nonLinearCreativeSequence": { "type": "string", "description": "Creative sequence of this non linear ad." }, "nonLinearWidth": { "type": "string", "description": "Width of this non linear ad." }, "nonLinearHeight": { "type": "string", "description": "Height of this non linear ad." }, "nonLinearExpandedWidth": { "type": "string", "description": "Expanded width of this non linear ad." }, "nonLinearExpandedHeight": { "type": "string", "description": "Expanded height of this non linear ad." }, "nonLinearScalable": { "type": "boolean", "description": "Boolean denoting if this non linear ad is scalable." }, "nonLinearMaintainAspectRatio": { "type": "boolean", "description": "Boolean denoting if aspect ratio should be maintained for this non linear ad." }, "nonLinearMinSuggestedDuration": { "type": "string", "description": "Min suggested duration for this non linear ad." }, "nonLinearApiFramework": { "type": "string", "description": "API framework for this non linear ad's parent Inline ad." }, "nonLinearStaticResource": { "type": "string", "description": "Static resource for this non linear ad." }, "nonLinearStaticResourceCreativeType": { "type": "string", "description": "Static Resource creative type for this non linear ad." }, "nonLinearIFrameResource": { "type": "string", "description": "I-Frame resource for this non linear ad." }, "nonLinearHtmlResource": { "type": "string", "description": "HTML resource for this non linear ad." }, "nonLinearAdParameters": { "type": "string", "description": "Ad parameters for this non linear ad." }, "nonLinearClickThrough": { "type": "string", "description": "Click Through data for this non linear ad." }, "nonLinearClickTracking": { "type": "string", "description": "Click Tracking data for this non linear ad." }, "nonLinearClickTrackingId": { "type": "string", "description": "Click Tracking ID for this non linear ad." } } } }, "nonLinearTrackingEvents": { "$ref": "#/definitions/trackingEvents" }, "extensions": { "$id": "#/properties/nonLinearAds/extensions", "type": "array", "description": "Extensions that exist for this NonLinearAds.", "items": { "$id": "#/properties/nonLinearAds/extensions/items", "type": "object", "title": "Extensions", "description": "Extensions found in non linear ads", "additionalProperties": false, "properties": { "extensionType": { "$id": "#/properties/nonLinearAds/extensions/extensionType", "type": "string", "description": "The value of the extension type attribute of the Extensions tag.", "examples": [ "FreeWheel" ] }, "extensionContent": { "$id": "#/properties/nonLinearAds/extensions/extensionContent", "type": "string", "description": "The extension content attribute of the Extensions tag.", "examples": [ "progressive" ] } } } } } }, "adBreakTrackingEvents": { "$id": "#/properites/adBreakTrackingEvents", "type": "object", "title": "adBreakTrackingEvents", "description": "These are all VMAP ad break tracking events.", "additionalProperties": { "type": "array", "description": "VMAP/ad break tracking events and corresponding URL", "items": { "type": "string", "description": "The beacon URLs for this tracking event." } } }, "vastAd": { "$id": "#/properties/vastAd", "type": "object", "title": "vastAd", "description": "Information about a single ad parsed from the VAST response.", "required": [ "vastAdId", "adSystem", "adTitle", "creativeId", "creativeAdId", "duration", "vastMediaFiles", "trackingEvents" ], "additionalProperties": false, "properties": { "vastAdId": { "$id": "#/properties/vastAd/vastAdId", "type": "string", "description": "The value of the id attribute of the Ad tag in the VAST response", "examples": [ "ad1" ] }, "adSystem": {"$ref": "#/definitions/adSystem" } , "adTitle": { "$id": "#/properties/vastAd/adTitle", "type": "string", "description": "The media files that are available for the ad in the VAST response.", "examples": [ "External NCA1C1L1 LinearInlineSkippable" ] }, "creativeId": { "$id": "#/properties/vastAd/creativeId", "type": "string", "description": "The value of the id attribute of the Creative tag in the VAST response.", "examples": [ "creative1" ] }, "creativeAdId": { "$id": "#/properties/vastAd/creativeAdId", "type": "string", "description": "The value of the adId attribute of the Creative tag in the VAST response." }, "duration": { "$id": "#/properties/vastAd/duration", "type": "number", "description": "The approximate duration of the ad, based on the duration tag in the linear element of the VAST response.", "examples": [ 30, 30.0 ] }, "vastMediaFiles": { "$id": "#/properties/vastAd/vastMediaFiles", "type": "array", "description": "The list of available media files for the ad in the VAST response.", "items": { "$id": "#/properties/vastAd/vastMediaFiles/items", "type": "object", "title": "vastMediaFile", "description": "Information about a media file for the ad.", "required": [ "uri", "id", "delivery", "type", "apiFramework", "width", "height", "bitrate" ], "additionalProperties": false, "properties": { "uri": { "$ref": "#/definitions/adMezzanineUri" }, "id": { "$id": "#/properties/vastAd/vastMediaFiles/items/properties/id", "type": "string", "description": "The value of the id attribute of the MediaFile tag.", "examples": [ "GDFP" ] }, "delivery": { "$id": "#/properties/vastAd/vastMediaFiles/items/properties/delivery", "type": "string", "description": "The protocol used for the media file, set to either progressive or streaming.", "examples": [ "progressive" ] }, "type": { "$id": "#/properties/vastAd/vastMediaFiles/items/properties/type", "type": "string", "description": "The MIME type of the media file, taken from the type attribute of the MediaFile tag.", "examples": [ "video/mp4" ] }, "apiFramework": { "$id": "#/properties/vastAd/vastMediaFiles/items/properties/apiFramework", "type": "string", "description": "The API framework needed to manage the media file. Example: VPAID." }, "width": { "$ref": "#/definitions/width" }, "height": { "$ref": "#/definitions/height" }, "bitrate": { "$ref": "#/definitions/bitrate" } } } }, "trackingEvents": { "$ref": "#/definitions/trackingEvents" }, "vastAdTagUri": { "$id": "#/properties/vastAd/vastAdTagUri", "type": "string", "description": "The VMAP-specific redirect URI for an ad.", "examples": [ "https://ads.redirect.com/redirect1" ] } } } } } ``` # AWS Elemental MediaTailor manifest logs description and event types The following sections describe the logs that MediaTailor emits to describe events with the origin server when requesting and receiving a manifest. These are `ManifestService` logs. **Topics** + [ ## ManifestService events ](#log-types-origininteraction) + [ ## Manifest logs properties ](#manifest-logs-main) ## ManifestService events The following events are emitted during MediaTailor interactions with the origin. | Log | Description | | --- | --- | | CONFIG\$1SECURITY\$1ERROR | The MediaTailor configuration has a security issue. | | CONFIG\$1SYNTAX\$1ERROR | The origin and asset path result in a malformed URL. | | CONNECTION\$1ERROR | The MediaTailor connection to the origin was refused or failed. | | GENERATED\$1MANIFEST | MediaTailor generated a manifest. You must have debug mode enabled to receive these logs. For information about debug log mode, including how to enable it, see [Generating debug logs](debug-log-mode.md). | | HOST\$1DISALLOWED | MediaTailor does not allow HTTP requests to this host. | | INCOMPATIBLE\$1HLS\$1VERSION | The manifest uses an incompatible HLS version. MediaTailor requires version 3 or greater. | | INVALID\$1SINGLE\$1PERIOD\$1DASH\$1MANIFEST | The single-period DASH manifest is invalid. MediaTailor is passing through single-period DASH manifest. | | IO\$1ERROR | MediaTailor encountered an IO error during communication with the origin. | | LAST\$1PERIOD\$1MISSING\$1AUDIO | The last period in the DASH manifest is missing all audio AdaptationSets because of origin audio or video misalignment. To avoid playback issues, delay publishing the last period until at least the next request. | | LAST\$1PERIOD\$1MISSING\$1AUDIO\$1WARNING | The last period in the DASH manifest is missing all audio AdaptationSets because of origin audio or video misalignment. Choosing to publish (not delay) the last period. Missing audio might cause playback issues. | | MANIFEST\$1ERROR | The MediaTailor manifest request failed. | | NO\$1MASTER\$1OR\$1MEDIA\$1PLAYLIST | The origin response doesn't contain a primary playlist or media playlist. | | NO\$1MASTER\$1PLAYLIST | The origin response doesn't contain the expected primary playlist. | | NO\$1MEDIA\$1PLAYLIST | The origin response doesn't contain the expected media playlist. | | ORIGIN\$1MANIFEST | MediaTailor fetched an origin manifest. You must have debug mode enabled to receive these logs. For information about debug log mode, including how to enable it, see [Generating debug logs](debug-log-mode.md). | | PARSING\$1ERROR | The origin is unable to parse the manifest request. | | SCTE35\$1PARSING\$1ERROR | MediaTailor is unable to parse Signal Binary element in the manifest. | | SESSION\$1INITIALIZED | A session was initialized. You must have debug mode enabled to receive these logs. For information about debug log mode, including how to enable it, see [Generating debug logs](debug-log-mode.md). | | TIMEOUT\$1ERROR | The MediaTailor manifest request timed out. | | TRACKING\$1RESPONSE | MediaTailor served a tracking response. You must have debug mode enabled to receive these logs. For information about debug log mode, including how to enable it, see [Generating debug logs](debug-log-mode.md). | | UNKNOWN\$1ERROR | MediaTailor encountered an unknown error. | | UNKNOWN\$1HOST | The host is unknown. | | UNSUPPORTED\$1SINGLE\$1PERIOD\$1DASH\$1MANIFEST | The single-period DASH manifest is unsupported. MediaTailor is passing through single-period DASH manifest. | ## Manifest logs properties This section describes the properties of the manifest logs. | Property | Type | Required | | --- | --- | --- | | awsAccountId | string | true | | eventTimestamp | string | true | | originId | string | true | | customerId | string | false | | eventType | string | false | | sessionId | string | false | | originRequestUrl | string | false | | mediaTailorPath | string | false | | requestId | string | false | | responseBody | string | false | | sessionType | string (legal values: [DASH, HLS]) | false | | requestNextToken | string | false | | eventDescription | string | false | | assetPath | string | false | | originFullUrl | string | false | | originPrefixUrl | string | false | | additionalInfo | string | false | | cause | string | false | | response | string | false | | httpCode | string | false | | errorMessage | string | false | | adAdsResponse | string | false | | adAdsRawResponse | string | false | | adAdsRequest | string | false | | adNumNewAvails | string | false | | generatedMediaPlaylist | string | false | | requestStartTime | string | false | | requestEndTime | string | false | | requestStartTimeEpochMillis | string | false | | requestEndTimeEpochMillis | string | false | # AWS Elemental MediaTailor transcode logs description and event types The following sections describe the logs that MediaTailor emits to describe events with the transcode service when preparing creatives for ad stitching. These are `TranscodeService` logs. **Topics** + [ ## TranscodeService events ](#log-types-tminteraction) + [ ## Transcode logs properties ](#transcode-logs-main) ## TranscodeService events The following events are emitted during MediaTailor interactions while transcoding ads. | Log | Description | | --- | --- | | IMPORT\$1ERROR | MediaTailor encountered an internal error during an import job (for preconditioned ads). Using an empty set of ads. | | INITIALIZED | MediaTailor initialized either a transcode job or an import job (for preconditioned ads). | | INTERNAL\$1ERROR | MediaTailor encountered an internal error. Using an empty set of ads. | | MISSING\$1VARIANTS | MediaTailor could not transcode the ad because of missing variants. Using an empty set of ads. | | PROFILE\$1NOT\$1FOUND | MediaTailor could not transcode the ad because of a missing profile to transcode. Using an empty set of ads. | | TRANSCODE\$1COMPLETED | Video transcoding is complete. The ad can be used for ad insertion. | | TRANSCODE\$1ERROR | MediaTailor encountered an internal error during a transcode job. Using an empty set of ads. | | TRANSCODE\$1IN\$1PROGRESS | Video transcoding is in progress. The transcoded video is not ready. Using an empty set of ads. | ## Transcode logs properties This section describes the properties of the transcode logs. | Property | Type | Required | Description | | --- | --- | --- | --- | | awsAccountId | string | true | The AWS account ID for the MediaTailor configuration that was used for the session. | | eventTimestamp | string | true | The date and time of the event. | | originId | string | true | The configuration name from the MediaTailor configuration. This is different from the video content source, which is also part of the configuration. | | eventType | string | false | The code for the event that triggered this log message. Example: TRANSCODE\$1ERROR. | | eventDescription | string | false | A short description of the event that triggered this log message, provided by the MediaTailor service. By default, this is empty. | | sessionId | string | false | The unique numeric identifier that MediaTailor assigned to the player session. All requests that a player makes for a session have the same session ID. Example: e039fd39-09f0-46b2-aca9-9871cc116cde. | | creativeUniqueId | string | false | The unique identifier for the ad creative that's being transcoded. | | profileName | string | false | | | adUri | string | false | The URI for the ad creative. | | transcodeRequestId | string | false | The unique identifier for this transcode request. | | cacheStatus | string | false | Indicates if MediaTailor cached the transcoded ad. | # Using vended logs to send AWS Elemental MediaTailor logs You can use vended logs for greater flexibility and control over where to deliver logs that MediaTailor emits from your playback configuration. With vended logs, MediaTailor sends all log activity associated with a configuration to Amazon CloudWatch Logs. CloudWatch Logs then sends the percent of logs that you specify to your chosen destination. Supported destinations are an Amazon CloudWatch Logs log group, Amazon S3 bucket, or Amazon Data Firehose stream. Because vended logs are available at volume discount pricing, you could see cost savings compared to sending logs directly to CloudWatch Logs. For pricing, see *Vended Logs* on the **Logs** tab at [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing/). To use vended logs, you must do the following: 1. [Add permissions](#vended-logs-perms). 1. [Create log delivery destinations](#vended-logs-destinations). 1. [Configure log delivery in CloudWatch Logs](#vended-logs-delivery). 1. [Enable vended logs in MediaTailor](#vended-logs-config). For more information about vended logs, see [Enable logging from AWS services](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html) in the CloudWatch Logs user guide. MediaTailor supports V2 of vended logs. ## Step 1: Add permissions for MediaTailor log delivery The person who's setting up vended logs must have permissions to create the delivery destination, configure log delivery, and enable vended logs in MediaTailor. Use the following policies to ensure that you have the appropriate permissions to set up vended logs. **Policies for CloudWatch Logs and delivery destinations** The following sections in the *Amazon CloudWatch Logs User Guide* provide the policies that enable you to work with logs in CloudWatch Logs and your delivery destinations. If you send logs to multiple locations, you can combine the policy statements into one policy instead of creating multiple policies. + [Logs sent to CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-logs-infrastructure-V2-CloudWatchLogs) + [Logs sent to Amazon S3](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-logs-infrastructure-V2-S3) + [Logs sent to Firehose](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-logs-infrastructure-V2-Firehose) **Policy for set up from the console** If you're setting up vended logs delivery through the console instead of the API or AWS CLI, you must have the following additional permissions in your policy. **Policy for vended logs in MediaTailor** To create, view, or modify vended logs delivery in MediaTailor, you must have the following permissions in your policy. For information about adding permissions and working with policies, see [Identity and Access Management for AWS Elemental MediaTailor](security-iam.md). ## Step 2: Create delivery destinations for MediaTailor logs Create the resources where your logs will be sent. Record the ARN of the resource for use in configuring the log delivery in a later step. **CloudWatch Logs log group delivery destination** Use one of the following for help creating a log group. + For the console, see [Create a log group in CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#Create-Log-Group) in the *Amazon CloudWatch Logs User Guide*. + For the API, see [CreateLogGroup](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogGroup.html) in the *Amazon CloudWatch Logs API Reference.* + For SDKs and CLI, see [Use `CreateLogGroup` with an AWS SDK or AWS CLI](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/example_cloudwatch-logs_CreateLogGroup_section.html) in the *Amazon CloudWatch Logs User Guide*. **Amazon S3 bucket delivery destination** Use one of the following for help creating a bucket. + For the console, SDKs, and CLI, see [Create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) in the *Amazon Simple Storage Service User Guide*. + For the API, see [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) in the *Amazon Simple Storage Service API Reference*. **Firehose stream delivery destination** For help creating a stream, see [Create a Firehose stream from console](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html) in the *Amazon Data Firehose Developer Guide*. ## Step 3: Enable vended logs for the MediaTailor playback configuration Create or update the playback configuration that will be sending logs to the delivery destination that you created in the previous step. Record the name of the configuration for use in configuring the log delivery in a later step. + To enable vended logs through the console, using [Creating a configuration](configurations-create.md) or [Editing configuration settings](configurations-edit.md) Editing a configuration to access the **Logging** settings. For **Logging strategies**, choose **Vended logs**. + To enable vended logs through the API, you must have an existing configuration. Use `ConfigureLogsForPlaybackConfiguration` to add the logging strategy `Vended logs`. If you're using the legacy MediaTailor logging strategy of sending logs directly to CloudWatch Logs and want to migrate to vended logs, see [Migrating the logging strategy](vended-logs-migrate.md). **Important** If you change the log strategy from Legacy CloudWatch to vended logs, MediaTailor will make this change as soon as you save the updates. You will stop receiving logs until you have fully configured vended logging. ## Step 4: Configure log delivery in CloudWatch Logs In CloudWatch Logs, you must create three elements to represent the pieces of log delivery. These elements are described in detail in [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html) in the *Amazon CloudWatch Logs API Reference*. The high-level steps to configure the delivery with the CloudWatch Logs API are as follows. **To configure log delivery in CloudWatch Logs (API)** 1. Use [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html) to add the source of logs. A `DeliverySource` represents the playback configuration that's generating the logs. You need the name of the playback configuration to create the `DeliverySource`. 1. Use [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html) to add the destination where logs will be written. A `DeliveryDestination` represents the delivery destination. You need the ARN of the log group, bucket, or stream to create the `DeliveryDestination`. 1. Use [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestinationPolicy.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestinationPolicy.html) if you are delivering logs across accounts. If the delivery destination is in a different account from the playback configuration, you need a `DeliveryDestinationPolicy`. This policy allows CloudWatch Logs to deliver logs to the `DeliveryDestination`. 1. Use [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html) to link the `DeliverySource` to the `DeliveryDestination`. A `Delivery` represents the connection between the `DeliverySource` and `DeliveryDestination`. # Migrating your AWS Elemental MediaTailor logging strategy If you change the log strategy from Legacy CloudWatch to vended logs, MediaTailor will make this change as soon as you save the updates. To avoid interruptions in your logging workflow, use the following steps to migrate your logging strategy. 1. Follow the steps as described in [Using vended logs](vended-logs.md). For [Enable vended logs in MediaTailor](vended-logs.md#vended-logs-config), select *both* logging strategies (**Vended logs** and **Legacy CloudWatch**). MediaTailor will send logs through both vended logs and directly to CloudWatch Logs. 1. Make the necessary changes in your workflow that are dependent on your logging strategy and delivery destination. 1. Revisit [Enable vended logs in MediaTailor](vended-logs.md#vended-logs-config) and remove **Legacy CloudWatch** from the **Logging strategies**. # Writing AWS Elemental MediaTailor logs directly to Amazon CloudWatch Logs MediaTailor produces logs that contain detailed information about session activity and ad decision server interactions, and writes them to Amazon CloudWatch. The logs provide a sequential description of activity that occurs during the session. MediaTailor can also use vended logs for flexibility in log delivery and volume discount pricing. For information about vended logs, see [Using vended logs](vended-logs.md). **Topics** + [ # Permissions for Amazon CloudWatch Logs ](monitoring-permissions.md) + [ # "As Run" log for AWS Elemental MediaTailor Channel Assembly ](as-run-log.md) + [ # AWS Elemental MediaTailor ADS log analysis in Amazon CloudWatch Logs Insights ](monitor-cloudwatch-ads-logs.md) # Permissions for Amazon CloudWatch Logs Use AWS Identity and Access Management (IAM) to create a role that gives AWS Elemental MediaTailor access to Amazon CloudWatch. You must perform these steps for CloudWatch Logs to be published for your account. CloudWatch automatically publishes metrics for your account. **To allow MediaTailor access to CloudWatch** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane of the IAM console, choose **Roles**, and then choose **Create role**. 1. Choose the **Another AWS account** role type. 1. For **Account ID**, enter your AWS account ID. 1. Select **Require external ID** and enter **Midas**. This option automatically adds a condition to the trust policy that allows the service to assume the role only if the request includes the correct `sts:ExternalId`. 1. Choose **Next: Permissions**. 1. Add a permissions policy that specifies what actions this role can complete. Select from one of the following options, and then choose **Next: Review**: + **CloudWatchLogsFullAccess** to provide full access to Amazon CloudWatch Logs + **CloudWatchFullAccess** to provide full access to Amazon CloudWatch 1. For **Role name**, enter **MediaTailorLogger**, and then choose **Create role**. 1. On the **Roles** page, choose the role that you just created. 1. To update the principal, edit the trust relationship: 1. On the role's **Summary** page, choose the **Trust relationship** tab. 1. Choose **Edit trust relationship**. 1. In the policy document, change the principal to the MediaTailor service. It should look like this: ``` "Principal": { "Service": "mediatailor.amazonaws.com" }, ``` The entire policy should read as follows: 1. Choose **Update Trust Policy**. # "As Run" log for AWS Elemental MediaTailor Channel Assembly The *As Run* log, in the CloudWatch `MediaTailor/Channel/AsRunLog` log group, shows information about programs and ad breaks as they play. When you create a channel, the As Run log is disabled by default. Using the Console or the AWS Command Line Interface (AWS CLI), you can enable and disable the As Run log state for each channel in your account. When you enable the As Run log, MediaTailor automatically creates a service-linked role that allows MediaTailor to write and manage the As Run log in your CloudWatch Logs account. For more information about service-linked roles, see [Using service-linked roles for MediaTailor](using-service-linked-roles.md). **Note** The As Run Log currently only supports the default program. For now it doesn't support the alternateMedia created by program rules. This means that it currently does not generate the As Run Log for alternateMedia. **Topics** + [ # Enabling the As Run log ](enabling-as-run-log.md) + [ # Disabling the As Run log ](disabling-as-run-log.md) # Enabling the As Run log To enable the As Run log, specify the channel name and enable the *As Run* log type for that channel. ------ #### [ Console ] **To enable the As Run log when creating a channel** 1. Sign in to the AWS Management Console and open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. In the navigation pane, choose **Channel assembly** > **Channels**. 1. On the navigation bar, choose **Create channel**. 1. In the **Set channel details**, **Configure outputs**, and **Access control** panes, configure your channel as desired. 1. In the **Access control** pane, choose **Next**. 1. In the **Logging** pane, under **Log types**, select **Enable as run** to enable the As Run log. **To enable the As Run log when updating a channel** **Note** If the channel is currently running, you must first stop that channel before you can update it. After you stop the channel, you can choose **Actions** > **Edit** to begin updating the channel. 1. Sign in to the AWS Management Console and open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. In the navigation pane, choose **Channel assembly** > **Channels**. 1. Choose the channel that you want to update to enable the As Run log for. 1. Choose **Actions** > **Edit**. 1. In the **Set channel details**, **Configure outputs**, and **Access control** panes, update your channel configuration as desired. 1. In the **Access control** pane, choose **Next**. 1. In the **Logging** pane, under **Log types**, select **Enable as run** to enable the As Run log. **To enable the As Run log from the **Logging** tab** **Note** If the channel is currently running, you must use the **Logging** tab instead of choosing **Actions** > **Edit** to enable the As Run log. 1. Sign in to the AWS Management Console and open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. In the navigation pane, choose **Channel assembly** > **Channels**. 1. Choose the channel that you want to enable the As Run log for. 1. In the navigation bar under the channel's name, choose **Logging**. 1. Under **Logging** > **Log types**, select **As run** to enable the As Run log. ------ #### [ AWS Command Line Interface (AWS CLI) ] **To enable the As Run log** Run the [configure-logs-for-channel](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/configure-logs-for-channel.html) command and specify the appropriate values for the required parameters. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability. ``` $ aws mediatailor configure-logs-for-channel \ --channel-name MyChannel \ --log-types AS_RUN ``` This example is formatted for Microsoft Windows, and it uses the caret (^) line-continuation character to improve readability. ``` C:\> aws mediatailor configure-logs-for-channel ^ --channel-name MyChannel ^ --log-types AS_RUN ``` Where: + `MyChannel` is the name of the channel that you own and want to enable the As Run log for. If the command runs successfully, you receive output similar to the following. ``` { "ChannelName": "MyChannel", "LogTypes": [ "AS_RUN" ] } ``` ------ # Disabling the As Run log To disable the As Run log for a channel that has it enabled, specify the channel name and disable the *As Run* log type for that channel. ------ #### [ Console ] **To disable the As Run log when updating a channel** **Note** If the channel is currently running, you must first stop that channel before you can update it. After you stop the channel, you can choose **Actions** > **Edit** to begin updating the channel. 1. Sign in to the AWS Management Console and open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. In the navigation pane, choose **Channel assembly** > **Channels**. 1. Choose the channel that you want to update to enable the As Run log for. 1. Choose **Actions** > **Edit**. 1. In the **Set channel details**, **Configure outputs**, and **Access control** panes, update your channel configuration as desired. 1. In the **Access control** pane, choose **Next**. 1. In the **Logging** pane, under **Log types**, clear **Enable as run** to disable the As Run log. **To disable the As Run log from the **Logging** tab** **Note** If the channel is currently running, you must use the **Logging** tab instead of choosing **Actions** > **Edit** to disable the As Run log. 1. Sign in to the AWS Management Console and open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. In the navigation pane, choose **Channel assembly** > **Channels**. 1. Choose the channel that you want to disable the As Run log for. 1. In the navigation bar under the channel's name, choose **Logging**. 1. Under **Logging** > **Log types**, clear **As run** to disable the As Run log. ------ #### [ AWS Command Line Interface (AWS CLI) ] **To disable the As Run log** Run the [configure-logs-for-channel](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/configure-logs-for-channel.html) command and specify the appropriate values for the required parameters. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability. ``` $ aws mediatailor configure-logs-for-channel \ --channel-name MyChannel \ --log-types ``` This example is formatted for Microsoft Windows, and it uses the caret (^) line-continuation character to improve readability. ``` C:\> aws mediatailor configure-logs-for-channel ^ --channel-name MyChannel ^ --log-types ``` Where: + `MyChannel` is the name of the channel that you own and want to disable the As Run log for. If the command runs successfully, you receive output similar to the following. ``` { "ChannelName": "MyChannel", "LogTypes": [] } ``` ------ # AWS Elemental MediaTailor ADS log analysis in Amazon CloudWatch Logs Insights You can view and query AWS Elemental MediaTailor ad decision server (ADS) logs using Amazon CloudWatch Logs Insights. MediaTailor sends event logs to CloudWatch for normal processing and error conditions. The logs adhere to a JSON schema. Through CloudWatch Logs Insights, you can select logs by time frame, and then run queries against them. For general information, see [Analyze log data with CloudWatch Logs insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). **Note** To access the logs, you need permissions to access Amazon CloudWatch. For instructions, see [Permissions for Amazon CloudWatch Logs](monitoring-permissions.md). **To view and query ADS logs using the CloudWatch console** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, under **Logs**, choose **Insights**. 1. In the search bar, enter **AdDec**, and then from the drop-down list, select `MediaTailor/AdDecisionServerInteractions`. 1. (Optional) Adjust the time period that you want to study. 1. (Optional) Change the query in the dialog box. For general guidance, see [CloudWatch Logs insights query syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html). For examples of queries for MediaTailor ADS, see [Querying the ADS logs](querying-the-ads-logs.md). 1. Choose **Run query**. The query might take a few seconds, during which time **Cancel** appears in place of **Run query**. 1. (Optional) To export the results as a CSV file, choose **Actions**, and then choose **Download query results (CSV)**. **Note** The console limits the number of records that it returns in query results and that it exports, so for bulk data, use the API, the AWS Command Line Interface (AWS CLI), or an SDK. **Topics** + [ # Querying the ADS logs ](querying-the-ads-logs.md) # Querying the ADS logs CloudWatch Logs Insights provides a rich set of options for querying your logs. For detailed information about querying syntax, see [CloudWatch Logs insights query syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html). This section provides examples of common queries to get you started with your ADS logs queries. All queries run against the logs for the current time range setting. The following query retrieves all information from the ADS logs. ``` fields @timestamp, eventType, sessionId, requestId, @message | sort sessionId, @timestamp asc ``` The following query retrieves all requests to the ADS. This query shows a way to retrieve the request header contents for MediaTailor logs. ``` fields @timestamp, adsRequestUrl, requestHeaders.0.value as @userAgent, requestHeaders.1.value as @xForwardedFor, sessionId, requestId | filter eventType = "MAKING_ADS_REQUEST" | sort @timestamp asc ``` The following query retrieves the ads MediaTailor inserted for a given session. ``` fields @timestamp, sessionId, requestId, @message | filter eventType = "FILLED_AVAIL" | sort @timestamp asc ``` The following query retrieves the tracking URLs that MediaTailor called on behalf of the player. ``` fields @timestamp, beaconInfo.trackingEvent, beaconInfo.beaconUri, beaconInfo.headers.0.value as @userAgent, beaconInfo.headers.1.value as @xForwardedFor, sessionId, requestId | filter eventType = "BEACON_FIRED" | sort @timestamp asc ``` The following query retrieves information for a specific playback session, by filtering the results by `sessionId`. ``` fields @timestamp, eventType, sessionId, requestId, @message | filter sessionId = "0aaf6507-c6f9-4884-bfe7-f2f841cb8195" | sort @timestamp asc ``` The following query retrieves information for a single request, by filtering the results by `requestId`. ``` fields @timestamp, eventType, sessionId, requestId, @message | filter requestId = "f5d3cf39-6258-4cf1-b3f6-a34ff8bf641d" | sort @timestamp asc ``` The following query retrieves a count of log entries for each event type that was logged. ``` fields eventType | stats count() as @eventCount by eventType ``` The following query retrieves the avail ID and list of skipped ads for all avails that had skipped ads. ``` fields avail.availId | parse @message '"skippedAds":[*]' as @skippedAdsList | filter ispresent(@skippedAdsList) ``` # Controlling the volume of AWS Elemental MediaTailor logs MediaTailor ad insertion session logs are sometimes verbose. To reduce log costs, you can define the percentage of session logs that MediaTailor sends to Amazon CloudWatch Logs. For example, if your playback configuration has 1000 ad insertion sessions and you set a percentage enabled value of `60`, MediaTailor sends logs for 600 of the sessions to CloudWatch Logs. MediaTailor decides at random which of the sessions to send logs for. If you want to view logs for a specific session, you can use the [debug log mode](debug-log-mode.md). When you set a logging percentage, MediaTailor automatically creates a service-linked role that grants MediaTailor the permissions it requires to write CloudWatch Logs to your account. For information about how MediaTailor uses service-linked roles, see [Using service-linked roles for MediaTailor](using-service-linked-roles.md). ## Creating a log configuration To control the percentage of session logs that MediaTailor writes to CloudWatch Logs, you create a *log configuration* for your playback configuration. When you create a log configuration, you specify a *playback configuration name*, and a *percent enabled* value. ------ #### [ Console ] **To create a log configuration for an *existing* playback configuration** 1. Sign in to the AWS Management Console and open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. On the **Playback configuration** pane, select the playback configuration that you'd like to set the log configuration for. 1. Choose **Edit**. 1. Under **Log configuration**, specify a **percent enabled** value. **To create a log configuration for a *new* playback configuration** + Follow the procedure in [Log configuration](configurations-create.md#configurations-log-configurations). ------ #### [ AWS Command Line Interface (AWS CLI) ] **To create a log configuration for an *existing* playback configuration** To create a log configuration by using the AWS CLI, run the [configure-logs-for-playback-configuration](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/configure-logs-for-playback-configuration.html) command and specify the appropriate values for the required parameters. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability. ``` $ aws mediatailor configure-logs-for-playback-configuration \ --percent-enabled 10 \ --playback-configuration-name MyPlaybackConfiguration ``` This example is formatted for Microsoft Windows, and it uses the caret (^) line-continuation character to improve readability. ``` C:\> aws mediatailor configure-logs-for-playback-configuration ^ --percent-enabled 10 ^ --playback-configuration-name MyPlaybackConfiguration ``` Where: + `percent-enabled` is the percentage of playback configuration session logs that MediaTailor sends to CloudWatch Logs. + `playback-configuration-name` is the name of the playback configuration to set the log configuration settings for. If the command runs successfully, you receive output similar to the following. ``` { "PercentEnabled": 10, "PlaybackConfigurationName": "MyPlaybackConfiguration" } ``` **To create a log configuration for a *new* playback configuration** + Use the `configure-logs-for-playback-configuration` option for the [put-playback-configuration](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/put-playback-configuration.html) command. ------ ## Deactivating a log configuration After you create a log configuration, you can't delete it—you can only *deactivate* it. To deactivate the log configuration, set the **percent enabled** value to **0** with the MediaTailor console or API. This turns off all session logging for that playback configuration. If you want to delete the service-linked role that MediaTailor uses for the log configuration(s) in your account, you must first deactivate all of your log configurations. For information about how to delete the service-linked role, see [Using service-linked roles for MediaTailor](using-service-linked-roles.md). ------ #### [ Console ] **To deactivate log configuration on a playback configuration** 1. Sign in to the AWS Management Console and open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. On the **Playback configuration** pane, select the playback configuration that you'd like to deactivate log configuration on. 1. Choose **Edit**. 1. Under **Log configuration**, set the **percent enabled** value to `0`. This turns off all session logging for this playback configuration. 1. Select **Save**. ------ #### [ AWS Command Line Interface (AWS CLI) ] **To deactivate a log configuration** + Set the `percent-enabled` value to `0` using the [configure-logs-for-playback-configuration](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/configure-logs-for-playback-configuration.html) command. ------ # Filtering AWS Elemental MediaTailor logs and events Logs emitted from a playback configuration in MediaTailor include information about a variety of activities that happen during the playback session. These activities are identified in the event type of the logs. Many events are logged by default. To help control the cost of logs in Amazon CloudWatch, you can specify the logs that MediaTailor emits. MediaTailor provides you control over log filtering so you can do the following: + Specify the log events that you want to exclude from logs + Enable logging raw responses from the ad decision server (ADS) You can set these log filtering preferences independently for each playback session, or as a default for all playback sessions for a playback configuration. + To filter logs on a per-session basis, include query parameters in the playback session initialization request. + To filter logs on a per-playback configuration basis, use the MediaTailor console or API to indicate your preferences in the playback configuration settings. The following sections provide instruction for enabling log filtering on sessions and playback configurations. # Per-session log filters To define a customized level of log detail for each session, append the following parameters to your initial server-side or client-side playback session request. Add values to the parameters to represent the events that you want to include or exclude, in a comma-delimited format: + `aws.adsInteractionLogPublishOptInEventTypes` to receive logs for specific ad decision server (ADS) interactions. + `aws.adsInteractionLogExcludeEventTypes` to stop receiving logs for specific ADS interactions. + `aws.manifestServiceLogExcludeEventTypes` to stop receiving logs for specific manifest service interactions. For a list of log and event types that MediaTailor emits, see [Manifest logs](log-types.md), [ADS logs](ads-log-format.md), and [Transcode logs](tm-log-format.md). If you don't pass through any query parameters for log filtering, MediaTailor writes all logs to your delivery destination. **Example server-side session initialization with log filters** To exclude `GENERATED_MANIFEST` and `PARSING_ERROR` events from your manifest logs and `MAKING_ADS_REQUEST` from the ADS logs, the session initialization request would look like this: ``` GET /v1/master///index.m3u8?aws.logMode=DEBUG&aws.manifestServiceLogExcludeEventTypes=GENERATED_MANIFEST,PARSING_ERROR&aws.adsInteractionLogExcludeEventTypes=MAKING_ADS_REQUEST ``` To enable raw logs from your ADS, include the `RAW_ADS_RESPONSE` value for the `AdsInteractionPublishOptInEventType` parameter: ``` GET /v1/master///index.m3u8?aws.adsInteractionPublishOptInEventType=RAW_ADS_RESPONSE ``` **Example client-side session initialization with log filters** To exclude log events during client-side session initialization, include `availSuppression` and log-type parameters in your client's POST request to MediaTailor. For more information about how to construct a client-side playback session request, see [Client-side ad tracking](ad-reporting-client-side.md). The following example excludes `CONFIG_SECURITY_ERROR` and `PARSING_ERROR` events from your manifest logs and `MAKING_ADS_REQUEST` from the ADS logs. ``` POST parent.m3u8 { "adsInteractionLog": { ... "excludeEventTypes": [ "MAKING_ADS_REQUEST" ] }, "manifestServiceLog": { ... "excludeEventTypes": [ "GENERATED_MANIFEST", "PARSING_ERROR" ] }, "logMode": "DEBUG" } ``` To enable raw logs from your ADS, include the `RAW_ADS_RESPONSE `value for the `publishOptInEventTypes` parameter: ``` POST parent.m3u8 { "adsInteractionLog": { "publishOptInEventTypes": ["RAW_ADS_RESPONSE"], "excludeEventTypes": [ "MAKING_ADS_REQUEST" ] }, "manifestServiceLog": { ... "excludeEventTypes": [ "GENERATED_MANIFEST", "PARSING_ERROR" ] }, "logMode": "DEBUG" } ``` # Per-playback configuration log filters Use the playback configuration's settings to define the log event types that MediaTailor emits as a default from this playback configuration. MediaTailor uses these default log filtering settings for all sessions that don't include filtering query parameters on the session init request. You can choose to do the following: + Receive logs for specific ad decision server (ADS) interactions. + Exclude logs for specific ADS interactions. + Exclude logs for specific manifest service interactions. To set these settings from the MediaTailor console, see [Creating a configuration](configurations-create.md). For the MediaTailor API, see [https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PutPlaybackConfiguration.html](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PutPlaybackConfiguration.html) in the *AWS Elemental MediaTailor API Reference*. For a list of log and event types that MediaTailor emits, see [Manifest logs](log-types.md), [ADS logs](ads-log-format.md), and [Transcode logs](tm-log-format.md). # Generating AWS Elemental MediaTailor debug logs Use debug logs to troubleshoot MediaTailor ad insertion playback session issues. To generate debug logs, set the log mode to debug in the player's request to MediaTailor. For server-side reporting, set the log mode in the *playback request*. For client-side reporting, set the log mode in the *session initialization request*. When the log mode is set to debug, MediaTailor writes all log event types to CloudWatch Logs. The logs provide information about the following events. For a complete list of the data produced in the debug logs, see [Debug log fields](https://docs.aws.amazon.com/mediatailor/latest/ug/debug-log-mode.html#debug-log-mode-fields). + **Origin interaction** – Details about MediaTailor interactions with the origin server. For example, the origin manifest response, manifest type, and origin URL. + **Generated manifest** – Details about the playback session response from MediaTailor. For example, the manifest that MediaTailor generates. + **Session initialized** – Session initialization details, such as the session ID. To customize the log event types that you receive on a per-session basis, see [Filtering logs and events](logs-filter.md). ## Prerequisites To set the log mode to debug, first you need to grant MediaTailor permission to send logs to CloudWatch, if you haven't already. Once you've granted permission for MediaTailor to access CloudWatch, then you're ready to enable the debug log mode. For information about how to grant MediaTailor permission to access CloudWatch see [Setting Up Permissions for Amazon CloudWatch](https://docs.aws.amazon.com/mediatailor/latest/ug/monitoring-permissions.html). ## How to set the log mode to debug This section explains how to set the log mode to debug for server-side reporting and client-side reporting. ### Server-side reporting For server-side reporting, include the `?aws.logMode=DEBUG` query parameter and value in your player's `GET HTTP` playback request to the HLS or DASH MediaTailor endpoint. For general information about server-side reporting see [Server-side Reporting](https://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-server-side.html). **Important** The `DEBUG` value is case-sensitive. A playback request that includes `?aws.logMode=DEBUG` looks like the following: **Example Playback request to an HLS endpoint** ``` GET /v1/master///?aws.logMode=DEBUG ``` After you set the log mode to debug, we recommend that you verify that the debug logging session is active. To verify that the debug session is active, check to see if there are any CloudWatch logs for the session ID. The session ID is included in the playback endpoint that MediaTailor provides. For more information, see [Verify that the debug log mode is active for your playback session](#debug-active). ### Client-side reporting For client-side reporting, include the `logMode` key and `DEBUG` value in your client's `POST HTTP` session initialization request body to the MediaTailor /v1/session endpoint. For general information about client-side reporting see [Client-Side Reporting](https://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side.html). **Important** The `DEBUG` value is case-sensitive. After you set the log mode to debug, we recommend that you verify that the debug session is active. To verify that the debug session is active, confirm that there's a `SESSION_INITIALIZED` event associated with the session ID in the CloudWatch logs. The session ID is included in the playback endpoint that MediaTailor provides. For more information, see [Verify that the debug log mode is active for your playback session](#debug-active). ## Maximum active debug sessions You can have a maximum of 10 active debug log sessions. When your player sends its session initialization or playback request to MediaTailor, MediaTailor checks to see if the limit has been reached. If it has, MediaTailor checks to see if there are any stale sessions. A session is stale if it hasn't been accessed within a certain period of time. For live streams this time period is 10 minutes, for VOD streams it's 30 minutes. If the maximum active debug log sessions limit has been reached, debug logs aren't written to CloudWatch Logs for your session. If you don't see debug logs in CloudWatch Logs for your session, you could have reached this limit. To confirm if the limit has been reached, see [Verify that the debug log mode is active for your playback session](#debug-active). ## Debug log fields The following table lists the debug log fields that MediaTailor writes to CloudWatch. | Field | Description | | --- | --- | | awsAccountId | Your AWS account ID. | | customerId | Your MediaTailor customer ID. | | eventTimestamp | The ISO 8601 timestamp associated with the debug log event. | | eventType | The type of debug log event. Values:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/debug-log-mode.html) | | originRequestUrl | The URL of your origin server that is retrieved for this request. | | mediaTailorPath | The MediaTailor endpoint that was called, including any parameters passed to MediaTailor in the initial manifest request. | | requestId | The ID of a specific HTTP request to MediaTailor. | | responseBody | The manifest in the response body from MediaTailor. This is either the raw origin manifest or the manifest generated by MediaTailor. | | sessionId | The playback session ID. | | sessionType | The type of playback session. Values: `HLS`, `DASH` | ## Read the debug logs MediaTailor writes the debug logs to Amazon CloudWatch Logs. Typical CloudWatch Logs charges apply. Use CloudWatch Insights to read the debug logs. For information on how to use CloudWatch Logs Insights, see [Analyzing Log Data with CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) in the *AWS CloudWatch Logs User Guide*. **Note** The debug logs can take a few minutes to appear in CloudWatch. If you don't see the logs, wait a few minutes and try again. If you still don't see the logs, it could be that you've reached the maximum number of active debug log sessions. To verify if this is the case, run a CloudWatch query to see if there was a debug session initialized for your playback session. For more information, see [Verify that the debug log mode is active for your playback session](#debug-active). ### Examples This section includes example queries that you can use to read MediaTailor debug log data. **Example 1: Verify that the debug log mode is active for your playback session** ``` fields @timestamp, @message | filter sessionId = "32002de2-837c-4e3e-9660-f3075e8dfd90" | filter eventType = "SESSION_INITIALIZED" # client-side reporting or mediaTailorPath like “/v1/master" # server-side reporting HLS or mediaTailorPath like “/v1/dash" # server-side reporting DASH ``` **Example 2: View the responses from your origin** ``` fields @timestamp, responseBody, @message, mediaTailorPath | filter eventType = "ORIGIN_MANIFEST" and sessionId = "32002de2-837c-4e3e-9660-f3075e8dfd90" ``` **Example 3: View the manifest generated by MediaTailor for a given session** ``` fields @timestamp, responseBody, @message | filter mediaTailorPath like "/v1/master/" and eventType = "GENERATED_MANIFEST" and sessionId = "32002de2-837c-4e3e-9660-f3075e8dfd90" ``` **Example 4: View all events for a given `requestId`** Use this query to view the origin manifest and the manifest generated by MediaTailor. ``` fields @timestamp, responseBody, @message, mediaTailorPath | filter requestId = "e5ba82a5-f8ac-4efb-88a0-55bed21c45b4" ``` # Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics You can monitor AWS Elemental MediaTailor metrics using CloudWatch. CloudWatch collects raw data about the performance of the service and processes that data into readable, near real-time metrics. These statistics are kept for 15 months, so that you can access historical information and gain a better perspective on how your web application or service is performing. You can also set alarms that watch for certain thresholds, and send notifications or take actions when those thresholds are met. For more information, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). Metrics can be useful when you investigate stale manifests. For more information, see [Using metrics to diagnose stale manifests](stale-manifest-diagnose.md). Metrics are grouped first by the service namespace, and then by the various dimension combinations within each namespace. **To view metrics using the CloudWatch console** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, choose **Metrics**. 1. Under **All metrics**, choose the **MediaTailor** namespace. 1. Select the metric dimension to view the metrics (for example, **originID**). 1. Specify the time period that you want to view. **To view metrics using the AWS Command Line Interface (AWS CLI)** + At a command prompt, use the following command: ``` aws cloudwatch list-metrics --namespace "AWS/MediaTailor" ``` ## AWS Elemental MediaTailor CloudWatch metrics The AWS Elemental MediaTailor namespace includes the following metrics. These metrics are published by default to your account. ### Channel Assembly (CA) metrics In the following table, all metrics are available by channel or by channel output. | Metric | Description | | --- | --- | | 4xxErrorCount | The number of `4xx` errors. | | 5xxErrorCount | The number of `5xx` errors. | | RequestCount | The total number of requests. The transaction count depends largely on how often players request updated manifests, and the number of players. Each player request counts as a transaction. | | TotalTime | The amount of time that the application server took to process the request, including the time used to receive bytes from and write bytes to the client and network. | #### Server-side Ad-insertion (SSAI) metrics The following table lists server-side ad-insertion metrics. | Metric | Description | | --- | --- | | AdDecisionServer.Ads | The count of ads included in ad decision server (ADS) responses within the CloudWatch time period that you specified. | | AdDecisionServer.Duration | The total duration, in milliseconds, of all ads that MediaTailor received from the ADS within the CloudWatch time period that you specified. This duration can be greater than the `Avail.Duration` that you specified. | | AdDecisionServer.Errors | The number of non-HTTP 200 status code responses, empty responses, and timed-out responses that MediaTailor received from the ADS within the CloudWatch time period that you specified. | | AdDecisionServer.FillRate | The simple average of the rates at which the responses from the ADS filled the corresponding individual ad avails for the time period that you specified. To get the weighted average, calculate the `AdDecisionServer.Duration` as a percentage of the `Avail.Duration`. For more information about simple and weighted averages, see [Simple and weighted averages](#metrics-simple-average). | | AdDecisionServer.Latency | The response time in milliseconds for requests made by MediaTailor to the ADS. | | AdDecisionServer.Timeouts | The number of timed-out requests to the ADS in the CloudWatch time period that you specified. | | AdNotReady | The number of times that the ADS pointed at an ad that wasn't yet transcoded by the internal transcoder service in the time period that you specified. A high value for this metric might contribute to a low overall `Avail.FillRate`. | | AdsBilled | The number of ads for which MediaTailor bills customers based on insertion. | | Avail.Duration | The planned total number of milliseconds of ad avails within the CloudWatch time period. The planned total is based on the ad avail durations in the origin manifest. | | Avail.FilledDuration | The planned number of milliseconds of ad avail time that MediaTailor will fill with ads within the CloudWatch time period. | | Avail.FillRate | The planned simple average of the rates at which MediaTailor will fill individual ad avails within the CloudWatch time period. To get the weighted average, calculate the `Avail.FilledDuration` as a percentage of the `Avail.Duration`. For more information about simple and weighted averages, see [Simple and weighted averages](#metrics-simple-average). The maximum `Avail.FillRate` that MediaTailor can attain is bounded by the `AdDecisionServer.FillRate`. If the `Avail.FillRate` is low, compare it to the `AdDecisionServer.FillRate`. If the `AdDecisionServer.FillRate` is low, your ADS might not be returning enough ads for the avail durations. | | Avail.Impression | The number of ads with impression tracking events that MediaTailor sees during server-side beaconing (not the number of impressions). | | Avail.ObservedDuration | The observed total number of milliseconds of ad avails that occurred within the CloudWatch time period. `Avail.ObservedDuration` is emitted at the end of the ad avail, and is based on the duration of the segments reported in the manifest during the ad avail. | | Avail.ObservedFilledDuration | The observed number of milliseconds of ad avail time that MediaTailor filled with ads within the CloudWatch time period. | | Avail.ObservedFillRate | The observed simple average of the rates at which MediaTailor filled individual ad avails within the CloudWatch time period. Emitted only for HLS manifests, at the first `CUE-IN` tag. If there is no `CUE-IN` tag, MediaTailor doesn't emit this metric. | | Avail.ObservedSlateDuration | The observed total number of milliseconds of slate that was inserted within the CloudWatch period. | | GetManifest.Age | The total age of the manifest in milliseconds. Measured from when the origin creates the manifest, to when MediaTailor sends the personalized manifest. For more information about metrics for measuring manifest age, see [Using metrics to diagnose stale manifests](stale-manifest-diagnose.md). | | GetManifest.Errors | The number of errors received while MediaTailor was generating manifests in the CloudWatch time period that you specified. | | GetManifest.Latency | The MediaTailor response time in milliseconds for the request to generate manifests. For more information about metrics for measuring manifest age, see [Using metrics to diagnose stale manifests](stale-manifest-diagnose.md). | | GetManifest.MediaTailorAge | The amount of time that the manifest has been stored in MediaTailor in milliseconds. Measured from when MediaTailor receives an origin response, to when MediaTailor sends the personalized manifest. For more information about metrics for measuring manifest age, see [Using metrics to diagnose stale manifests](stale-manifest-diagnose.md). | | Origin.Age | The amount of time that the origin has the manifest in milliseconds. Measured from when the origin creates the manifest, to when MediaTailor sends the origin request. All `origin.*` metrics are emitted for requests that are fulfilled directly from the origin. They are not emitted for cached origin responses. For more information about metrics for measuring manifest age, see [Using metrics to diagnose stale manifests](stale-manifest-diagnose.md). | | Origin.Errors | The number of non-HTTP 200 status code responses and timed-out responses that MediaTailor received from the origin server in the CloudWatch time period that you specified. All `origin.*` metrics are emitted for requests that are fulfilled directly from the origin. They are not emitted for cached origin responses. | | Origin.ManifestFileSizeBytes | The file size of the origin manifest in bytes for both HLS and DASH. Typically this metric is used in conjunction with `Origin.ManifestFileSizeTooLarge`. All `origin.*` metrics are emitted for requests that are fulfilled directly from the origin. They are not emitted for cached origin responses. | | Origin.ManifestFileSizeTooLarge | The number of responses from the origin that have a manifest size larger than the configured amount. Typically this metric is used in conjunction with `Origin.ManifestFileSizeBytes`. All `origin.*` metrics are emitted for requests that are fulfilled directly from the origin. They are not emitted for cached origin responses. | | Origin.Timeouts | The number of timed-out requests to the origin server in the CloudWatch time period that you specified. All `origin.*` metrics are emitted for requests that are fulfilled directly from the origin. They are not emitted for cached origin responses. | | Requests | The number of concurrent transactions per second across all request types. The transaction count depends mainly on the number of players and how often the players request updated manifests. Each player request counts as a transaction. | | SkippedReason.DurationExceeded | The number of ads that were not inserted into an avail because the ADS returned a duration of ads that was greater than the specified avail duration. A high value for this metric might contribute to a discrepancy between the `Avail.Ads` and `AdDecisionServer.Ads` metric. For more information about ad skipped reasons, see [Ad skipping troubleshooting](troubleshooting-ad-skipping-overview.md). | | SkippedReason.EarlyCueIn | The number of ads skipped due to an early `CUE-IN`. | | SkippedReason.ImportError | The number of ads skipped due to an error in the import job. | | SkippedReason.ImportInProgress | The number of ads skipped due to an existing active import job. | | SkippedReason.InternalError | The number of ads skipped due to a MediaTailor internal error. | | SkippedReason.NewCreative | The number of ads that were not inserted into an avail because it was the first time the asset had been requested by a client. A high value for this metric might temporarily contribute to a low overall `Avail.FillRate`, until assets can be successfully transcoded. | | SkippedReason.NoVariantMatch | The number of ads skipped due to there being no variant match between the ad and content. | | SkippedReason.PersonalizationThresholdExceeded | The duration of ads exceeding the **Personalization Threshold** setting in this configuration. | | SkippedReason.ProfileNotFound | The number of ads skipped due to the transcoding profile not being found. | | SkippedReason.TranscodeError | The number of ads skipped due to a transcode error. | | SkippedReason.TranscodeInProgress | The count of the number of ads that were not inserted into an avail because the ad had not yet been transcoded. A high value for this metric might temporarily contribute to a low overall `Avail.FillRate`, until the assets can be successfully transcoded. | | GetAssets.Requests | The number of Asset List requests received for HLS Interstitials sessions within the CloudWatch time period. Use this metric to monitor late-binding ad decisioning volume and understand the scale of HLS Interstitials usage. | | GetAssets.Latency | The response time for Asset List requests in milliseconds for HLS Interstitials sessions. Monitor this metric to ensure optimal ad decisioning performance and identify potential bottlenecks in the late-binding workflow. | **Note** For HLS Interstitials sessions, some metrics behave differently due to the late-binding nature of ad decisioning: `Avail.ObservedFilledDuration` matches `Avail.FilledDuration` since MediaTailor cannot observe actual client-side playback behavior. `Avail.ObservedSlateDuration` reports planned slate duration from Asset List responses rather than observed playback. Metrics prefixed with "Observed" provide estimated values for HLS Interstitials sessions. ### Simple and weighted averages You can retrieve the simple average and the weighted average for the responses from the ADS to ad requests from MediaTailor and for how MediaTailor fills ad avails: + The *simple averages* are provided in the `AdDecisionServer.FillRate` and the `Avail.FillRate`. These are the averages of the fill rate percentages for the individual avails for the time period. The simple averages don't take into account any differences between the durations of the individual avails. + The *weighted averages* are the fill rate percentages for the sum of all avail durations. These are calculated as (`AdDecisionServer.Duration`\$1100)/`Avail.Duration` and (`Avail.FilledDuration`\$1100)/`Avail.Duration`. These averages reflect the differences in duration of each ad avail, giving more weight to those with longer duration. For a time period that contains just a single ad avail, the simple average provided by the `AdDecisionServer.FillRate` is equal to the weighted average provided by (`AdDecisionServer.Duration`\$1100)/`Avail.Duration`. The simple average provided by the `Avail.FillRate` is equal to the weighted average provided by (`Avail.FilledDuration`\$1100)/`Avail.Duration`. **Example** Assume the time period that you specified has the following two ad avails: + The first ad avail has 90 seconds duration: + The ADS response for the avail provides 45 seconds of ads (50% filled). + MediaTailor fills 45 seconds worth of the ad time available (50% filled). + The second ad avail has 120 seconds duration: + The ADS response for the avail provides 120 seconds of ads (100% filled). + MediaTailor fills 90 seconds worth of the ad time available (75% filled). The metrics are as follows: + `Avail.Duration` is 210, the sum of the two ad avail durations: 90 \$1 120. + `AdDecisionServer.Duration` is 165, the sum of the two response durations: 45 \$1 120. + `Avail.FilledDuration` is 135, the sum of the two filled durations: 45 \$1 90. + `AdDecisionServer.FillRate` is 75%, the average of the percentages filled for each avail: (50% \$1 100%) / 2. This is the simple average. + The weighted average for the ADS fill rates is 78.57%, which is `AdDecisionServer.Duration` as a percentage of the `Avail.Duration`: (165\$1100) / 210. This calculation accounts for the differences in the durations. + `Avail.FillRate` is 62.5%, the average of the filled percentages for each avail: (50% \$1 75%) / 2. This is the simple average. + The weighted average for the MediaTailor avail fill rates is 64.29%, which is the `Avail.FilledDuration` as a percentage of the `Avail.Duration`: (135\$1100) / 210. This calculation accounts for the differences in the durations. The highest `Avail.FillRate` that MediaTailor can attain for any ad avail is 100%. The ADS might return more ad time than is available in the avail, but MediaTailor can only fill the time available. ## AWS Elemental MediaTailor CloudWatch dimensions You can filter the AWS Elemental MediaTailor data using the following dimension. | Dimension | Description | | --- | --- | | `Configuration Name` | Indicates the configuration that the metric belongs to. | # Using metrics to diagnose stale manifests from AWS Elemental MediaTailor A stale manifest is one that hasn't been recently updated. Different ad insertion workflows could have varying tolerance to how long must pass before a manifest is considered stale, based on a variety of factors (such as requirements for downstream systems). You can use Amazon CloudWatch metrics to identify manifests that exceed the staleness tolerance for your workflow, and help identify what could be causing the delays in manifest updates. The following metrics help identify stale manifests and their causes. For information about all metrics that MediaTailor emits, see [AWS Elemental MediaTailor CloudWatch metrics](monitoring-cloudwatch-metrics.md#metrics). | Metric | Definition | Use | | --- | --- | --- | | GetManifest.Age | Measures the total age of the manifest, including both `GetManifest.MediaTailorAge` and `Origin.Age` for this configuration. | You can use this metric to identify manifests that are past your update threshold and are stale. Set alarms on this metric so that you're alerted when stale manifests are being served. For information about alarms, see [Alarming on metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ConsoleAlarms.html) in the *Amazon CloudWatch User Guide.* When you receive an alarm, use `Origin.Age` and `GetManifest.MediaTailorAge` to identify if MediaTailor or the origin is causing the staleness. | | Origin.Age | Measures how long the origin has the manifest before sending it to MediaTailor for this configuration.This metric is not emitted when the response comes from a content delivery network (CDN). The response must come from the origin for `Origin.Age` to be emitted. | When you identify stale manifests with `GetManifest.Age`, you can analyze the `Origin.Age` metric and the `GetManifest.MediaTailorAge` metric to determine which is contributing to manifest staleness. If you find that `Origin.Age` is longer than your typical processing times at the origin, it's likely that the upstream system is causing the issue and you should focus diagnostics there. | | GetManifest.MediaTailorAge | Measures how long MediaTailor has stored this manifest for this configuration. | When you identify stale manifests with `GetManifest.Age`, you can analyze the `GetManifest.MediaTailorAge` metric and the `Origin.Age` metric to determine which is contributing to manifest staleness. If the `GetManifest.MediaTailorAge` is longer than your typical manifest personalization times in MediaTailor, it's likely that MediaTailor is causing the issue and you should focus diagnostics there. `GetManifest.Latency` can further identify how long it takes for MediaTailor to create a personalized manifest. | | GetManifest.Latency | Measures the amount of time it takes for MediaTailor to process the request and create a personalized manifest for this configuration. | When you compare `Origin.Age` and `GetManifest.MediaTailorAge` and determine that MediaTailor is the cause of delayed manifest delivery, you can analyze the `GetManifest.Latency` metric to determine if the manifest personalization process is contributing to manifest staleness. `GetManifest.MediaTailorAge` measures the total time that the manifest is stored in MediaTailor. `GetManifest.Latency` measures how much of that storage time is MediaTailor personalizing the manifest in response to a request. | # Recording AWS Elemental MediaTailor API calls AWS Elemental MediaTailor is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in MediaTailor. CloudTrail captures all API calls for MediaTailor as events. The calls captured include calls from the MediaTailor console and code calls to the MediaTailor API operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for MediaTailor. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**. Using the information collected by CloudTrail, you can determine the request that was made to MediaTailor, the IP address from which the request was made, who made the request, when it was made, and additional details. To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html). ## AWS Elemental MediaTailor information in CloudTrail CloudTrail is enabled on your AWS account when you create the account. When activity occurs in AWS Elemental MediaTailor, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**. You can view, search, and download recent events in your AWS account. For more information, see [Viewing events with CloudTrail event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html). For an ongoing record of events in your AWS account, including events for AWS Elemental MediaTailor, create a trail. A *trail* enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following: + [Creating a trail for your AWS account](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + [AWS service integrations with CloudTrail logs](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations) + [Configuring Amazon SNS notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html) + [Receiving CloudTrail log files from multiple regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail log files from multiple accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) All AWS Elemental MediaTailor actions are logged by CloudTrail and are documented in the [AWS Elemental MediaTailor API reference](https://docs.aws.amazon.com/mediatailor/latest/apireference/Welcome.html). For example, calls to the `PutPlaybackConfiguration` and `ListPlaybackConfigurations` operations generate entries in the CloudTrail log files. Every event or log entry contains information about who generated the request. The identity information helps you determine the following: + Whether the request was made with the root user or AWS Identity and Access Management (IAM) credentials + Whether the request was made with temporary security credentials for a role or federated user + Whether the request was made by another AWS service For more information, see [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). ## Understanding AWS Elemental MediaTailor log file entries A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order. The following example shows a CloudTrail log entry that demonstrates the `PutPlaybackConfiguration` action: ``` { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "AIDAEXAMPLE", "arn": "arn:aws:iam::111122223333:user/testuser", "accountId": "111122223333", "accessKeyId": "AIDAEXAMPLE", "userName": "testuser" }, "eventTime": "2018-12-28T22:53:46Z", "eventSource": "mediatailor.amazonaws.com", "eventName": "PutPlaybackConfiguration", "awsRegion": "us-west-2", "sourceIPAddress": "1.2.3.4", "userAgent": "PostmanRuntime/7.4.0", "requestParameters": { "VideoContentSourceUrl": "http://examplevideo.com", "Name": "examplename", "AdDecisionServerUrl": "http://exampleads.com" }, "responseElements": { "SessionInitializationEndpointPrefix": "https://777788889999.mediatailor.us-east-1.amazonaws.com/v1/session/AKIAIOSFODNN7EXAMPLE/examplename/", "DashConfiguration": { "ManifestEndpointPrefix": "https://777788889999.mediatailor.us-east-1.amazonaws.com/v1/dash/AKIAIOSFODNN7EXAMPLE/examplename/", "MpdLocation": "EMT_DEFAULT" }, "AdDecisionServerUrl": "http://exampleads.com", "CdnConfiguration": {}, "PlaybackEndpointPrefix": "https://777788889999.mediatailor.us-east-1.amazonaws.com", "HlsConfiguration": { "ManifestEndpointPrefix": "https://777788889999.mediatailor.us-east-1.amazonaws.com/v1/master/AKIAIOSFODNN7EXAMPLE/examplename/" }, "VideoContentSourceUrl": "http://examplevideo.com", "Name": "examplename" }, "requestID": "1a2b3c4d-1234-5678-1234-1a2b3c4d5e6f", "eventID": "987abc65-1a2b-3c4d-5d6e-987abc654def", "readOnly": false, "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` The following example shows a CloudTrail log entry that demonstrates the `GetPlaybackConfiguration` action: ``` { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "AIDAEXAMPLE", "arn": "arn:aws:iam::111122223333:user/testuser", "accountId": "111122223333", "accessKeyId": "AIDAEXAMPLE", "userName": "testuser" }, "eventTime": "2018-12-28T22:52:37Z", "eventSource": "mediatailor.amazonaws.com", "eventName": "GetPlaybackConfiguration", "awsRegion": "us-west-2", "sourceIPAddress": "1.2.3.4", "userAgent": "PostmanRuntime/7.4.0", "requestParameters": { "Name": "examplename" }, "responseElements": null, "requestID": "0z1y2x3w-0123-4567-9876-6q7r8s9t0u1v", "eventID": "888ddd77-3322-eeww-uuii-abc123jkl343", "readOnly": true, "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` # Receiving AWS Elemental MediaTailor channel assembly alerts MediaTailor creates alerts for issues or potential issues that occur with your channel assembly resources. The alert describes the issue, when the issue occurred, and the affected resources. You can view the alerts in the AWS Management Console, the AWS Command Line Interface (AWS CLI), AWS SDKs, or programmatically using the MediaTailor [ListAlerts](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_ListAlerts.html) API. **Important** Alerts are only available for channel assembly resources created on or after July 14th, 2021. **Channel Assembly Alerts** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/channel-assembly-alerts.html) ## Troubleshooting manifest-related alerts When you encounter manifest-related alerts such as `UNPARSABLE_MANIFEST`, `VARIANT_DURATION_MISMATCH`, or `TARGET_DURATION_MISMATCH`, check the following: 1. **Verify source requirements**: Ensure your content meets the requirements outlined in [Integrating a content source for MediaTailor ad insertion](integrating-origin.md). 1. **Check manifest logs**: For detailed manifest error analysis and event types, see [AWS Elemental MediaTailor manifest logs description and event types](log-types.md). 1. **Check error codes**: For detailed error analysis, see [Troubleshooting MediaTailor](troubleshooting.md). 1. **Review manifest format**: Verify that your manifest follows the correct format specifications for your streaming protocol (HLS or DASH). ## Viewing alerts You can view alerts for any MediaTailor channel assembly resource. When you view the alerts for channels and programs, MediaTailor includes all of the related resources contained within the channel or program. For example, when you view the alerts for a specific program, you also see alerts for the source location and VOD sources that the program contains. To view alerts, perform the following procedure. ------ #### [ Console ] **To view alerts in the console** 1. Open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. Choose the resource that you want to view alerts for. 1. Select the **Alerts** tab to view the alerts. ------ #### [ AWS Command Line Interface (AWS CLI) ] To list alerts for a channel assembly resource, you need the resource's [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). You can use the `describe-resource_type` command in the AWS Command Line Interface (AWS CLI) to get the resource's ARN. For example, run the [describe-channel](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/describe-channel.html) command to get a specific channel's ARN: ``` aws mediatailor describe-channel --channel-name MyChannelName ``` Then use the [aws mediatailor list-alerts](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/list-alerts.html) command to list the alerts associated with the resource: ``` aws mediatailor list-alerts --resource-arn arn:aws:mediatailor:region:aws-account-id:resource-type/resource-name ``` ------ #### [ API ] To list alerts for a channel assembly resource, you need the resource's [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). You can use the `DescribeResource` operation in the MediaTailor API to get the resource's ARN. For example, use the [DescribeChannel](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_DescribeChannel.html) operation to get a specific channel's ARN. Then use the [ListAlerts](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_ListAlerts.html) API to list the alerts for the resource. ------ ## Handling alerts When an alert occurs, view the alerts in the AWS Management Console, or use the AWS Command Line Interface (AWS CLI), AWS SDKs, or the MediaTailor Alerts API to determine the possible sources of the issue. After you resolve the issue, MediaTailor clears the alert. # Tagging AWS Elemental MediaTailor resources A *tag* is a metadata label that you assign or that AWS assigns to an AWS resource. Each tag consists of a *key* and a *value*. For tags that you assign, you define the key and value. For example, you might define the key as `stage` and the value for one resource as `test`. Tags help you do the following: + Identify and organize your AWS resources. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related. For example, you could assign the same tag to an AWS Elemental MediaPackage channel and endpoint that you assign to an AWS Elemental MediaTailor configuration. + Track your AWS costs. You activate these tags on the AWS Billing and Cost Management dashboard. AWS uses the tags to categorize your costs and deliver a monthly cost allocation report to you. For more information, see [Use cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the [AWS Billing User Guide](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/). + Control access to your AWS resources. For more information, see [Controlling access using tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html). The following sections provide more information about tags for AWS Elemental MediaTailor. ## Supported resources in AWS Elemental MediaTailor The following resources in AWS Elemental MediaTailor supports tagging: + Channels + Configurations + SourceLocations + VodSources ## Tag restrictions The following basic restrictions apply to tags on AWS Elemental MediaTailor resources: + Maximum number of tags that you can assign to a resource – 50 + Maximum key length – 128 Unicode characters + Maximum value length – 256 Unicode characters + Valid characters for key and value – a-z, A-Z, 0-9, space, and the following characters: \$1 . : / = \$1 - and @ + Keys and values are case sensitive + Don't use `aws:` as a prefix for keys; it's reserved for AWS use ## Managing tags in AWS Elemental MediaTailor You set tags as properties on a resource. You can add, edit, and delete tags through the AWS Elemental MediaTailor API or the AWS Command Line Interface (AWS CLI). For more information, see the [AWS Elemental MediaTailor API reference](https://docs.aws.amazon.com/mediatailor/latest/apireference/Welcome.html). # Monitoring AWS media services with workflow monitor Workflow monitor is a tool for the discovery, visualization, and monitoring of AWS media workflows. Workflow monitor is available in the AWS console and API. You can use workflow monitor to discover and create visual mappings of your workflow's resources, called *signal maps*. You can create and manage Amazon CloudWatch alarm and Amazon EventBridge rule templates to monitor the mapped resources. The monitoring templates you create are transformed into deployable AWS CloudFormation templates to allow repeatability. AWS recommended alarm templates provide predefined best-practice monitoring. **Discover** Utilize signal maps to automatically discover interconnected AWS resources associated with your media workflow. Discovery can begin at any supported service resource and creates an end-to-end mapping of the workflow. Signal maps can be used as stand-alone visualization tools or enhanced with monitoring templates. ![\[Workflow monitor discovery components.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/workflowmonitor-discovery.png) **Monitor** You can create custom CloudWatch alarm and EventBridge rule templates to monitor the health and status of your media workflows. Best practice alarm templates are available to import into your workflow monitor environment. You can use the best practice alarm templates as they are, or edit them to better fit your workflow. Any templates you create are transformed into CloudFormation templates for repeatable deployment. ![\[Workflow monitor monitoring components.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/workflowmonitor-monitoring.png) **Note** There is no direct cost for using workflow monitor. However, there are costs associated with the resources created and used to monitor your workflow. When monitoring is deployed, Amazon CloudWatch and Amazon EventBridge resources are created. When using the AWS Management Console, prior to deploying monitoring to a signal map, you will be notified of how many resources will be created. For more information about pricing, see: [CloudWatch pricing](https://aws.amazon.com/cloudwatch/pricing/) and [EventBridge pricing](https://aws.amazon.com/eventbridge/pricing/). Workflow monitor uses AWS CloudFormation templates to deploy the CloudWatch and EventBridge resources. These templates are stored in a standard class Amazon Simple Storage Service bucket that is created on your behalf, by workflow monitor, during the deployment process and will incur object storage and recall charges. For more information about pricing, see: [Amazon S3 pricing](https://aws.amazon.com/s3/pricing/). Previews generated in the workflow monitor signal map for AWS Elemental MediaPackage channels are delivered from the MediaPackage Origin Endpoint and will incur Data Transfer Out charges. For pricing, see: [MediaPackage pricing](https://aws.amazon.com/mediapackage/pricing/). ## Components of workflow monitor Workflow monitor has four major components: + CloudWatch alarm templates - Define the conditions you would like to monitor using CloudWatch. You can create your own alarm templates, or import predefined templates created by AWS. For more information, see: [CloudWatch alarm groups and templates for monitoring your AWS media workflow](monitor-with-workflow-monitor-configure-alarms.md) + EventBridge rule templates - Define how EventBridge sends notifications when an alarm is triggered. For more information, see: [EventBridge rule groups and templates for monitoring your AWS media workflow](monitor-with-workflow-monitor-configure-notifications.md) + Signal maps - Use an automated process to create AWS Elemental workflow maps using existing AWS resources. The signal maps can be used to discover resources in your workflow and deploy monitoring to those resources. For more information, see: [Workflow monitor signal maps](monitor-with-workflow-monitor-configure-signal-maps.md) + Overview - The overview page allows you to directly monitor the status of multiple signal maps from one location. Review metrics, logs, and alarms for your workflows. For more information, see: [Workflow monitor overview](monitor-with-workflow-monitor-operate-overview.md) ## Supported services Workflow monitor supports automatic discovery and signal mapping of resources associated with the following services: + AWS Elemental MediaConnect + AWS Elemental MediaLive + AWS Elemental MediaPackage + AWS Elemental MediaTailor + Amazon S3 + Amazon CloudFront **Topics** + [ ## Components of workflow monitor ](#monitor-with-workflow-monitor-components) + [ ## Supported services ](#monitor-with-workflow-monitor-supported-services) + [ # Configuring workflow monitor to monitor AWS media services ](monitor-with-workflow-monitor-configure.md) + [ # Using workflow monitor ](monitor-with-workflow-monitor-operate.md) # Configuring workflow monitor to monitor AWS media services To setup workflow monitor for the first time; you create the alarm and event templates, and discover signal maps that are used to monitor your media workflows. The following guide contains the steps necessary to setup both Administrator and Operator level IAM roles, create workflow monitor resources, and deploy monitoring to your workflows. **Topics** + [ # Getting started with workflow monitor ](monitor-with-workflow-monitor-configure-getting-started.md) + [ # Workflow monitor groups and templates ](monitor-with-workflow-monitor-configure-templates.md) + [ # Workflow monitor signal maps ](monitor-with-workflow-monitor-configure-signal-maps.md) + [ # Workflow monitor quotas ](monitor-with-workflow-monitor-configure-quotas.md) # Getting started with workflow monitor The following steps provide a basic overview of using workflow monitor for the first time. 1. Setup workflow monitor IAM permissions for administrator and operator level roles: [Workflow monitor IAM policies](monitor-with-workflow-monitor-configure-getting-started-IAM.md) 1. Build alarm templates or import predefined templates created by AWS: [CloudWatch alarms](monitor-with-workflow-monitor-configure-alarms.md) 1. Build notification events that will be delivered by EventBridge: [EventBridge rules ](monitor-with-workflow-monitor-configure-notifications.md) 1. Discover signal maps using your existing AWS Elemental resources: [Signal maps ](monitor-with-workflow-monitor-configure-signal-maps.md) 1. Attach the alarm templates and notification rules to your signal map: [Attaching templates](monitor-with-workflow-monitor-configure-signal-maps-attach.md) 1. Deploy the templates to begin monitoring the signal map: [Deploying monitoring templates](monitor-with-workflow-monitor-configure-deploy.md) 1. Monitor and review your workflow monitor resources using the overview section of the AWS console: [Overview](monitor-with-workflow-monitor-operate-overview.md) ![\[The individual steps of setting up workflow monitor. Begin by creating the IAM roles. Next, create templates for alarms and events. Next, discover a signal map and attach your templates to the map. After a signal map has templates attached, the templates must be deployed. The final step is monitoring using the templates and overview resources.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/workflowmonitor-overview-steps.png) # Workflow monitor IAM policies Workflow monitor interacts with multiple AWS services to create signal maps, build CloudWatch and EventBridge resources, and CloudFormation templates. Because workflow monitor interacts with a wide range of services, specific AWS Identity and Access Management (IAM) policies must be assigned for these services. The following examples indicate the necessary IAM policies for both administrator and operator IAM roles. ## Administrator IAM policy The following example policy is for an administrator-level workflow monitor IAM policy. This role allows for the creation and management of workflow monitor resources and the supported service resources that interact with workflow monitor. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudwatch:List*", "cloudwatch:Describe*", "cloudwatch:Get*", "cloudwatch:PutAnomalyDetector", "cloudwatch:PutMetricData", "cloudwatch:PutMetricAlarm", "cloudwatch:PutCompositeAlarm", "cloudwatch:PutDashboard", "cloudwatch:DeleteAlarms", "cloudwatch:DeleteAnomalyDetector", "cloudwatch:DeleteDashboards", "cloudwatch:TagResource", "cloudwatch:UntagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cloudformation:List*", "cloudformation:Describe*", "cloudformation:CreateStack", "cloudformation:UpdateStack", "cloudformation:DeleteStack", "cloudformation:TagResource", "cloudformation:UntagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cloudfront:List*", "cloudfront:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:DescribeNetworkInterfaces" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "events:List*", "events:Describe*", "events:CreateEventBus", "events:PutRule", "events:PutTargets", "events:EnableRule", "events:DisableRule", "events:DeleteRule", "events:RemoveTargets", "events:TagResource", "events:UntagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:Describe*", "logs:Get*", "logs:TagLogGroup", "logs:TagResource", "logs:UntagLogGroup", "logs:UntagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediaconnect:List*", "mediaconnect:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "medialive:*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediapackage:List*", "mediapackage:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediapackagev2:List*", "mediapackagev2:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediapackage-vod:List*", "mediapackage-vod:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediatailor:List*", "mediatailor:Describe*", "mediatailor:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "resource-groups:ListGroups", "resource-groups:GetGroup", "resource-groups:GetTags", "resource-groups:GetGroupQuery", "resource-groups:GetGroupConfiguration", "resource-groups:CreateGroup", "resource-groups:UngroupResources", "resource-groups:GroupResources", "resource-groups:DeleteGroup", "resource-groups:UpdateGroupQuery", "resource-groups:UpdateGroup", "resource-groups:Tag", "resource-groups:Untag" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:*" ], "Resource": "arn:aws:s3:::workflow-monitor-templates*" }, { "Effect": "Allow", "Action": [ "sns:TagResource", "sns:UntagResource" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "tag:Get*", "tag:Describe*", "tag:TagResources", "tag:UntagResources" ], "Resource": "*" } ] } ``` ------ ## Operator IAM policy The following example policy is for an operator-level workflow monitor IAM policy. This role allows for limited and read-only access to the workflow monitor resources and the supported service resources that interact with workflow monitor. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudwatch:List*", "cloudwatch:Describe*", "cloudwatch:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cloudformation:List*", "cloudformation:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cloudfront:List*", "cloudfront:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:DescribeNetworkInterfaces" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "events:List*", "events:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:Describe*", "logs:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediaconnect:List*", "mediaconnect:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "medialive:List*", "medialive:Get*", "medialive:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediapackage:List*", "mediapackage:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediapackagev2:List*", "mediapackagev2:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediapackage-vod:List*", "mediapackage-vod:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "mediatailor:List*", "mediatailor:Describe*", "mediatailor:Get*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:Get*", "s3:List*" ], "Resource": "arn:aws:s3:::workflow-monitor-templates*" }, { "Effect": "Allow", "Action": [ "tag:Get*", "tag:Describe*" ], "Resource": "*" } ] } ``` ------ # Workflow monitor groups and templates Before you can deploy workflow monitoring to a signal map, you must create the groups and templates for CloudWatch alarms and EventBridge notifications. The CloudWatch templates define what scenarios and thresholds will be used to trigger the alarms. The EventBridge templates will determine how these alarms are reported to you. If you only want mappings of your connected resources and do not want to use the monitoring template capabilities of workflow monitor, signal maps can be used without CloudWatch and EventBridge templates. For more information about using signal maps, see: [Signal maps ](monitor-with-workflow-monitor-configure-signal-maps.md) **Topics** + [ # CloudWatch alarm groups and templates for monitoring your AWS media workflow ](monitor-with-workflow-monitor-configure-alarms.md) + [ # EventBridge rule groups and templates for monitoring your AWS media workflow ](monitor-with-workflow-monitor-configure-notifications.md) # CloudWatch alarm groups and templates for monitoring your AWS media workflow Workflow monitor alarms allow you to use existing CloudWatch metrics as the foundation of alarms for your signal maps. You can create an alarm template group to sort and classify the types of alarming that is important to your workflow. Within each alarm template group, you create alarm templates with specific CloudWatch metrics and parameters that you want to monitor. You can create your own alarm templates or import recommended alarm templates created by AWS. After creating an alarm template group and alarm templates within that group, you can attach one or more of these alarm template groups to a signal map. You must create an alarm template group first. After you have created an alarm template group, you can create your own templates or use recommended templates created by AWS. If you want to create your own alarm templates, continue on this page. For more information about importing recommended templates, see: [Recommended templates](monitor-with-workflow-monitor-configure-alarms-recommended-templates.md) This section covers the creation of CloudWatch alarms using workflow monitor. For more information about how the CloudWatch service handles alarms and details of the alarm components, see: [Using CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide* ## Creating alarm template groups Alarm template groups allow you to sort and classify the types of alarms that are important to your workflow. **To create an alarm template group** 1. From the workflow monitor console's navigation pane, select **CloudWatch alarm templates**. 1. Select **Create alarm template group**. 1. Give the alarm template group a unique **Group name** and optional **Description**. 1. Select **Create**, You will be taken to the newly created alarm template group's details page. ## Creating alarm templates You can create alarm templates with the CloudWatch metrics and parameters that you want to monitor. **To create an alarm template** 1. From the alarm template group's details page, select **Create alarm template**. 1. Give the alarm template a unique **Template name** and optional **Description**. 1. In the **Choose metric** section: 1. Select a **Target Resource Type**. The target resource type is a resource for the respective service, such as a channel for MediaLive and MediaPackage or a flow for MediaConnect. 1. Select a **Metric Name**. This is the CloudWatch metric that acts as the foundation for the alarm. The list of metrics will change depending on the selected **Target Resource Type**. 1. In the **Alarm settings** section: **Note** For more information about how the CloudWatch service handles alarms and details of the alarm components, see: [Using CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide* 1. Select the **Statistic**. This is a value such as a **Sum** or an **Average** that will be used to monitor the metric. 1. Select the **Comparison Operator**. This field references the **Threshold** that you set in the next step. 1. Set a **Threshold**. This is a numeric value that the **Comparison Operator** uses to determine greater than, less than, or equal to status. 1. Set a **Period**. This is a time value, in seconds. The **Period** is the length of time that the **Statistic**, **Comparison Operator**, and **Threshold** interact to determine if the alarm gets triggered. 1. Set the **Datapoints**. This value determines how many datapoints are needed to trigger the alarm. 1. Select how to **Treat Missing Data**. This selection determines how this alarm reacts to missing data. 1. Select **Create** to complete the process. An example of a completed alarm template could have the following parameters: A MediaConnect flow **Target Resource Type** is monitored for the Disconnections **Metric Name**. The **Statistic** value is set to Sum with a **Comparison Operator** of "greater than or equal to" and a **Threshold** of 10. The **Period** is set to 60 seconds, and only requires 1 out of 1 **Datapoints**. **Treat Missing Data** is set to "ignore." The result of these settings is: workflow monitor will monitor for disconnections on the flow. If 10 or more disconnections occur within 60 seconds, the alarm will be triggered. 10 or more disconnections in 60 seconds only needs to happen one time for the alarm to be triggered. # Recommended alarm templates for monitoring your AWS media workflow Workflow monitor's recommended templates are a curated selection of AWS Elemental service metrics with predefined alarm settings appropriate for the metric. If you do not want to create customized alarm templates, recommended templates provide you with best-practice monitoring templates that are created by AWS. Workflow monitor contains recommended template groups for each supported service. These groups are designed to apply best-practice monitoring to specific types of workflows. Each template group contains a curated selection of alarms configured from service-specific metrics. For example, a recommended template group for a MediaLive multiplex workflow will have a different set of preconfigured metrics than a MediaConnect CDI workflow. **To use recommended alarm templates** 1. Follow the steps to [create an alarm template group](monitor-with-workflow-monitor-configure-alarms.md#monitor-with-workflow-monitor-alarms-groups-create), or select an existing one. 1. In the **Alarm templates** section, select **Import**. You will need to import the AWS recommended templates into your template group. 1. Use the **CloudWatch alarm template groups** dropdown to select an AWS recommended group. These groups contain curated alarms for specific services. 1. Select the templates to import using the check boxes. Each template will list its metrics, preconfigured monitoring values, and provide a description of the metric. When you are done selecting templates, select the **Add** button. 1. The selected templates will move to the **Alarm template(s) to import** section. Review your choices and select **Import**. 1. After the import is complete, the selected templates will be added to the template group. If you want to add more templates, repeat the import process. 1. Imported templates can be customized after import. Alarm settings can be modified to fit your alarming needs. # EventBridge rule groups and templates for monitoring your AWS media workflow CloudWatch uses Amazon EventBridge rules to send notifications. You begin by creating an event template group. In that event template group, you create event templates that determine what conditions create a notification and who is notified. This section covers the creation of EventBridge rules using workflow monitor. For more information about how the EventBridge service uses rules, see: [EventBridge rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) in the *Amazon EventBridge User Guide* ## Creating event template groups Event template groups allow you to sort and classify events based on your use case. **To create an event template group** 1. From the workflow monitor console's navigation pane, select **EventBridge rule templates**. 1. Select **Create event template group**. 1. Give the alarm template group a unique **Group name** and optional **Description**. 1. Select **Create**, You will be taken to the newly created alarm template group's details page. ## Creating event templates You can send notifications based on event templates you create. **To create an event template** 1. From the event template group's details page, select **Create event template**. 1. Give the event template a unique **Template name** and optional **Description**. 1. In the **Rule settings** section: 1. Select an **Event type**. When selecting an event type, you can choose between several events created by AWS or select **Signal map active alarm** to use an alarm created by an alarm template. 1. Select a **Target service**. This determines how you would like to be notified of this event. You can select Amazon Simple Notification Service or CloudWatch logs. 1. After selecting a target service, select a **Target**. This will be a Amazon SNS topic or a CloudWatch log group, depending on your target service selection. 1. Select **Create** to complete the process. # Workflow monitor signal maps Signal maps are visual mappings of AWS resources in your media workflow. You can use workflow monitor to start the signal map discovery on any of the supported resource types. During the discovery process, workflow monitor will automatically and recursively map all connected AWS resources. After the signal map has been created, you can use the workflow monitor console to do things like deploy monitoring templates, view metrics, and view details of the mapped resources. **Topics** + [ # Creating signal maps for AWS media workflows ](monitor-with-workflow-monitor-configure-signal-maps-create.md) + [ # Viewing signal maps of AWS media workflows ](monitor-with-workflow-monitor-configure-signal-maps-view.md) + [ # Attaching alarm and event templates to the signal map of your AWS media workflow ](monitor-with-workflow-monitor-configure-signal-maps-attach.md) + [ # Deploying templates to the signal map of your AWS media workflow ](monitor-with-workflow-monitor-configure-deploy.md) + [ # Updating the signal map of your AWS media workflow ](monitor-with-workflow-monitor-configure-signal-maps-update.md) + [ # Deleting the signal map of your AWS media workflow ](monitor-with-workflow-monitor-configure-signal-maps-delete.md) # Creating signal maps for AWS media workflows You can use workflow monitor signal maps to create a visual mapping of all connected AWS resources in your media workflow. **To create a signal map** 1. From the workflow monitor console's navigation pane, select **Signal maps**. 1. Select **Create signal map**. 1. Give the signal map a **Name** and **Description**. 1. In the **Discover new signal map** section, resources in the current account and selected region are displayed. Select a resource to begin signal map discovery. The selected resource will be the starting point for discovery. 1. Select **Create**. Allow a few moments for the discovery process to complete. After the process is complete, you will be presented with the new signal map. **Note** Previews generated in the workflow monitor signal map for AWS Elemental MediaPackage channels are delivered from the MediaPackage Origin Endpoint and will incur Data Transfer Out charges. For pricing, see: [MediaPackage pricing](https://aws.amazon.com/mediapackage/pricing/). # Viewing signal maps of AWS media workflows Workflow monitor signal maps allow you to see a visual mapping of all connected AWS resources in your media workflow. **Signal map views** After selecting a signal map, you have two views that can be used to monitor or configure the signal map. **Monitor signal map** and **Configure signal map** is a context-sensitive button found in the upper-right of the signal map console section. If you select the signal map using the **Signal maps** section of the navigation pane, your signal map will be displayed in the configuration view. The configuration view allows you to make changes to the template groups attached to this signal map, deploy the attached templates, and view the basic details and tags of the signal map. If you select the signal map using the **Overview** section of the navigation pane, your signal map will be displayed in monitoring view. The monitoring view displays the CloudWatch alarms, EventBridge rules, alerts, logs, and metrics for this signal map. The view can be changed at any time by selecting the **Monitor/Configure signal map** button in the upper-right. The configuration view requires administrator-level IAM permissions. Required IAM permissions can be viewed here: [Workflow monitor IAM policies](monitor-with-workflow-monitor-configure-getting-started-IAM.md) **Navigating the signal map** A signal map will contain nodes for every supported AWS resource discovered by workflow monitor. Certain resources, such as MediaLive channels and MediaPackage endpoints can display thumbnail previews of the content, if thumbnail previews are available. Selecting a resource node, and selecting **View selected resource details** from the **Actions** dropdown menu will take you to the associated service's details page. For example, selecting a MediaLive channel and selecting **View selected resource details** will open the MediaLive console's details page for that channel. Selecting a resource node will filter the list of active alarms to only that node. If you select the resource's **Target ARN** in the active alarm, you will be taken to the associated service's details page, with the selected resource open. # Attaching alarm and event templates to the signal map of your AWS media workflow After you have created alarm and event templates, you need to attach these to a signal map. Any of the alarm and event templates you have created can be attached to any discovered signal maps. **To attach alarm and event templates to your signal map** 1. From the workflow monitor console's navigation pane, select **Signal maps** and select the signal map you want to work with. 1. In the upper-right of the signal map page, in the **CloudWatch alarm template groups** tab, select **Attach CloudWatch alarm template groups**. 1. In the new section that opens, choose all of the alarm template groups that you want to apply to this signal map, then select **Add**. This will cause the selected alarm template groups to move to the **Attached CloudWatch alarm template groups** section. 1. Selecting **Save** will save your changes and return you to the signal map page. 1. At the right of the signal map page, select the **EventBridge rule template groups** tab then select **Attach EventBridge rule template groups**. 1. In the new section that opens, choose all of the event template groups that you want to apply to this signal map, then select **Add**. This will cause the selected rule template groups to move to the **Attached EventBridge rule template groups** section. 1. Selecting **Save** will save your changes and return you to the signal map page. 1. You have assigned CloudWatch alarm and EventBridge rule templates to the signal map, but the monitoring is not yet deployed. The next section will cover the deployment of the monitoring resources. # Deploying templates to the signal map of your AWS media workflow After you have attached the alarm and event templates to your signal map, you must deploy the monitoring. Until the deployment is complete, the monitoring of your signal map will not be active. Workflow monitor will only deploy alarms that are relevant to the selected signal map. For example, the attached alarm template group might contain alarms for multiple services, such as MediaLive, MediaPackage, and MediaConnect. If the selected signal map only contains MediaLive resources, no MediaPackage or MediaConnect alarms will be deployed. **To deploy the monitoring templates** 1. After attaching alarm and event template groups to your signal map and saving your changes, select **Deploy monitor** in the **Actions** dropdown menu. 1. You will be asked to confirm the deployment and presented with the number of CloudWatch and EventBridge resources that will be created. If you would like to proceed, select **Deploy**. **Note** There is no direct cost for using workflow monitor. However, there are costs associated with the resources created and used to monitor your workflow. When monitoring is deployed, Amazon CloudWatch and Amazon EventBridge resources are created. When using the AWS Management Console, prior to deploying monitoring to a signal map, you will be notified of how many resources will be created. For more information about pricing, see: [CloudWatch pricing](https://aws.amazon.com/cloudwatch/pricing/) and [EventBridge pricing](https://aws.amazon.com/eventbridge/pricing/). Workflow monitor uses AWS CloudFormation templates to deploy the CloudWatch and EventBridge resources. These templates are stored in a standard class Amazon Simple Storage Service bucket that is created on your behalf, by workflow monitor, during the deployment process and will incur object storage and recall charges. For more information about pricing, see: [Amazon S3 pricing](https://aws.amazon.com/s3/pricing/). 1. The status of the deployment is displayed next to the name of the signal map. The deployment status is also visible in the **Stacks** section of the CloudFormation console. After a few moments of resource creation and deployment, your signal map monitoring will begin. # Updating the signal map of your AWS media workflow If a change is made to your workflow, you might need to rediscover the signal map and redeploy monitoring resources. Workflow monitor is a visualization and monitoring tool that does not have the ability to make any changes to your workflow. Signal maps represent a point-in-time visualization of your workflow. In the event that you add, remove, or significantly modify parts of your media workflow, we recommend that you rediscover the signal map. If you have monitoring resources attached to the signal map, we recommend you redeploy monitoring after the rediscovery process. **To rediscover a signal map** 1. From the workflow monitor console's navigation pane, select **Signal maps** and select the signal map you want to work with. 1. Verify that you are in the **Configure signal map** view. For more information about changing views, see: [Viewing signal maps ](monitor-with-workflow-monitor-configure-signal-maps-view.md) 1. In the upper-right of the signal map page, select the **Actions** dropdown menu. Select **Rediscover**. 1. You will be presented with the rediscovery screen. Select a resource that is a part of the workflow you are rediscovering. Select the **Rediscover** button. 1. The signal map will be rebuilt according to the current workflow. If you need to redeploy monitoring resources, stay on this signal map's page. Any previously attached monitoring templates will remain attached, but will need to be redeployed. **To redeploy monitoring templates after a signal map rediscovery** 1. After the rediscovery, you will be directed to the updated signal map. To redeploy the monitoring templates, select **Deploy monitor** from the **Actions** dropdown menu. 1. You will be asked to confirm the deployment and presented with the number of any CloudWatch and EventBridge resources that will be created. If you would like to proceed, select **Deploy**. 1. The status of the deployment is displayed next to the name of the signal map. After a few moments of resource creation and deployment, your signal map monitoring will begin. # Deleting the signal map of your AWS media workflow If you not longer need a signal map, it can be deleted. If you have monitoring templates deployed on the signal map, the deletion process will ask you to delete any CloudWatch and EventBridge resources that have been deployed to this signal map. Deleting the deployed resources does not affect the templates that created them. This resource deletion is to ensure that you do not have CloudWatch and EventBridge resources that are deployed but not used. **To delete a signal map** 1. From the workflow monitor console's navigation pane, select **Signal maps** and select the radio button next to the signal map you want to delete. 1. Select the **Delete** button. You will be asked to confirm the deletion of the monitoring resources. Select **Delete** to begin the monitoring resource deletion process. 1. The **Monitor deployment** column will display the current status. When the status has changed to **DELETE\$1COMPLETE**, select the **Delete** button again. 1. You will be asked to confirm deletion of the signal map. Select **Delete** to proceed and delete the signal map. # Workflow monitor quotas The following section contains quotas for workflow monitor resources. Each quota is on a "per account" basis. If you need to increase a quota for your account, you can use the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/home) to request an increase, unless otherwise noted in the following table. **Quotas** | Resource type | Quota | | --- | --- | | CloudWatch alarm template groups | 20 | | CloudWatch alarm templates | 200 | | EventBridge rule template groups | 20 | | EventBridge rule templates | 200 | | Signal maps | 30 | | Signal maps: CloudWatch alarm template groups attached to a single signal map | 5You cannot increase this quota. | | Signal maps: EventBridge rule template groups attached to a single signal map | 5You cannot increase this quota. | # Using workflow monitor Use the **overview** and **signal maps** sections of the workflow monitor console to review the current status of the workflows and any associated alarms, metrics, and logs. **Topics** + [ # Workflow monitor overview ](monitor-with-workflow-monitor-operate-overview.md) + [ # Overview logs and metrics for workflow monitor ](monitor-with-workflow-monitor-operate-logs-metrics.md) + [ # Using workflow monitor signal maps ](monitor-with-workflow-monitor-operate-signal-maps.md) # Workflow monitor overview The **Overview** section of the workflow monitor console is a dashboard that provides at-a-glance information about your signal maps. In the overview section, you can see the current state of each signal map's monitoring, as well as CloudWatch metrics and any associated CloudWatch logs. You can select any signal map to be taken to that signal maps console page. **Overview filtering** Using the **Search** bar in the overview section, you can filter the list of signal maps using context sensitive constraints. After selecting the search bar, you will be presented with a list of **Properties** to filter by. Selecting a property will present **Operators** such as Equals, Contains, Does not equal, and Does not contain. Selecting an operator will create a list of resources from the selected property type. Selecting one of these resources will cause the signal map list to only display signal maps that fit the constraint you defined. # Overview logs and metrics for workflow monitor To view CloudWatch metrics and logs for a signal map, select the radio button next to the name of the signal map. A tabbed interface for both metrics and logs will appear beneath the signal map list. **CloudWatch Metrics** CloudWatch metrics for the selected signal map will be context-sensitive and only display metrics associated with the services used in that signal maps workflow. You can use the on-screen metrics tools to customize the displayed metric periods and time ranges. **CloudWatch Logs ** If you associated a CloudWatch log group with the signal map, that group will be displayed here. # Using workflow monitor signal maps From the **overview** section of the console, you can select a specific signal map to view more information about that signal map and its attached monitoring resources. After selecting a signal map, you will be presented with the signal map and a number of tabbed section containing more information: + CloudWatch alarms + EventBridge rules + AWS Elemental alerts + Metrics + Logs + Basic details **Navigating the signal map** A signal map will contain nodes for every supported AWS resource discovered by workflow monitor. Certain resources, such as MediaLive channels and MediaPackage endpoints can display thumbnail previews of the content, if thumbnail previews are available. Selecting a resource node, and selecting **View selected resource details** from the **Actions** dropdown menu will take you to the associated service's details page. For example, selecting a MediaLive channel and selecting **View selected resource details** will open the MediaLive console's details page for that channel. Selecting a resource node will filter the list of active alarms to only that node. If you select the resource's **Target ARN** in the active alarm, you will be taken to the associated service's details page, with the selected resource open.