From 59677c4bf2bee1f2c04faf78d4365d2a8fa45e4c Mon Sep 17 00:00:00 2001 From: Ashay Vipinkumar Date: Tue, 23 Nov 2021 15:30:09 -0800 Subject: [PATCH] Documentation --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++---- gdk-config.json | 6 ++--- 2 files changed, 66 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 847260c..466e16c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,68 @@ -## My Project +## Greengrass Labs InfluxDBPublisher Component - `aws.greengrass.labs.telemetry.InfluxDBPublisher` -TODO: Fill this README out! +## 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 ](https://github.com/awslabs/aws-greengrass-labs-database-influxdb), which starts and provisions a managed InfluxDB instance. -Be sure to: +At a high level, the component will do the following: -* Change the title in this README -* Edit your repository description on GitHub +1. Pull down the [Nucleus Telemetry Emitter component plugin](https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html), 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.database.InfluxDB` and `aws.greengrass.labs.dashboard.Grafana` components to persist and visualize Greengrass System Telemetry data. +* [aws.greengrass.labs.database.InfluxDB](https://github.com/awslabs/aws-greengrass-labs-database-influxdb) +* [aws.greengrass.labs.dashboard.Grafana](https://github.com/awslabs/aws-greengrass-labs-dashboard-grafana) + +## 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](https://docs.aws.amazon.com/greengrass/v2/developerguide/interprocess-communication.html#ipc-authorization-policies), required for InfluxDB secret retrieval over pub/sub. + * The default for this component allows for publish access to `greengrass/influxdb/token/request` and subscribe access to `greengrass/influxdb/token/response` + +## Setup +* This component requires no additional setup, 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](https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html). + * 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" + } + ``` + +## 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. + * See the [local pub/sub documentation to learn more](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-publish-subscribe.html). +* The component expects messages to consist of a JSON array in the following format. [See the Nucleus Emitter output](https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html#nucleus-emitter-component-output-data) for a full example. + ``` + [{ + "A": "", + "N": "", + "NS": "", + "TS": , + "U": "", + "V": + }, + ... + ] + ``` + * `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](CONTRIBUTING.md#security-issue-notifications) for more information. @@ -15,3 +71,5 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform This project is licensed under the Apache-2.0 License. +## Troubleshooting +* Troubleshooting for this component is mainly the same as for `aws.greengrass.labs.database.InfluxDB`. Please see [its troubleshooting guide here.](https://github.com/awslabs/aws-greengrass-labs-database-influxdb/blob/main/README.md#troubleshooting) diff --git a/gdk-config.json b/gdk-config.json index a7518bc..9bbf9e7 100644 --- a/gdk-config.json +++ b/gdk-config.json @@ -2,13 +2,13 @@ "component" :{ "aws.greengrass.labs.telemetry.InfluxDBPublisher": { "author": "AWS IoT Greengrass", - "version": "LATEST", + "version": "NEXT_PATCH", "build": { "build_system": "zip" }, "publish": { - "bucket": "", - "region": "" + "bucket": "", + "region": "" } } },