Download Message IDs for Troubleshooting

You can use data available under Operational Metrics on the Analytics page to troubleshoot skill failures and latency issues in smart home and video skills. When a user asks Alexa to control their smart device, Alexa sends a directive request to your smart home skill to trigger a capability, for example, turn on a light. Operational metrics show the latency and success rate metrics and any issues that impact customers. For details about these metrics, see Operational metrics.

Learn how to download and view your message IDs and associated metadata, such as latency issues, errors, and exceptions, to help you debug skill failures.

Download your message ID logs

Use the Alexa developer console to access your skill metrics and download your message IDs and associated metadata for a given skill.

To download your message ID logs

  1. Follow the instructions in View Skill Metrics to access the Alexa Analytics Dashboard and view the metrics for one of your skills.

  2. Decide which method you want to use to download your message ID logs:

    • Download message IDs by category – Apply your own filter criteria to download a set of message IDs for your skill:

      1. On the left navigation, locate the Operational Metrics heading, and then click Capability Directives.
      2. On the right side of the report, below the Refresh button, click the Download Message IDs link, as shown in the following image:
        Download Message IDs
        Download Message IDs
      3. A Download Message IDs dialog opens with blank filter criteria fields:
      Download Message IDs Dialog
      Download Message IDs Dialog

    • Download message IDs from a chart – Automatically create filter criteria for your set of message IDs by exporting your message IDs from a Capability Directives chart. For more details about Capability Directives charts, see Operational Metrics:

      1. Find the Capability Directives chart that you want to use to export your message IDs.
      2. On the Capability Directives chart that you selected, click the Export chart button:
        Export chart button
        Export chart button
      3. From the Export chart button menu, click the Download Message IDs link to open a Download Message IDs dialog that has been auto-populated with the filter criteria used to create the chart:
      Populated Download Message IDs Dialog
      Populated Download Message IDs Dialog

  3. On the Download Message IDs dialog, select or modify the following search 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 timestamp (in UTC) to apply to the search filter for message IDs.
      • Duration – The duration to use to calculate a window for the time line. Valid values are 5 minutes, 10 minutes, 15 minutes, 30 minutes, 45 minutes, and 1 Hour.
    • Response Type (Required) – Select the type of responses to include in your search results:
      • Skill Failure – Requests to a skill that were categorized as failures.
      • Skill Success – Requests to a skill that were 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 while Alexa processes the response from your skill. The following two available exceptions are a subset of Alexa exceptions:
        • 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 ms) to filter your search results by response latency. Only message IDs with latencies greater than or equal to the threshold are available for download.
  4. Click the Download button to download the top 20 message IDs and metadata that meet the search criteria to a CSV file.

About the message ID log file

After downloading the CSV file of your message ID log, you can open the file in a spreadsheet editor. The CSV file contains the following fields:

  • Timestamp(UTC) – Time in UTC format that the user invoked the skill.
  • Skill ID – Amazon 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 capability associated with the skill invocation.
  • Directive – Alexa directive associated with the skill invocation.
  • 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 from the time until Alexa receives a response from your skill after sending a request to your skill.
  • Error Type – Error thrown by the skill. For a complete list of Error Types, see the Alexa.ErrorResponse Interface.
  • Exception Name – Alexa-side exception. Supported exceptions for the Message ID logs are SKILL_RESPONSE_TIMEOUT_EXCEPTION and INVALID_SKILL_RESPONSE_EXCEPTION.

Last updated: Apr 25, 2023