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: dockerhub
  static_configs:
  - targets:
    - dockerhub_exporter:9505

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 envrionment 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

  dockerhub_exporter:
    image: promhippie/dockerhub-exporter:latest
    restart: always
    environment:
      - DOCKERHUB_EXPORTER_USERNAME=octocat
      - DOCKERHUB_EXPORTER_PASSWORD=p455w0rd
      - DOCKERHUB_EXPORTER_ORG=promhippie
      - DOCKERHUB_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:

  dockerhub_exporter:
-   image: promhippie/dockerhub-exporter:latest
+   image: promhippie/dockerhub-exporter:1.0.0
    restart: always
    environment:
      - DOCKERHUB_EXPORTER_USERNAME=octocat
      - DOCKERHUB_EXPORTER_PASSWORD=p455w0rd
      - DOCKERHUB_EXPORTER_ORG=promhippie
      - DOCKERHUB_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:9505/metrics:

  dockerhub-exporter:
    image: promhippie/dockerhub-exporter:latest
    restart: always
+   ports:
+     - 127.0.0.1:9505:9505
    environment:
      - DOCKERHUB_EXPORTER_USERNAME=octocat
      - DOCKERHUB_EXPORTER_PASSWORD=p455w0rd
      - DOCKERHUB_EXPORTER_ORG=promhippie
      - DOCKERHUB_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:

  dockerhub_exporter:
    image: promhippie/dockerhub-exporter:latest
    restart: always
    environment:
+     - DOCKERHUB_EXPORTER_WEB_CONFIG=path/to/web-config.json
      - DOCKERHUB_EXPORTER_USERNAME=octocat
      - DOCKERHUB_EXPORTER_PASSWORD=p455w0rd
      - DOCKERHUB_EXPORTER_ORG=promhippie
      - DOCKERHUB_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:

  dockerhub_exporter:
    image: promhippie/dockerhub-exporter:latest
    restart: always
    environment:
-     - DOCKERHUB_EXPORTER_USERNAME=octocat
-     - DOCKERHUB_EXPORTER_PASSWORD=p455w0rd
+     - DOCKERHUB_EXPORTER_USERNAME=file://path/to/secret/file/with/username
+     - DOCKERHUB_EXPORTER_PASSWORD=file://path/to/secret/file/with/password
      - DOCKERHUB_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:9505/metrics and Prometheus at http://localhost:9090.

Configuration

DOCKERHUB_EXPORTER_LOG_LEVEL

Only log messages with given severity, defaults to info

DOCKERHUB_EXPORTER_LOG_PRETTY

Enable pretty messages for logging, defaults to false

DOCKERHUB_EXPORTER_WEB_ADDRESS

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

DOCKERHUB_EXPORTER_WEB_PATH

Path to bind the metrics server, defaults to /metrics

DOCKERHUB_EXPORTER_WEB_PPROF

Enable pprof debugging for server, defaults to false

DOCKERHUB_EXPORTER_WEB_TIMEOUT

Server metrics endpoint timeout, defaults to 10s

DOCKERHUB_EXPORTER_WEB_CONFIG

Path to web-config file

DOCKERHUB_EXPORTER_REQUEST_TIMEOUT

Timeout requesting DockerHub API, defaults to 5s

DOCKERHUB_EXPORTER_USERNAME

Username for the DockerHub authentication

DOCKERHUB_EXPORTER_PASSWORD

Password for the DockerHub authentication

DOCKERHUB_EXPORTER_ORG

Organizations to scrape metrics from, comma-separated list

DOCKERHUB_EXPORTER_USER

Users to scrape metrics from, comma-separated list

DOCKERHUB_EXPORTER_REPO

Repositories to scrape metrics from, comma-separated list

DOCKERHUB_EXPORTER_COLLECTOR_REPOS

Enable collector for repos, defaults to true

Web Configuration

If you want to secure the service by TLS or by some basic authentication you can provide a YAML configuration file whch follows the Prometheus toolkit format. You can see a full configration 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.

dockerhub_repo_automated{owner, name}

Defines if the repository builds automatically

dockerhub_repo_collaborators{owner, name}

How many collaborators are working on that repo

dockerhub_repo_migrated{owner, name}

Hsve this repository been migrated

dockerhub_repo_private{owner, name}

Is the repository private or public

dockerhub_repo_pulls{owner, name}

How often have this repository been pulled

dockerhub_repo_stars{owner, name}

How often have this repository been stared

dockerhub_repo_status{owner, name}

What is the current status of the repository

dockerhub_repo_updated{owner, name}

A timestamp when the repository have been updated

dockerhub_request_duration_seconds{collector}

Histogram of latencies for requests to the api per collector

dockerhub_request_failures_total{collector}

Total number of failed requests to the api per collector

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: dockerhub-exporter

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

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

secretGenerator:
  - name: dockerhub-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/dockerhub-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/dockerhub-exporter
helm install dockerhub-exporter promhippie/dockerhub-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/dockerhub_exporter.git
cd dockerhub_exporter/

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

make generate build

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

License Back to Top