ACK Analytics Service
You can use the ACK Analytics Service to collect, store, and analyze data about the performance and use of your ACK products. If you choose to collect logs and metrics from your ACK products, the ACK Analytics Service automatically collects and analyzes operational metrics from your ACK-based devices to ensure optimal health, security, and connection status. You can choose whether to enable collection of additional product logs, product metrics, Heartbeat Metrics, and registration metrics associated with your ACK products.
If you choose to collect these additional logs and metrics for your ACK products, the ACK Analytics Service identifies a standard set of product logs, as well as default Heartbeat Metrics and registration metrics. When you design your ACK product firmware in the ACK portal, you can define the specific product logs and metrics you wish to collect. If you choose to collect additional logs and metrics but do not define them, the ACK Analytics Service collects only the default product logs, Heartbeat Metrics, and registration metrics.
Logs and metrics from your ACK products are stored by the ACK Analytics Service. You can request access to your logs and metrics at any time. If you request assistance from ACK support engineers to help troubleshoot or resolve issues with your ACK products, Amazon may use your logs and metrics to fulfill that request.
Operational metrics
If you enable logs and metrics for your product, Amazon automatically collects and analyzes operational metrics from your ACK-based devices. ACK can then access these metrics to ensure optimal health, security, and connection status. Analysis of operational metrics allows Amazon to continually monitor for and proactively troubleshoot any issues that arise with device performance or Alexa service integration.
Amazon defines operational metrics based on the capabilities of your device, which may change over time. In general, each operational metric collected from your device includes metadata such as the fields listed in the following table.
| Field | Description |
|---|---|
|
Session ID |
Randomly generated ID refreshed with each factory reset of the device. |
|
ID |
Randomly generated UUID that ties together multiple device datapoints. |
|
marketplaceId |
ID of the marketplace in which the device is registered. This value is blank. |
|
CountryOfResidence |
Country in which the device is registered. This value is blank. |
|
OTA group |
String that represents the over-the-air (OTA) status of the device. |
|
Software version |
Firmware version of the ACK module. |
|
Platform |
Components on which a device chipset is based. |
|
Hardware |
Chipset used in a device. |
|
Device type ID |
Unique ID for each kind of device. |
Product logs
When you enable logs and metrics, ACK retains product logs to help you troubleshoot ACK device issues and determine their root causes. Logs are used to collect detailed information about the sequence of events and the code or workflow that leads to a given condition. Events documented in these logs are not captured by metrics. If you choose to collect product logs, they're stored by the ACK Analytics Service.
When you configure your ACK product firmware, you define the product logs you want to collect. Product logs should generally include the information necessary to help you debug device issues. To simplify development, the ACK Analytics Service pre-defines the schema for product logs, such as the schema shown in the following table, but you define the payload of the log type(s) you want to collect and determine how to command your device to upload its logs for debugging purposes. A set of device schema is available in the ACK portal.
| Field | Description |
|---|---|
|
DSN |
Device serial number (DSN). |
|
Device type |
Unique ID for each kind of device. |
|
Log type |
Type of device log. |
|
Timestamp |
Time at which the device generated the metric (epoch time). |
Product metrics
To learn how your ACK products are being used by end users and to detect if your devices have any issues, you can choose to collect product metrics. If you choose to collect product metrics, they're stored by the ACK Analytics Service.
When you configure your ACK product firmware, you define the product metrics you want to collect. For example, you can define product metrics that correspond to the capabilities your device offers its end customers, such as on/off or various device modes. Product metrics are uploaded to the ACK Analytics Service each time the designated event occurs. The ACK Analytics Service pre-defines the schema for product metrics, such as the fields shown in the following table, but you define the payload of each field to collect specified information. When you design your device firmware, a set of device schema is available in the ACK portal.
| Field | Description |
|---|---|
|
Id |
Randomly generated UUID that connects multiple datapoints for the same metric. |
|
Version |
Current schema iteration. |
|
BootTime |
Time at which the device was last booted up (epoch time). Note: This is closer to Wi-Fi connect time. |
|
SequenceNumber |
Counter that increments sequentially with each metric batch. |
|
Timestamp |
Time at which the device generated the specified metric (epoch time). |
|
MarketplaceId |
ID of the marketplace in which the device is registered. This value is blank. |
|
CountryOfResidence |
Country in which the device is registered. This value is blank. |
|
DeviceType |
Unique ID for each kind of device. |
|
DSN |
Serial number of the device. |
|
MetricType |
Category of the metric. |
|
DataType |
Data type of the metric value. |
|
Name |
Name of the metric. |
|
Value |
Value of the metric. |
Heartbeat Metrics
You can choose to collect Heartbeat Metrics, which are engagement metrics that provide key information to help you troubleshoot ACK products and understand customer device usage patterns. Heartbeat Metrics for an ACK product are PowerOn (Is the device receiving power?) and Wi-Fi Connected (Is the device connected to Wi-Fi?). If you choose to collect logs and metrics for your ACK product, these Heartbeat Metrics, as described in the following table, are collected from your ACK products and uploaded to the ACK Analytics Service each time a device event is captured.
| Field | Description |
|---|---|
|
device_record_date |
Date on which the device generated the metric (epoch day). |
|
device_record_time |
Time at which the device generated the metric (epoch time). |
|
DSN |
Device serial number. |
|
device_type |
Identified kind of device. |
|
metric_name |
Name of the metric. |
|
software_version |
Firmware version of the ACK module. |
|
reason_code |
For device actions, this field is always blank. For appliance actions (from HMCU), indicates whether the action is triggered by manual action or by voice. |
Registration metrics
You can choose to collect registration metrics, which are metrics that identify the registration status of your ACK products. You can use this metric to monitor the registration rate of your ACK products over time and identify potential issues if the registration status shows a sudden or unexpected change.
If you choose to collect ACK product logs and metrics, this data is collected when you register, de-register, or re-register a device. The data is stored by the ACK Analytics Service. Registration metrics are described in the following table.
| Field | Description |
|---|---|
|
event_complete_date |
Date of the event (epoch day). |
|
event_complete_time |
Time of the event (epoch time). |
|
event_type |
Kind of event. If a device is re-registered (without explicitly being de-registered), a de-register metric is still created. |
|
device_serial_number |
DSN associated with the event. |
|
thing_name |
IoT device identifier. |
Data management
Through the ACK Analytics Service, you can access, delete, and manage the retention period of the logs and metrics stored for your ACK products.
- Access – In the ACK portal, you can request a copy of your ACK logs and metrics for either an individual device or a group of products. You can define the group of ACK products based on the capability or a particular log or metric. To submit a data request from the ACK developer portal, navigate to the Product page and then choose the Data settings tab. If you request data for a particular device, you'll receive an email with a link to the requested data within five business days. The link expires after seven days.
- Deletion – You can delete your ACK logs and metrics for all devices at once or for an individual device. A deletion request will result in the deletion of all logs and metrics associated with the specified device but does not de-register the device.
- Retention – You determine how long to store ACK product logs and metrics in the ACK portal. The default retention period is 365 days, but you can set your preferred retention period when you configure the logs and metrics for your device or at any time thereafter. Shortening the retention period automatically deletes logs and metrics older than the specified period.
Data access and security
If you open a troubleshooting ticket for help with your ACK product, in order to fulfill your request, Amazon ACK support engineers are granted access to the logs and metrics associated with your devices. This access lasts until the troubleshooting request is closed.
Logs and metrics from your ACK products are encrypted in transit and at rest using industry standard encryption protocols.
Related topics
Last updated: Nov 27, 2023