How to Monitor Jenkins Builds with Prometheus

If you’ve ever been paged at 2 AM because a deployment silently failed, or spent an afternoon digging through Jenkins console logs trying to figure out why builds have been getting slower over the past month, you already understand why monitoring matters. Jenkins on its own gives you a build history page and some plugins for basic stats, but it isn’t built for the kind of time-series monitoring, alerting, and dashboarding that a serious DevOps setup needs. That’s where Prometheus comes in.

This guide covers exactly how to expose Jenkins metrics, scrape them with Prometheus, and visualize them — with real configuration examples you can drop straight into your environment.

Why Monitor Jenkins with Prometheus?

Prometheus is a time-series monitoring system that pulls (scrapes) metrics from configured targets at regular intervals, stores them efficiently, and lets you query them with PromQL. Pairing it with Jenkins gives you visibility into things Jenkins doesn’t surface well on its own:

• Build duration trends over weeks or months
• Queue length and executor utilization
• Job success/failure rates
• JVM health (heap usage, garbage collection pauses) of the Jenkins controller itself
• Plugin and node health

Combined with Grafana and Alertmanager, you get dashboards your whole team can watch and alerts that fire before a problem becomes an outage.

Jenkins Architecture Context

To understand what you’re monitoring, it helps to recall how Jenkins is structured. A Jenkins controller schedules and coordinates jobs; agents (formerly “slaves”) execute the actual build steps. Each executor slot on an agent can run one build at a time. When you monitor Jenkins, you’re really watching three layers: the JVM the controller runs on, the queue and executor scheduling logic, and the individual job/build results.

Step 1: Install the Prometheus Metrics Plugin

1. In Jenkins, go to Manage Jenkins > Plugins > Available Plugins
2. Search for Prometheus metrics
3. Install it and restart Jenkins

