/aws-greengrass-labs-telemetry-influxdbpublisher

The AWS IoT Greengrass Labs InfluxDBPublisher Component (aws.greengrass.labs.telemetry.InfluxDBPublisher) allows you to forward Greengrass system health telemetry and other custom telemetry to InfluxDB.

Primary LanguagePython

Greengrass Labs InfluxDBPublisher Component - aws.greengrass.labs.telemetry.InfluxDBPublisher

Overview

This AWS IoT Greengrass component allows you to forward Greengrass telemetry to InfluxDB. It has a dependency on the aws.greengrass.labs.database.InfluxDB Greengrass component , which starts and provisions a managed InfluxDB instance.

At a high level, the component will do the following:

  1. Pull down the Nucleus Telemetry Emitter component plugin, which publishes Greengrass System Telemetry data to the local pub/sub topic $local/greengrass/telemetry at a configurable rate.
  2. Send a request to the IPC topic greengrass/influxdb/token/request (configurable) to retrieve InfluxDB credentials and metadata from aws.greengrass.labs.database.InfluxDB
  3. Receive a message on the IPC topic greengrass/influxdb/token/response (configurable).
  4. Use the retrieved credentials to connect to InfluxDB.
  5. Set up a subscription to the $local/greengrass/telemetry topic and forward all telemetry messages to InfluxDB.

This component works together with the aws.greengrass.labs.dashboard.InfluxDBGrafana, aws.greengrass.labs.database.InfluxDB and aws.greengrass.labs.dashboard.Grafana components to persist and visualize Greengrass System Telemetry data. The aws.greengrass.labs.dashboard.InfluxDBGrafana component automates the setup of Grafana with InfluxDB to provide a "one-click" experience, but this component still needs to be configured first before creation. See the Setup section below for instructions.

Configuration

  • TokenRequestTopic- the topic to send a request to in order to retrieve InfluxDB credentials

    • (string)
    • default: greengrass/influxdb/token/request

  • TokenResponseTopic- the topic to subscribe to in order to receive the response with InfluxDB credentials

    • (string)
    • default: greengrass/influxdb/token/response

  • accessControl - Greengrass Access Control Policy, required for InfluxDB secret retrieval over pub/sub.

    • A default accessControl policy allowing publish access to the greengrass/influxdb/token/request topic and subscribe access to the greengrass/influxdb/token/response has been included and requires no further configuration

Setup

  • This component requires no additional configuration, unless the request/response topics are modified in aws.greengrass.labs.database.InfluxDB
  • When deployed, this component will automatically begin forwarding telemetry from the Nucleus Telemetry Emitter component plugin.
    • Since the default publish interval for the Nucleus Telemetry Emitter is 60 seconds, you may want to configure that component during deployment to have a lower publish interval with a configuration update similar to the following (which sets it to 5 seconds). Note that smaller publish intervals may result in higher CPU usage on your device. 
      {
"telemetryPublishIntervalMs": "5000"
}

Prerequisites

  1. Setup the GDK CLI, Greengrass, and aws.greengrass.labs.database.InfluxDB using the instructions here.

Component Setup

  1. Pull down the component in a new directory using the GDK CLI. 
    mkdir aws-greengrass-labs-telemetry-influxdbpublisher; cd aws-greengrass-labs-telemetry-influxdbpublisher
gdk component init --repository aws-greengrass-labs-telemetry-influxdbpublisher
  2. Use the GDK CLI to build the component to prepare for publishing. 
    gdk component build
  3. Use the GDK CLI to create a private component. 
    gdk component publish

Sending Custom Telemetry

  • This component listens to all telemetry on the $local/greengrass/telemetry topic and forwards it to InfluxDB.
  • You can also send your own custom telemetry to this topic from your own Greengrass component to have it forwarded to InfluxDB.
  • The component expects messages to consist of a JSON array in the following format. See the Nucleus Emitter output for a full example. 
    [{
"A": "<Aggregation Type>",
"N": "<Metric Name>",
"NS": "<Metric Namespace>",
"TS": <Metric Timestamp>,
"U":  "<Metric Unit>",
"V":  <Metric Value>
},
...
]
    • A - The aggregation type for the metric.
    • N- The name of the metric.
    • NS- The metric namespace.
    • TS- The timestamp of when the data was gathered. (ms since Unix Epoch start time)
    • U - The unit of the metric value.
    • V - The metric value.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

Troubleshooting