3. Up and running: Install Prometheus, Promscale, and TimescaleDB

We recommend four methods to setup and install Promscale:

  1. TOBS - The Observability Stack for Kubernetes (recommended for kubernetes deployments)
  2. Docker (instructions detailed below)
  3. Helm
  4. Bare Metal

tip

See the Promscale github installation guide for more information on installation options.

For demonstration purposes, we will use Docker to get up and running with Promscale.

The easiest way to get started is by using Docker images. Make sure you have Docker installed on your local machine (Docker installation instructions).

The instructions below have 4 steps:

  1. Install TimescaleDB
  2. Install Promscale
  3. Install node_exporter
  4. Install Prometheus

Alternatively, you can skip to the bonus section which contains a docker-compose file for four components above: Skip to docker-compose file

warning

The instructions below are local testing purposes only and should not be used to set up a production environment.

3.1: Install TimescaleDB

First, let’s create a network specific to Promscale and TimescaleDB:

  1. docker network create --driver bridge promscale-timescaledb

Secondly, let’s install and spin up an instance of TimescaleDB in a docker container. This is where Promscale will store all metrics data scraped from Prometheus targets.

We will use a docker image which has thepromscale PostgreSQL extension already pre-installed:

  1. docker run --name timescaledb \
  2.     --network promscale-timescaledb \
  3.     -e POSTGRES_PASSWORD=<password> -d -p 5432:5432 \
  4.     timescaledev/timescaledb-ha:pg12-latest

The above commands create a TimescaleDB instanced named timescaledb (via the --name flag), on the network named promscale-timescale (via the --network flag), whose container will run in the background with the container ID printed after created (via the -d flag), with port-forwarding it to port 5432 on your machine (via the -p flag).

warning

We set the POSTGRES_PASSWORD environment variable (using the -e flag) in the command above. Please ensure to replace [password] with the password of your choice for the postgres superuser.

For production deployments, you will want to fix the docker tag to a particular version instead of pg12-latest

3.2: Install Promscale

Since we have TimescaleDB up and running, let’s spin up a Promscale instance, using the Promscale docker image available on Docker Hub:

  1. docker run --name promscale -d -p 9201:9201 \
  2. --network promscale-timescaledb \
  3. timescale/promscale:latest
  4. -db-uri postgres://postgres:<password>@timescaledb:5432/postgres?sslmode=allow

In the -db-uri flag above, the second mention of postgres after the double backslash refers to the the user we’re logging into the database as, <password> is the password for user postgres, and timescaledb is the name of the TimescaleDB container, installed in step 3.1. We can use the name timescaledb to refer to the database, rather than using its host address, as both containers are on the same docker network promscale-timescaledb.

Furthermore, note that the value <password> should be replaced with the password you set up for TimescaleDB in step 3.1 above.

warning

The setting ssl-mode=allow is for testing purposes only. For production deployments, we advise you to use ssl-mode=require for security purposes.

3.3: Start collecting metrics using node_exporter

node_exporter is a Prometheus exporter for hardware and OS metrics exposed by *NIX kernels, written in Go with pluggable metric collectors. To learn more about it, refer to the Node Exporter Github.

For the purposes of this tutorial, we need a service that will expose metrics to Prometheus. We will use the node_exporter for this purpose.

Install the the node_exporter on your machine by running the docker command below:

  1. docker run --name node_exporter -d -p 9100:9100 \
  2. --network promscale-timescaledb \
  3. quay.io/prometheus/node-exporter

The command above creates a node exporter instanced named node_exporter, which port-forwards its output to port 9100 and runs on the promscale-timescaledb network created in Step 3.1.

Once the Node Exporter is running, you can verify that system metrics are being exported by visiting its /metrics endpoint at the following URL: http://localhost:9100/metrics. Prometheus will scrape this /metrics endpoint to get metrics.

3.4: Install Prometheus

All that’s left is to spin up Prometheus.

First we need to ensure that our Prometheus configuration file prometheus.yml is pointing to Promscale and that we’ve properly set the scrape configuration target to point to our node_exporter instance, created in Step 3.3.

Here is a basic prometheus.yml configuration file that we’ll use for this tutorial. (More information on Prometheus configuration)

A basic prometheus.yml file for Promscale:

  1. global:
  2.  scrape_interval:     10s
  3.  evaluation_interval: 10s
  4. scrape_configs:
  5.  - job_name: prometheus
  6.    static_configs:
  7.      - targets: ['localhost:9090']
  8.  - job_name: node-exporter
  9.    static_configs:
  10.      - targets: ['node_exporter:9100']
  11. remote_write:
  12.   - url: "http://promscale:9201/write"
  13. remote_read:
  14.   - url: "http://promscale:9201/read"
  15.     read_recent: true

In the file above, we configure Prometheus to use Promscale as its remote storage endpoint by pointing both its remote_read and remote_write to Promscale URLs. Moreover, we set node-exporter as our target to scrape every 10s.

Next, let’s spin up a Prometheus instance using the configuration file above (assuming it’s called prometheus.yml and is in the current working directory), using the following command:

  1. docker run \
  2.     --network promscale-timescaledb \
  3.     -p 9090:9090 \
  4.     -v ${PWD}/prometheus.yml:/etc/prometheus/prometheus.yml \
  5.     prom/prometheus

BONUS: Docker compose file

To save time spinning up and running each docker container separately, here is a sampledocker-compose.yml file that will spin up docker containers for TimescaleDB, Promscale, node_exporter and Prometheus using the configurations mentioned in Steps 1-4 above.

warning

Ensure you have the Prometheus configuration file prometheus.yml in the same directory as docker-compose.yml

A sample docker-compose.yml file to spin up and connect TimescaleDB, Promscale, node_exporter and Prometheus: is available in the Promscale Github repo.

To use the docker-compose file above method, follow these steps:

  1. In docker-compose.yml, set <PASSWORD>, the password for superuser postgres in TimescaleDB, to a password of your choice.
  2. Run the command docker-compose up in the same directory as the docker-compose.yml file .
  3. That’s it! TimescaleDB, Promscale, Prometheus, and node-exporter should now be up and running.

Next step