Goals

The walkthrough aims to achieve the following results:

  1. Having an InfluxDB container running on Docker, that users can access at localhost:8086
  2. Having a Telegraf container running on Docker, regularly writing timer series data in the InfluxDB container that we have set up. The time series data in this walkthrough are HTTP response for InfluxData’s websites.
  3. Expose config and database files outside of Docker containers. This is so that we can modify config files on the host machine to change the behaviours of InfluxDB and Telegraf.

Installation and Setup

Preparations. Install Docker on your machine, following instructions from Docker’s website. This walkthrough presumes that Docker is installed properly. This walkthrough also presumes basic knowledge on InfluxDB and command line usage.

This walkthrough is tried on macOS, and has everything stored in ~/influx.

Step 1. Install InfluxDB and Telegraf using the following command:

docker pull influxdb
docker pull telegraf

Step 2. Set up network. We need to build a network for the two containers to communicate with each other.

(Note: Telegraf will be started with host network. It seems necessary for the tutorial’s HTTP Response example, but I’m still investigating if it’s actually the case.)

To set up the network, we will be using bridge for the two containers to communicate. The command below sets up the network named influxdb-telegraf-net.

docker network create --driver bridge influxdb-telegraf-net

Step 3. Run InfluxDB with external persistence:

docker run -d --name=influxdb \
  -p 8086:8086 \
  -v ~/influx/config.yml:/etc/influxdb2/config.yml \
  -v ~/influx/influxdb:/var/lib/influxdb2 \
  --network=influxdb-telegraf-net \ 
  influxdb

The -p argument opens the port 8086 for us to connect using a browser. The -v arguments maps the config file and storage locations to a directory on the host machine. The --network argument attaches the container to the network that we created in Step 2.

Step 4. Configure InfluxDB using GUI.

In the browser, go to http://localhost:8086. Follow the prompts to set u initial account. For consistency in the tutorial, we have the following values:

Step 5. Gather API token. We will use the Admin token for the tutorial, but it should not be followed outside of this POC.

Step 6. Configure Telegraf.

Create file telegraf.conf under ~/influx/telegraf. This file follows TOML syntax.

[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  ## Token for authentication.
  token = "ADMIN_TOKEN_FROM_STEP_5"
  ## Organization is the name of the organization you wish to write to; must exist.
  organization = "ORG_NAME_FROM_STEP_4"
  ## Destination bucket to write into.
  bucket = "BUCKET_NAME_FROM_STEP_4"

# Configuration for telegraf agent. These values below are automatically generated.
[agent]
  interval = "20s"
  round_interval = true
  metric_batch_size = 1000
  metric_buffer_limit = 10000
  collection_jitter = "0s"
  flush_interval = "10s"
  flush_jitter = "0s"
  precision = ""

# HTTP/HTTPS request given an address a method and a timeout
[[inputs.http_response]]
  urls = [
	"https://influxdata.com",
	"https://influxdays.com"
  ]
  method = "HEAD"
  follow_redirects = true

Make sure to modify 3 things in the config file: your own token, organization name, and bucket name.

Values under [agent] group are provided by default. You get these values by following any other tutorials. These are mostly the default behaviours for Telegraf.

Under [[inputs.http_response]] is our input plug-in “HTTP Response”. This plug-in pings websites and records responses in InfluxDB. We are pinging two websites under InfluxData’s name. We use HEAD method since we are only interested in response time. The plus-in also follows page redirects as we configured, just for the longevity of this tutorial.

Step 7. Run Telegraf.

docker run -d --name=telegraf \
  -v ~/influx/telegraf:/etc/telegraf \
  --net=influxdb-telegraf-net \
  telegraf

Same as Step 3, we attach Telegraf container to the network, and map config files on the host machine’s directory.

Step 8. Check if data are flowing in. Log into the GUI and query the data in Explore.

Notes and Considerations

References