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.