Skip to content

docs: add Grafana dashboard setup guide and provisioning JSON for Prometheus users#1282

Open
Vaishnav88sk wants to merge 2 commits into
jenkinsci:mainfrom
Vaishnav88sk:docs/grafana-setup-guide
Open

docs: add Grafana dashboard setup guide and provisioning JSON for Prometheus users#1282
Vaishnav88sk wants to merge 2 commits into
jenkinsci:mainfrom
Vaishnav88sk:docs/grafana-setup-guide

Conversation

@Vaishnav88sk
Copy link
Copy Markdown

The existing docs/DASHBOARDS.md only covers Kibana (Elastic) dashboards. Users running the Prometheus + Grafana stack - a common open-source observability setup - have no documentation showing how to visualise Jenkins metrics in Grafana.

This PR adds:

  • docs/grafana-dashboard-setup.md - end-to-end guide covering:

    • OTel Collector config with Prometheus exporter and resource_to_telemetry_conversion (required for label filtering)
    • Prometheus scrape config
    • Dashboard import via Grafana UI and via provisioning
    • JCasC config to link Jenkins build pages back to Grafana using customObservabilityBackend
    • Troubleshooting section for missing metrics and the ci_pipeline_run_duration_milliseconds allow-list config
  • docs/grafana/jenkins-overview.json - provisioning-ready Grafana
    dashboard JSON with panels for:

    • Build count, success rate, p50/p95 build duration (stat panels)
    • Build results over time by status (SUCCESS / FAILURE / ABORTED)
    • Queue wait time p50/p95
    • Executor busy vs idle
    • JVM heap memory and HTTP request duration
    • service_name template variable for multi-instance filtering
  • docs/DASHBOARDS.md - added link to the new Grafana guide

Relates to the gap identified in docs/monitoring-metrics.md, which lists all available metrics but provides no Grafana visualisation guidance.

Testing done

Documentation and dashboard JSON only - no code changes.

  • All PromQL expressions in jenkins-overview.json verified against metrics emitted by the plugin (ci_pipeline_run_duration_milliseconds, ci_pipeline_run_queue_duration_milliseconds, jenkins_executor_count, runtime_jvm_memory_usage, http_server_request_duration_seconds)

  • Dashboard JSON imported into Grafana 10.x locally against a Prometheus instance scraping the OTel Collector - all panels render without errors

  • Provisioning config tested: copied JSON to /etc/grafana/provisioning/dashboards/ and confirmed dashboard appears automatically after Grafana restart

  • All cross-links in the markdown verified to point to existing files in the repo (setup-and-configuration.md, monitoring-metrics.md, DASHBOARDS.md)

  • OTel Collector config in the guide tested locally with otelcol-contrib validate --config otel-collector-config.yaml

Submitter checklist

  • Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
  • Ensure that the pull request title represents the desired changelog entry
  • Please describe what you did
  • Link to relevant issues in GitHub or Jira
  • Link to relevant pull requests, esp. upstream and downstream changes
  • Ensure you have provided tests that demonstrate the feature works or the issue is fixed

Fixes #1276

…users

Signed-off-by: Vaishnav88sk <vaishnavsk8804@gmail.com>
@Vaishnav88sk Vaishnav88sk requested a review from a team as a code owner April 14, 2026 10:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: no Grafana dashboard setup guide for Prometheus + Grafana users

1 participant