Usage Back to Top

Installation

We won’t cover further details how to properly setup Prometheus itself, we will only cover some basic setup based on docker-compose. But if you want to run this exporter without docker-compose you should be able to adopt that to your needs.

First of all we need to prepare a configuration for Prometheus that includes the exporter based on a static configuration with the container name as a hostname:

global:
  scrape_interval: 1m
  scrape_timeout: 10s
  evaluation_interval: 1m

scrape_configs:
- job_name: hcloud
  static_configs:
  - targets:
    - hcloud_exporter:9501

After preparing the configuration we need to create the docker-compose.yml within the same folder, this docker-compose.yml starts a simple Prometheus instance together with the exporter. Don’t forget to update the environment variables with the required credentials.

version: '2'

volumes:
  prometheus:

services:
  prometheus:
    image: prom/prometheus:latest
    restart: always
    ports:
      - 9090:9090
    volumes:
      - prometheus:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  hcloud_exporter:
    image: promhippie/hcloud-exporter:latest
    restart: always
    environment:
      - HCLOUD_EXPORTER_TOKEN=bldyecdtysdahs76ygtbw51w3oeo6a4cvjwoitmb
      - HCLOUD_EXPORTER_LOG_PRETTY=true

Since our latest tag always refers to the master branch of the Git repository you should always use some fixed version. You can see all available tags at DockerHub or Quay, there you will see that we also provide a manifest, you can easily start the exporter on various architectures without any change to the image name. You should apply a change like this to the docker-compose.yml file:

  hcloud_exporter:
-   image: promhippie/hcloud-exporter:latest
+   image: promhippie/hcloud-exporter:1.0.0
    restart: always
    environment:
      - HCLOUD_EXPORTER_TOKEN=bldyecdtysdahs76ygtbw51w3oeo6a4cvjwoitmb
      - HCLOUD_EXPORTER_LOG_PRETTY=true

If you want to access the exporter directly you should bind it to a local port, otherwise only Prometheus will have access to the exporter. For debugging purpose or just to discover all available metrics directly you can apply this change to your docker-compose.yml, after that you can access it directly at http://localhost:9501/metrics:

  hcloud-exporter:
    image: promhippie/hcloud-exporter:latest
    restart: always
+   ports:
+     - 127.0.0.1:9501:9501
    environment:
      - HCLOUD_EXPORTER_TOKEN=bldyecdtysdahs76ygtbw51w3oeo6a4cvjwoitmb
      - HCLOUD_EXPORTER_LOG_PRETTY=true

If you want to secure the access to the exporter you can provide a web config. You just need to provide a path to the config file in order to enable the support for it, for details about the config format look at the documentation section:

  hcloud_exporter:
    image: promhippie/hcloud-exporter:latest
    restart: always
    environment:
+     - HCLOUD_EXPORTER_WEB_CONFIG=path/to/web-config.json
      - HCLOUD_EXPORTER_TOKEN=bldyecdtysdahs76ygtbw51w3oeo6a4cvjwoitmb
      - HCLOUD_EXPORTER_LOG_PRETTY=true

If you want to provide the required secrets from a file it’s also possible. For this use case you can write the secret to a file on any path and reference it with the following format:

  hcloud_exporter:
    image: promhippie/hcloud-exporter:latest
    restart: always
    environment:
-     - HCLOUD_EXPORTER_TOKEN=bldyecdtysdahs76ygtbw51w3oeo6a4cvjwoitmb
+     - HCLOUD_EXPORTER_TOKEN=file://path/to/secret/file/with/token
      - HCLOUD_EXPORTER_LOG_PRETTY=true

Finally the exporter should be configured fine, let’s start this stack with docker-compose, you just need to execute docker-compose up within the directory where you have stored the prometheus.yml and docker-compose.yml.

That’s all, the exporter should be up and running. Have fun with it and hopefully you will gather interesting metrics and never run into issues. You can access the exporter at http://localhost:9501/metrics and Prometheus at http://localhost:9090.

Configuration

HCLOUD_EXPORTER_LOG_LEVEL

Only log messages with given severity, defaults to info

HCLOUD_EXPORTER_LOG_PRETTY

Enable pretty messages for logging, defaults to false

