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.