Once installed, Jenkins automatically exposes a /prometheus endpoint (by default at http://your-jenkins-url/prometheus) with metrics in the standard Prometheus text exposition format.

You can verify it’s working with:

curl http://your-jenkins-url/prometheus/

You should see a long list of metrics like:

default_jenkins_builds_duration_milliseconds_summary{jenkins_job="my-pipeline"} 45231.0
default_jenkins_queue_size_value 2.0
default_jenkins_node_count_value 5.0
default_jenkins_executor_count_value 10.0
jvm_memory_bytes_used{area="heap"} 512482816.0

Step 2: Configure Plugin Options (Optional but Recommended)

Go to Manage Jenkins > System > Prometheus and adjust:

• Path: change from the default /prometheus if you want a different endpoint
• Default namespace: prefixes all metrics, useful if you run multiple Jenkins instances
• Collecting metrics period in seconds: how frequently Jenkins recalculates internal stats
• Use authenticated endpoint: enable this in production so the metrics endpoint isn’t wide open

If you enable authentication, create an API token for a service account and configure Prometheus to use it in its scrape config.

Step 3: Install and Configure Prometheus

If you don’t already have Prometheus running, here’s a minimal Docker-based setup:

docker run -d --name prometheus -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus

Your prometheus.yml needs a scrape job pointing at Jenkins:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'jenkins'
    metrics_path: '/prometheus/'
    static_configs:
      - targets: ['jenkins-host:8080']

If you enabled authentication on the Jenkins endpoint, add basic auth:

scrape_configs:
  - job_name: 'jenkins'
    metrics_path: '/prometheus/'
    basic_auth:
      username: 'prometheus-svc'
      password: 'your-api-token'
    static_configs:
      - targets: ['jenkins-host:8080']

Restart Prometheus (or send it a SIGHUP) to pick up the config, then check Status > Targets in the Prometheus web UI at http://localhost:9090 to confirm Jenkins shows as “UP.”

Step 4: Key Metrics to Watch

Some of the most useful metrics exposed by the plugin:

Metric	What it tells you
jenkins_builds_duration_milliseconds_summary	How long builds are taking, per job
jenkins_builds_failed_build_count	Failed build counts
jenkins_builds_success_build_count	Successful build counts
jenkins_queue_size_value	How many jobs are waiting for an available executor
jenkins_executor_count_value	Total executors across all nodes
jenkins_executor_free_value	Currently idle executors
jvm_memory_bytes_used	JVM heap and non-heap memory usage
jenkins_node_count_value	Number of connected agent nodes

A consistently high jenkins_queue_size_value alongside low jenkins_executor_free_value is a classic sign you need more agents.

Step 5: Visualize with Grafana

Prometheus’s own UI is fine for quick queries but not for dashboards. Add Grafana:

docker run -d --name grafana -p 3000:3000 grafana/grafana

1. Log in at http://localhost:3000 (default admin/admin)
2. Add Prometheus as a data source, pointing at http://prometheus-host:9090
3. Import a pre-built Jenkins dashboard — the community dashboard ID 9964 on grafana.com works well as a starting point, showing build duration, queue size, and executor usage out of the box

From there, customize panels with PromQL. For example, average build duration over the last hour for a specific job:

avg(jenkins_builds_duration_milliseconds_summary{jenkins_job="my-pipeline"})

Or failure rate over the last 24 hours:

rate(jenkins_builds_failed_build_count[24h])

Step 6: Set Up Alerting with Alertmanager

Monitoring without alerting just means you find out about problems when you happen to check a dashboard. Add alert rules to Prometheus:

groups:
  - name: jenkins_alerts
    rules:
      - alert: JenkinsQueueBacklog
        expr: jenkins_queue_size_value > 10
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Jenkins build queue is backed up"
          description: "Queue size has been above 10 for 10 minutes."

      - alert: JenkinsHighFailureRate
        expr: rate(jenkins_builds_failed_build_count[1h]) > 0.3
        for: 15m
        labels:
          severity: critical
        annotations:
          summary: "High Jenkins build failure rate"

      - alert: JenkinsHeapUsageHigh
        expr: jvm_memory_bytes_used{area="heap"} / jvm_memory_bytes_max{area="heap"} > 0.85
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Jenkins controller JVM heap usage is high"

Point Alertmanager at Slack, PagerDuty, or email so these fire to wherever your team actually looks.

Integrating This Into Your CI/CD Pipeline

You can even add a pipeline stage that pushes custom metrics for individual build steps using the Prometheus Pushgateway, which is useful for metrics tied to a single job run rather than the ongoing Jenkins state:

stage('Push Custom Metrics') {
    steps {
        sh '''
            echo "custom_deploy_duration_seconds ${DEPLOY_DURATION}" | \
            curl --data-binary @- http://pushgateway:9091/metrics/job/deploy/instance/${JOB_NAME}
        '''
    }
}

This lets you track things Prometheus wouldn’t otherwise see, like deployment duration or the size of an artifact.

Troubleshooting

Prometheus target shows “DOWN”: Check network connectivity between the Prometheus host and Jenkins, and confirm the metrics path matches exactly (/prometheus/ with the trailing slash is the default).

Metrics endpoint returns 403: Authentication is likely enabled on the plugin but not configured in your scrape config — add basic auth credentials.

No data for a specific job: The plugin only reports metrics for jobs that have actually run since the plugin was installed; trigger a build to populate it.

Grafana dashboard shows “No Data”: Double check the Prometheus data source URL in Grafana and confirm the underlying query matches your metric names (namespaces can change label prefixes).

Security Best Practices

• Always enable authentication on the /prometheus endpoint in production
• Run Prometheus and Grafana behind a reverse proxy with TLS
• Limit who can edit Grafana dashboards and alert rules
• Use read-only Grafana viewer roles for most team members
• Rotate the Jenkins API token used for scraping periodically

FAQs

Does the Prometheus plugin slow down Jenkins? No noticeable impact for most installations — metric collection is lightweight and runs on a configurable interval.

Can I monitor multiple Jenkins instances with one Prometheus server? Yes, just add multiple scrape targets or use service discovery, and set a distinct namespace per instance so metrics don’t collide.

Do I need Grafana, or can I just use Prometheus’s UI? Prometheus’s UI is fine for ad hoc queries, but Grafana is far better for persistent dashboards your whole team can view.

What’s the difference between this and the Jenkins Metrics plugin? The Metrics plugin exposes data in Dropwizard/JSON format for general consumption; the Prometheus plugin specifically formats it for Prometheus scraping.

Can I get alerted the moment a specific critical job fails, not just on rate thresholds? Yes — add a rule matching jenkins_builds_last_build_result{jenkins_job="critical-job"} (or use the Jenkins post-build notification plugins alongside Prometheus for immediate, job-specific alerts).

How long should I retain Prometheus metrics for Jenkins? It depends on how far back you want trend analysis to reach. Thirty to ninety days of local retention is common for day-to-day dashboards, but if you want to compare build performance quarter over quarter, consider remote-writing metrics to a longer-term store like Thanos, Cortex, or Mimir, since Prometheus’s local storage isn’t designed for indefinite retention.

Does this integration work the same way for Jenkins running in Kubernetes? Yes, with one addition: if Jenkins runs as a pod, you’ll typically use a Kubernetes ServiceMonitor (if you’re running the Prometheus Operator) instead of a static scrape config, pointing at the Jenkins service’s /prometheus endpoint the same way.

Summary

Monitoring Jenkins with Prometheus turns your CI/CD server from a black box into something you can actually observe over time. Once the Prometheus metrics plugin is installed and scraped, you get visibility into build durations, queue backlogs, executor saturation, and JVM health — all queryable and graphable. Layer Grafana on top for dashboards and Alertmanager for proactive alerts, and you’ll catch capacity and reliability issues long before they turn into failed deployments.

References

• Jenkins Prometheus Metrics Plugin
• Prometheus Official Documentation
• Grafana Documentation
• Prometheus Alerting Rules Documentation
• Jenkins Official Documentation