HCLOUD_EXPORTER_WEB_ADDRESS

Address to bind the metrics server, defaults to 0.0.0.0:9501

HCLOUD_EXPORTER_WEB_PATH

Path to bind the metrics server, defaults to /metrics

HCLOUD_EXPORTER_WEB_PPROF

Enable pprof debugging for server, defaults to false

HCLOUD_EXPORTER_WEB_TIMEOUT

Server metrics endpoint timeout, defaults to 10s

HCLOUD_EXPORTER_WEB_CONFIG

Path to web-config file

HCLOUD_EXPORTER_REQUEST_TIMEOUT

Request timeout as duration, defaults to 10s

HCLOUD_EXPORTER_TOKEN

Access token for the HetznerCloud API

HCLOUD_EXPORTER_COLLECTOR_FLOATING_IPS

Enable collector for floating IPs, defaults to true

HCLOUD_EXPORTER_COLLECTOR_IMAGES

Enable collector for images, defaults to true

HCLOUD_EXPORTER_COLLECTOR_PRICING

Enable collector for pricing, defaults to true

HCLOUD_EXPORTER_COLLECTOR_SERVERS

Enable collector for servers, defaults to true

HCLOUD_EXPORTER_COLLECTOR_SERVER_METRICS

Enable collector for server metrics, defaults to false

HCLOUD_EXPORTER_COLLECTOR_LOAD_BALANCERS

Enable collector for load balancers, defaults to true

HCLOUD_EXPORTER_COLLECTOR_SSH_KEYS

Enable collector for SSH keys, defaults to true

HCLOUD_EXPORTER_COLLECTOR_VOLUMES

Enable collector for volumes, defaults to false

Web Configuration

If you want to secure the service by TLS or by some basic authentication you can provide a YAML configuration file which follows the Prometheus toolkit format. You can see a full configuration example within the toolkit documentation.

Metrics

You can a rough list of available metrics below, additionally to these metrics you will always get the standard metrics exported by the Golang client of Prometheus. If you want to know more about these standard metrics take a look at the process collector and the Go collector.

hcloud_floating_ip_active{id, server, location, type, ip}

If 1 the floating IP is used by a server, 0 otherwise

hcloud_image_active{id, name, type, server, flavor, version}

If 1 the image is used by a server, 0 otherwise

hcloud_image_created_timestamp{id, name, type, server, flavor, version}

Timestamp when the image have been created

hcloud_image_deprecated_timestamp{id, name, type, server, flavor, version}

Timestamp when the image will be deprecated, 0 if not deprecated

hcloud_image_disk_bytes{id, name, type, server, flavor, version}

Size if the disk for the image in bytes

hcloud_image_size_bytes{id, name, type, server, flavor, version}

Size of the image in bytes

hcloud_pricing_floating_ip{currency, vat, type, location}

The cost of one floating IP per month

hcloud_pricing_image{currency, vat}

The cost of an image per GB/month

hcloud_pricing_loadbalancer_type{currency, vat, type, location}

The costs of a load balancer by type and location per month

hcloud_pricing_loadbalancer_type_traffic{currency, vat, type, location}

The costs of additional traffic per TB for a load balancer by type and location per month

hcloud_pricing_primary_ip{currency, vat, type, location}

The cost of one primary IP per month

hcloud_pricing_server_backup{}

Will increase base server costs by specific percentage if server backups are enabled

hcloud_pricing_server_type{currency, vat, type, location}

The costs of a server by type and location per month

hcloud_pricing_server_type_traffic{currency, vat, type, location}

The costs of additional traffic per TB for a server by type and location per month

hcloud_pricing_volume{currency, vat}

The cost of a volume per GB/month

hcloud_request_duration_seconds{collector}

Histogram of latencies for requests to the api per collector

hcloud_request_failures_total{collector}

Total number of failed requests to the api per collector

hcloud_server_backup{id, name, datacenter}

If 1 server backups are enabled, 0 otherwise

hcloud_server_cores{id, name, datacenter}

Server number of cores

hcloud_server_created_timestamp{id, name, datacenter}

Timestamp when the server have been created

hcloud_server_disk_bytes{id, name, datacenter}

Server disk in bytes

hcloud_server_included_traffic_bytes{id, name, datacenter}

