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. The ACK Analytics Service enables collection of Product Logs, Product Metrics, Heartbeat Metrics, and Registration Metrics associated with your ACK products. You can choose whether to enable collection of logs and metrics for your ACK products when designing the firmware for your ACK Product. If you choose to collect logs and metrics for your ACK product, the ACK Analytics Service identifies a standard set of Product Logs and Product Metrics and default Heartbeat Metrics and Registration Metrics. You can define the specific Product Logs and Product Metrics you wish to collect when designing the firmware for your ACK product in the ACK Portal. If you choose to collect logs and metrics but do not define Product Logs and Product Metrics for your ACK products, the ACK Analytics service will collect only the default Heartbeat Metrics and Registration Metrics.

Logs and metrics from your ACK products are stored in 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, we may use your logs and metrics to fulfill that request.

Product logs

You can choose to collect Product Logs to help you root cause and troubleshoot device issues with your ACK products. Logs are used to collect detailed information about events occurring within your device’s system that may not be captured by metrics. If you choose to collect Product Logs, they will be stored in the ACK Analytics Service.

You define Product Logs you wish to collect when configuring the firmware for your ACK product. Generally, Product Logs should be defined to include the information necessary to help you debug device issues. To simplify development, ACK Analytics Service pre-defines the schema for Product Logs, such as the schema shown in the table below, but you define the payload of the log type(s) you wish to collect, how to command your devices to upload its logs for debugging purposes, and how frequently logs are sent to the ACK Analytics Service. The schema for your device will be available in the ACK Portal when designing the firmware for your device.

Field Description

DSN

Device Serial Number (DSN).

Device Type

The unique id for each device type.

Log Type

The type of log for each device.

Timestamp

The timestamp the device generated the metric (epoch time).

Product metrics

You can choose to collect Product Metrics to collect information about how your ACK products are being used by end users and to detect if your devices are experiencing issues. If you choose to collect Product Metrics, they will be stored in the ACK Analytics Service.

You define the Product Metrics you wish to collect when configuring the firmware for your ACK product. For example, you can define Product Metrics to correspond to the capabilities your device offers for end customers, such as on/off or various modes of your device. Product Metrics will be uploaded to the ACK Analytics Service each time the event being measured occurs. The ACK Analytics Service pre-defines the schema for Product Metrics, such as the schema shown in the table below, but you define the payload of each field to collect the information you wish to collect. The schema for your device will be available in the ACK Portal when designing the firmware for your device.

Field Description

Id

A randomly generated UUID to tie together multiple datapoints belonging to the same metric.

Version

The current schema version.

BootTime

The timestamp at which the device last booted (epoch time). Note: this is closer to Wi-Fi connect time.

SequenceNumber

A counter which increments sequentially with each metric batch.

Timestamp

The timestamp at which the device generated the metric (epoch time).

MarketplaceId

The marketplaceId in which the device is registered. This value is blank.

CountryOfResidence

The country in which the device is registered. This value is blank.

DeviceType

The unique id for each device type.

DSN

The DSN of the device.

MetricType

A categorization of the metric.

DataType

The data type of the metric value.

Name

The name of the metric.

Value

The value of the metric.

Heartbeat metrics

You can choose to collect Heartbeat Metrics, which are engagement metrics that provide key information to help troubleshoot your ACK products and further understand customer usage patterns with their devices. 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 table below, will be collected from your ACK products and uploaded to the ACK Analytics Service each time an event is captured from the device.

Field Description

device_record_date

The date at which the device generated the metric (epoch day).

device_record_time

The timestamp at which the device generated the metric (epoch time).

DSN

The DSN of the device.

device_type

The identified of the device type.

metric_name

The name of the metric.

software_version

The 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 was 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 rate of registrations of your ACK products over time and identify potential issues if the registration status shows a sudden and unexpected change. If you choose to collect logs and metrics for your ACK product, Registration Metrics, as described in the table below, will be collected from your ACK products upon registration of a device and any subsequent de-registration or re-registration of a device and stored in the ACK Analytics Service.

Field Description

event_complete_date

The date of the event (epoch day).

event_complete_time

The timestamp of the event (epoch time)

event_type

The type of the event that occurred. If a device is re-registered (without explicitly being de-registered), a de-register metric will still be created.

device_serial_number

The DSN about which the event is.

thing_name

The IoT identifier for the device.

Data management

Through the ACK Analytics Service, you can access, delete, and manage the retention period of the logs and metrics stored from your ACK products.

  • Access – You can request a copy of the logs and metrics associated with your ACK products in the ACK Portal, either (a) for an individual device, or (b) for groups of your ACK products. You can define the group of ACK products based on 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 a copy of data for a particular device, you will receive an email with a link to the requested data within five business days. The link expires after seven days.
  • Delete – You can delete the logs and metrics associated with your ACK products either for all devices at once or for an individual device. Requesting deletion will delete all logs and metrics associated with the device but will not de-register the device.
  • Retention – You determine how long to store logs and metrics from your ACK products in the ACK Portal. The default retention period for logs and metrics is 365 days but you can set your preferred retention period in the ACK Portal upon configuring the logs and metrics for your device or at any time thereafter. Shortening the retention period will automatically delete logs and metrics older than that period.

Data access and security

If you open a troubleshooting ticket for help with your ACK product, Amazon ACK support engineers will be granted access to logs and metrics associated with your devices to complete the support request. This access will last 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.