Download Message IDs for Troubleshooting

Note: Sign in to the developer console to build or publish your skill.

Use the operational metrics on the Analytics page of the Alexa developer console to troubleshoot smart home and video skill failures and latency issues that might impact customers. From the Capability Directives page, you can download message ID logs to view the latency and success rate metrics by capability interface. For details about these metrics, see Operational metrics.

Learn how to download and view your message IDs and associated metadata to gain visibility into causes of failures and insight to help you debug skill issues.

Download directive message IDs

Use the Alexa developer console to access your skill metrics and download message ID logs and associated metadata for a given skill. Use the logs to view and troubleshoot errors with your skill.

For details about how to view the metrics in the developer console, see View Skill Metrics.

Download logs by category

Apply filter criteria to limit the logs to a specific set of message IDs. You can filter by different categories, such as by time or capability.

To download your message ID logs by category

On the Analytics page, on the left pane, locate the Operational Metrics heading, and then click Capability Directives.
To download latency and success rate logs, click the Overview tab.
Or, to download latency logs, click the Latency tab.
Or, to download success rate logs, click the Success Rate tab.
To apply filter criteria to the logs, click the Download Message IDs link.
The following screenshot shows an example Capability Directives page with the Download Message IDs link circled in red.
Download message IDs example
On Download Message IDs, fill out the applicable filter criteria fields, and then click Download.
The following example shows populated filter criteria.
Example filter criteria by category

Save the downloaded CSV file to a convenient place.
For details about the contents, see About the message ID log file.

Download logs by chart

You can create filter criteria automatically by exporting your message IDs from a chart for a specific capability directive, such as Alexa.BrightnessController.

To download your message ID logs by chart

On the Analytics page, on the left pane, locate the Operational Metrics heading, and then click Capability Directives.
To download latency logs, click the Latency tab.
Or, to download success rate logs, click the Success Rate tab.
Find the capability chart that you want to export.
On the chart that you selected, click Export chart, and then select Download Message IDs.
The following screenshot shows an example Capability Directives page with the Download Message IDs selection circled in red.
Export chart example
On Download Message IDs, view the populated filters, and then click Download.
For details about the filter options, see Define filter criteria.
The following example shows populated filter criteria.
Example filter criteria by chart

Save the downloaded CSV file to a convenient place.
For details about the contents, see About the message ID log file.

Define filter criteria

You can select or enter the following filter criteria for your message IDs:

Timeline (Required) – Gives a starting time and a duration for applying the search filter. The 20 most recent message IDs are available for download for a given timeline.
- Start Time (UTC) – The starting UTC timestamp to apply to the search filter for message IDs.
- Duration – Select the duration to use to calculate a window for the time line. Valid values: 5 minutes, 10 minutes, 15 minutes, 30 minutes, 45 minutes, 1 Hour.
Response Type (Required) – Select the type of responses to include in your search results:
- Skill Failure – Requests to a skill categorized as failures.
- Skill Success – Requests to a skill categorized as successes.
- Invalid Request – Invalid requests to a skill.
- All – All requests to the skill.
Capability (Required) – Select at least one capability from the list of all capabilities supported by the skill to include in the search results.
Directive (Required) – Select at least one directive from the list of all directives supported by the skill to include in the search results.
Error Type/Exception (Optional) – Select at least one error type or exception from the list to include in the search results.
- Error Type – Choose from a subset of the most frequently seen Error Types. If you leave this field blank, the search downloads the top 20 message IDs associated with all Error Types and the supported subset of Exceptions. For a comprehensive list of Error Types and their descriptions, see the Alexa.ErrorResponse Interface reference.
- Exception – Exceptions occur on the Alexa side after Alexa attempts to process the response from your skill. The following subset of Alexa exceptions are available:
  - SKILL_RESPONSE_TIMEOUT_EXCEPTION – Exception thrown when a skill times out on an Alexa request to the skill.
  - INVALID_SKILL_RESPONSE_EXCEPTION – Exception thrown when Alexa receives an invalid response from the skill.
Latency Threshold (ms) (Optional) – Specify a latency threshold in milliseconds to filter your search results by response latency. Only message IDs with latencies greater than or equal to the threshold are available for download.

About the message ID log file

The downloaded message ID log file is a CSV file with the top 20 message IDs that match the filter criteria. You can open the downloaded file in a spreadsheet editor.

The log file contains the following fields:

Timestamp(UTC) – Time in UTC format that the user invoked the skill.
Skill ID – Alexa skill ID for the skill.
Skill Stage – Specifies whether the skill is in development or production.
Region – Region where the user invoked the skill.
Capability – Alexa interface associated with the skill invocation.
Directive – Alexa directive that invoked the skill. For more details about capability directives, see the documentation for each interface that your skill supports.
Request Message ID – Message ID associated with the request.
Success Flag – TRUE indicates that the skill request was a success; FALSE indicates that the skill request failed.
Latency(ms) – Number of milliseconds until Alexa receives a response from the skill after Alexa sends a directive to the skill.
Error Type – Error thrown by the skill, if applicable. For a complete list of Error Types, see the Alexa.ErrorResponse Interface.
Exception Name – Alexa-side exception, if applicable. Supported exceptions for the Message ID logs are SKILL_RESPONSE_TIMEOUT_EXCEPTION and INVALID_SKILL_RESPONSE_EXCEPTION.

Download logs for operational issues

Use the Capability Directives page on the Alexa developer console to access your skill metrics and download the operational metrics for a given skill. You can filter the logs by device type and country.

For details about how to view the metrics in the developer console, see View Skill Metrics.

To download logs for latency and success rate issues

On the Analytics page, on the left pane, locate the Operational Metrics heading, and then click Capability Directives.
On the Overview tab, find the issue chart that you want to export.
To open the issue log by device type, click one of the listed device types.
Or, to open the issue log by country, click one of the listed countries. The following screenshot shows the Lightblub device type selected in an example Latency Issue Summary.
Example of latency and success rate issues summaries
To download the message ID log for a specific hour, country, device type, and directive statistic, under MESSAGE IDs, click the download button for the row that you want to troubleshoot.
The following example shows the download button to export the message ID log in the first row.
Export message ID log example

To download the summary statistics for all issues, click the download button at the top of the page.
Or, at the bottom of the page, click Export the full list.
The following example shows the download button to export the summary log.
Export summary log example

Save the downloaded CSV files to a convenient place.
For details about the contents, see About the issue log files.

About the issue log files

You can troubleshooting latency and success rate performance issues by viewing the logs for issues that occur for a specific country or device type. Use the message ID logs to troubleshoot capability directives used in your skill.

Message ID log file

The message ID log file is a CSV file with one row for each message that exceeds the baseline. You can open the downloaded file in a spreadsheet editor.

The summary log file contains the following fields:

Date – Date and time in UTC format during which the issue occurred for the specified message ID.
Directive Namespace – Alexa interface used in the request.
Directive Name – Alexa directive that invoked the skill. For more details about capability directives, see the documentation for each interface that your skill supports.
Country – Country where the user invoked the directive.
DeviceType – Type of device.
Latency(ms) – Number of milliseconds until Alexa receives a response from the skill after Alexa sends a directive to the skill. Available for latency issue logs only.
Success Rate – Indicates whether the directive request succeeded or failed. Available for success rate issue logs only.
MessageId – Message ID associated with the request from Alexa.

Summary log file

The summary log file is a CSV file with one row for a combination of device type, country, and directive statistic, aggregated hourly. You can open the downloaded file in a spreadsheet editor.