Download Message IDs for Troubleshooting

---

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, success rate, and user-perceived errors aggregated across capability interfaces. For details about these metrics, see View Operational Metrics for Smart Home and Video Skills.

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

Troubleshoot errors and latency issues

Alexa includes the unique messageId property in the header of requests to your skill. Your skill includes a new messageId value in the response to Alexa. You can download the message ID logs to find the associated request and response in your skill logs. View these logs together to troubleshoot issues that impact customers.

Try the following best practices to troubleshoot errors:

• In your skill code, log a message with the messageId and capability interface for every error that your skill returns to Alexa. Include enough information to troubleshoot the error.
• On the Analytics > Capability Directives page, choose a specific directive, latency threshold, or error code with a high error rate and drill down to find the message IDs that produced the error.
• Download the selected message IDs.
• Find your logs in the CloudWatch console in the log group for your skill.
• Analyze your logs to find the matching message IDs and the reason for the recurring error.

Download message ID logs

Use the Alexa developer console to access your skill metrics and download message ID logs and associated metadata for a given smart home or video skill. For details about how to view the metrics in the developer console, see View Skill Metrics.

Logs for latency and success rate

Download latency and success rate logs for the aggregate of all capability interfaces and for each capability interface supported by your skill. Analyze the logs to understand when latency and success rate issues occur.

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. Complete the following steps to download latency and success rate data by category.

To download your message ID logs by category

1. On the Analytics page, on the left pane, locate the Operational Metrics heading, and then click Capability Directives.
2. 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.
3. 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.

   

4. On Download Message IDs, fill out the applicable filter criteria fields, and then click Download.
   The following example shows populated filter criteria.

   

5. Save the downloaded CSV file to a convenient place.
   For details about the contents, see About the latency and success rate 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. Complete the following steps to download latency and success rate data for a selected chart.

To download your message ID logs by chart

1. On the Analytics page, on the left pane, locate the Operational Metrics heading, and then click Capability Directives.
2. To download latency logs, click the Latency tab.
   Or, to download success rate logs, click the Success Rate tab.
3. Find the capability chart that you want to export.
4. 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.

   

5. 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.

   

6. 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 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.

Logs for performance issues

The Overview tab shows a summary of latency and success rate issues and the number of utterances affected. This data shows the countries and device types that don't meet the recommended operational performance targets. Download these logs to troubleshoot performance issues. You can filter the logs by device type and country.

To download logs for performance issues

1. On the Analytics page, on the left pane, locate the Operational Metrics heading, and then click Capability Directives.
2. On the Overview tab, find the issue chart that you want to export.
3. 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.

   

4. 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.

   

5. 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.

   

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

About the log file

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. You can open the downloaded files in a spreadsheet editor.

Message ID log file

The message ID log file is a CSV file with one row for each message that exceeds the baseline. The message ID 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. The summary log file contains the following fields:

• Date – Date and time in UTC format during which the issue occurred. The time indicates the start of the hour.
• DeviceType – Type of device.
• Country – Country where the user invoked the directive.
• Directive Stat – Directive name and percentile statistic, such as P99, P90, and P50. Percentile (P) indicates how a value compares to others within the same period. For example, P90 is the 90^th percentile and means that 90 percent of the data within the period is lower than this value and 10 percent of the data is higher than this value.
• Latency(ms) – Number of milliseconds, averaged across all directives in the hour, until Alexa receives a response from the skill after Alexa sends a directive to the skill. Available for latency issue logs only.
• Success Rate – Percentage of directives that succeeded in the hour. Available for success rate issue logs only.
• Baseline – For latency: The baseline latency in milliseconds for the given percentile statistic. Amazon recommends a maximum latency of 1000 milliseconds for P90 and 800 milliseconds for P50 percentile.
  For success rate: The baseline success rate percentage. Amazon recommends a success rate of 97 percent.
• Diff – For latency: The difference in milliseconds between the actual latency and the baseline.
  For success rate: The percentage difference between the actual success rate and the baseline.
• Affected Utterances – Number of utterances that whose latency or success rate exceeds the baseline.

Error logs

Use the Capability Directives page to access and download the UPE data for a given skill. You can filter the logs by region, time interval, and aggregation period.

To download message IDs by error type

1. On the Analytics page, on the left pane, locate the Operational Metrics section, and then click Capability Directives.

2. To view a list of message IDs for a specific error type, open the Overview tab or the Error tab, and then on the User-perceived error summary chart, click the error type that you want to analyze.
   The following image shows an example Error tab on the Capability Directives page on the Alexa developer console.

   

3. To download the message ID list for the selected error type, under MESSAGE IDs, click the download button for the row that you want to troubleshoot. The screen shows up to 25 entries.
   The following image shows the hourly error count for the INTERNAL_ERROR error.

   

4. To download the summary error count, click the download button at the top of the page.
5. Save the downloaded CSV files to a convenient place.
   For details about the contents, see About the log files.

About the log file

You can troubleshoot UPE issues by using the message ID logs to find the message request and response in your skill logs. You can open the downloaded files in a spreadsheet editor.

Message ID log file

The message ID log file is a CSV file with one row for each message that caused an error. The log file contains the following fields:

• Date – Date and time in UTC format at which the error occurred for the request.
• Error Type – Error type or exception that occurred. For more details, see Error types.
• Success – Indicates whether the directive request succeeded or failed.
• MessageId – Unique identifier for the request or event. Use the message ID to find the associate logs from your skill to troubleshoot errors.

Summary log file

The summary log file is a CSV file with one row per error type, aggregated hourly. The log file contains the following fields:

• Date – Date and time at which the errors occurred. The time indicates the start of the hour.
• Error Type – Error type or exception that occurred. For more details, see Error types.
• Impacted Utterances/Error Count – Number of errors of the specified error type that occurred in the hour.

Related topics

• Analyze Your Skill Metrics
• Skill Metrics FAQ

---

---

Last updated: Sep 05, 2024