# 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" ```