Included traffic for the server in bytes

hcloud_server_incoming_traffic_bytes{id, name, datacenter}

Ingoing traffic to the server in bytes

hcloud_server_memory_bytes{id, name, datacenter}

Server memory in bytes

hcloud_server_metrics_cpu{id, name, datacenter}

Server CPU usage metric

hcloud_server_metrics_disk_read_bps{id, name, datacenter, disk}

Server disk write bytes/s metric

hcloud_server_metrics_disk_read_iops{id, name, datacenter, disk}

Server disk read iop/s metric

hcloud_server_metrics_disk_write_bps{id, name, datacenter, disk}

Server disk write bytes/s metric

hcloud_server_metrics_disk_write_iops{id, name, datacenter, disk}

Server disk write iop/s metric

hcloud_server_metrics_network_in_bps{id, name, datacenter, interface}

Server network incoming bytes/s metric

hcloud_server_metrics_network_in_pps{id, name, datacenter, interface}

Server network incoming packets/s metric

hcloud_server_metrics_network_out_bps{id, name, datacenter, interface}

Server network outgoing bytes/s metric

hcloud_server_metrics_network_out_pps{id, name, datacenter, interface}

Server network outgoing packets/s metric

hcloud_server_outgoing_traffic_bytes{id, name, datacenter}

Outgoing traffic from the server in bytes

hcloud_server_price_hourly{id, name, datacenter, vat}

Price of the server billed hourly in €

hcloud_server_price_monthly{id, name, datacenter, vat}

Price of the server billed monthly in €

hcloud_server_running{id, name, datacenter}

If 1 the server is running, 0 otherwise

hcloud_ssh_key{id, name, fingerprint}

Information about SSH keys in your HetznerCloud project

hcloud_volume_created{id, server, location, name}

Timestamp when the volume have been created

hcloud_volume_protection{id, server, location, name}

If 1 the volume is protected, 0 otherwise

hcloud_volume_size{id, server, location, name}

Size of the volume in GB

hcloud_volume_status{id, server, location, name}

If 1 the volume is availabel, 0 otherwise

Kubernetes Back to Top

Kubernetes

Currently we are covering the most famous installation methods on Kubernetes, you can choose between Kustomize and Helm.

Kustomize

We won’t cover the installation of Kustomize within this guide, to get it installed and working please read the upstream documentation. After the installation of Kustomize you just need to prepare a kustomization.yml wherever you like similar to this:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: hcloud-exporter

resources:
  - github.com/promhippie/hcloud_exporter//deploy/kubernetes?ref=master

configMapGenerator:
  - name: hcloud-exporter
    behavior: merge
    literals: []

secretGenerator:
  - name: hcloud-exporter
    behavior: merge
    literals: []

After that you can simply execute kustomize build | kubectl apply -f - to get the manifest applied. Generally it’s best to use fixed versions of the container images, this can be done quite easy, you just need to append this block to your kustomization.yml to use this specific version:

images:
  - name: quay.io/promhippie/hcloud-exporter
    newTag: 1.1.0

After applying this manifest the exporter should be directly visible within your Prometheus instance if you are using the Prometheus Operator as these manifests are providing a ServiceMonitor.

Helm

We won’t cover the installation of Helm within this guide, to get it installed and working please read the upstream documentation. After the installation of Helm you just need to execute the following commands:

helm repo add promhippie https://promhippie.github.io/charts
helm show values promhippie/hcloud-exporter
helm install hcloud-exporter promhippie/hcloud-exporter

You can also watch that available values and generally the details of the chart provided by us within our chart repository or on Artifacthub.

After applying this manifest the exporter should be directly visible within your Prometheus instance depending on your installation if you enabled the annotations or the service monitor.

Building Back to Top

As this project is built with Go you need to install Go first. The installation of Go is out of the scope of this document, please follow the official documentation. After the installation of Go you need to get the sources:

git clone https://github.com/promhippie/hcloud_exporter.git
cd hcloud_exporter/

All required tool besides Go itself are bundled, all you need is part of the Makefile:

make generate build

Finally you should have the binary within the bin/ folder now, give it a try with ./bin/hcloud_exporter -h to see all available options.

License Back to Top