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: jenkins
  static_configs:
  - targets:
    - jenkins_exporter:9506

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

  jenkins_exporter:
    image: promhippie/jenkins-exporter:latest
    restart: always
    environment:
      - JENKINS_EXPORTER_URL=https://jenkins.example.com
      - JENKINS_EXPORTER_USERNAME=octocat
      - JENKINS_EXPORTER_PASSWORD=p455w0rd
      - JENKINS_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:

  jenkins_exporter:
-   image: promhippie/jenkins-exporter:latest
+   image: promhippie/jenkins-exporter:1.0.0
    restart: always
    environment:
      - JENKINS_EXPORTER_URL=https://jenkins.example.com
      - JENKINS_EXPORTER_USERNAME=octocat
      - JENKINS_EXPORTER_PASSWORD=p455w0rd
      - JENKINS_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:9506/metrics:

  jenkins-exporter:
    image: promhippie/jenkins-exporter:latest
    restart: always
+   ports:
+     - 127.0.0.1:9506:9506
    environment:
      - JENKINS_EXPORTER_URL=https://jenkins.example.com
      - JENKINS_EXPORTER_USERNAME=octocat
      - JENKINS_EXPORTER_PASSWORD=p455w0rd
      - JENKINS_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:

  jenkins_exporter:
    image: promhippie/jenkins-exporter:latest
    restart: always
    environment:
+     - JENKINS_EXPORTER_WEB_CONFIG=path/to/web-config.json
      - JENKINS_EXPORTER_URL=https://jenkins.example.com
      - JENKINS_EXPORTER_USERNAME=octocat
      - JENKINS_EXPORTER_PASSWORD=p455w0rd
      - JENKINS_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:

  jenkins_exporter:
    image: promhippie/jenkins-exporter:latest
    restart: always
    environment:
-     - JENKINS_EXPORTER_USERNAME=octocat
-     - JENKINS_EXPORTER_PASSWORD=p455w0rd
+     - JENKINS_EXPORTER_USERNAME=file://path/to/secret/file/with/username
+     - JENKINS_EXPORTER_PASSWORD=file://path/to/secret/file/with/password
      - JENKINS_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:9506/metrics and Prometheus at http://localhost:9090.

Configuration

JENKINS_EXPORTER_LOG_LEVEL
Only log messages with given severity, defaults to info
JENKINS_EXPORTER_LOG_PRETTY
Enable pretty messages for logging, defaults to false
JENKINS_EXPORTER_WEB_ADDRESS
Address to bind the metrics server, defaults to 0.0.0.0:9506
JENKINS_EXPORTER_WEB_PATH
Path to bind the metrics server, defaults to /metrics
JENKINS_EXPORTER_WEB_PPROF
Enable pprof debugging for server, defaults to false
JENKINS_EXPORTER_WEB_TIMEOUT
Server metrics endpoint timeout, defaults to 10s
JENKINS_EXPORTER_WEB_CONFIG
Path to web-config file
JENKINS_EXPORTER_REQUEST_TIMEOUT
Timeout requesting Jenkins API, defaults to 5s
JENKINS_EXPORTER_URL
URL to access the Jenkins to scrape
JENKINS_EXPORTER_USERNAME
Username for the Jenkins authentication
JENKINS_EXPORTER_PASSWORD
Password for the Jenkins authentication
JENKINS_EXPORTER_COLLECTOR_JOBS
Enable collector for jobs, 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 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.

jenkins_job_buildable{name, path, class}
1 if the sjob is buildable, 0 otherwise
jenkins_job_color{name, path, class}
Color code of the jenkins job
jenkins_job_disabled{name, path, class}
1 if the job is disabled, 0 otherwise
jenkins_job_last_build{name, path, class}
Builder number for last build
jenkins_job_last_completed_build{name, path, class}
Builder number for last completed build
jenkins_job_last_failed_build{name, path, class}
Builder number for last failed build
jenkins_job_last_stable_build{name, path, class}
Builder number for last stable build
jenkins_job_last_successful_build{name, path, class}
Builder number for last successful build
jenkins_job_last_unstable_build{name, path, class}
Builder number for last unstable build
jenkins_job_last_unsuccessful_build{name, path, class}
Builder number for last unsuccessful build
jenkins_job_next_build_number{name, path, class}
Next build number for the job
jenkins_request_duration_seconds{collector}
Histogram of latencies for requests to the api per collector
jenkins_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: jenkins-exporter

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

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

secretGenerator:
  - name: jenkins-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/jenkins-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/jenkins-exporter
helm install jenkins-exporter promhippie/jenkins-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/jenkins_exporter.git
cd jenkins_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/jenkins_exporter -h to see all available options.

License Back to Top

This project is licensed under the Apache 2.0 license. For the license of the used libraries you have to check the respective sources.