feat: New Airthings input plugin

[marcgeld]

Use Case

Airthings (https://www.airthings.com/) is supplying an API that allows you to access the data collected from sensors that indoor air quality and mainly the gas radon. We would like to have a Telegraf input plugin that exposes Airthings metrics Expose metrics for Airthings in Telegraf collector to enable processing and aggregation of Airthings sensor data.

Expected behavior

In the near future, I will propose PR which adds a new plugin I have created. The plugin will be able to fetch Airthings metrics from the Airthings API.

Actual behavior

Currently, it is not possible to gather and expose Airthings metrics.

Additional info

Airthings REST API developer docs: https://developer.airthings.com/docs/api-getting-started/index.html Info about the the Airthings products: https://www.airthings.com/.

[reimda]

Looking forward to your PR. Does Airthings provide a rest API or something more custom? Where can we find the API specifications? Thanks!

[marcgeld]

Hi, you find the Airthings REST API here https://developer.airthings.com/docs/api-getting-started/index.html and more about the the Airthings products here https://www.airthings.com. I'll submit the PR as soon as possible, but will have a friend review the code (before you do :-) ).

[slai]

It would be a better user experience with the proposed plugin, but for anyone wanting to get something working now, I've successfully used the following input plugin config -

[[inputs.http]]

  ## One or more URLs from which to read formatted metrics
  urls = [
    # 1234567890 is the serial number for the AirThings device
    "https://ext-api.airthings.com/v1/devices/1234567890/latest-samples"
  ]

  ## HTTP method
  method = "GET"

  ## OAuth2 Client Credentials Grant
  # TODO: replace client_id and client_secret with your values from the AirThings web console
  client_id = "${AIRTHINGS_CLIENT_ID}"
  client_secret = "${AIRTHINGS_CLIENT_SECRET}"
  token_url = "https://accounts-api.airthings.com/v1/token"
  scopes = ["read:device:current_values"]

  ## Amount of time allowed to complete the HTTP request
  timeout = "5s"

  ## Data format to consume.
  ## Each data format has its own unique set of configuration options, read
  ## more about them here:
  ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md
  data_format = "json"

  ## Query is a GJSON path that specifies a specific chunk of JSON to be
  ## parsed, if not specified the whole document will be parsed.
  ##
  ## GJSON query paths are described here:
  ##   https://github.com/tidwall/gjson/tree/v1.3.0#path-syntax
  json_query = "data"

  ## Time key is the key containing the time that should be used to create the
  ## metric.
  json_time_key = "time"

  ## Time format is the time layout that should be used to interpret the json_time_key.
  ## The time must be `unix`, `unix_ms`, `unix_us`, `unix_ns`, or a time in the
  ## "reference time".  To define a different format, arrange the values from
  ## the "reference time" in the example to match the format you will be
  ## using.  For more information on the "reference time", visit
  ## https://golang.org/pkg/time/#Time.Format
  ##   ex: json_time_format = "Mon Jan 2 15:04:05 -0700 MST 2006"
  ##       json_time_format = "2006-01-02T15:04:05Z07:00"
  ##       json_time_format = "01/02/2006 15:04:05"
  ##       json_time_format = "unix"
  ##       json_time_format = "unix_ms"
  json_time_format = "unix"

  ## Timezone allows you to provide an override for timestamps that
  ## don't already include an offset
  ## e.g. 04/06/2016 12:41:45
  ##
  ## Default: "" which renders UTC
  ## Options are as follows:
  ##   1. Local               -- interpret based on machine localtime
  ##   2. "America/New_York"  -- Unix TZ values like those found in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  ##   3. UTC                 -- or blank/unspecified, will return timestamp in UTC
  json_timezone = "UTC"

  # example payload (from a View Plus), after unwrapping from 'data' key (see json_query above)
  # {
  #     'time': 1699548910,
  #     'battery': 0,
  #     'co2': 763.0,
  #     'humidity': 45.0,
  #     'pm1': 0.0,
  #     'pm25': 0.0,
  #     'pressure': 892.3,
  #     'radonShortTermAvg': 20.0,
  #     'relayDeviceType': 'hub',
  #     'temp': 16.0,
  #     'voc': 39.0
  # }

  # drop the text field that doesn't really change
  fielddrop = ["relayDeviceType"]