# Writing AWS Elemental MediaTailor logs directly to Amazon CloudWatch Logs
<a name="monitoring-cw-logs"></a>

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
<a name="monitoring-permissions"></a>

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
<a name="as-run-log"></a>

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
<a name="enabling-as-run-log"></a>

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
<a name="disabling-as-run-log"></a>

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
<a name="monitor-cloudwatch-ads-logs"></a>

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
<a name="querying-the-ads-logs"></a>

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)
```