Documentation Plugins Jenkins data source Query editor

Jenkins query editor

This document explains how to use the Jenkins query editor to build queries and template variables.

Before you begin

• Ensure you have configured the Jenkins data source.
• Verify your credentials have permission to read the projects, nodes, and queues you want to query.

Key concepts

If you’re new to Jenkins, these terms are used throughout the query editor:

Query types

Select a query type from the query editor to get started. The Jenkins data source supports the following query types:

• Projects: List all Jenkins projects and their status.
• Project Builds: List the builds for a selected project.
• Build Queue: List builds currently waiting in the build queue.
• Nodes: List all nodes connected to your Jenkins server.
• Node Labels: List the labels used to organize your Jenkins nodes.

Create a query

To create a query:

1. Select the Jenkins data source.
2. Select a query type from the query type selector.
3. For a Project Builds query, select a project.

Projects

A project, also known as a job or item, is the core building block in the Jenkins automation server. It holds the configuration for Jenkins to perform specific tasks in CI/CD pipelines, such as building code, running tests, or deploying applications.

The Projects query returns a list of all Jenkins projects with information such as name, URL, current status, and whether it can be built. You also get details about its first, last, and most recent successful, failed, or unstable builds, along with information like the next build number and whether it’s currently disabled.

The query returns the following fields:

Project builds

A project build, or simply build, is a single execution of a configured Jenkins project. Triggered manually, on schedule, or by code changes, each build independently runs the project’s defined steps, including SCM operations, build commands, and post-build actions.

The Project Builds query returns a list of all project builds with information such as its unique number, when it started, its display name, and a direct URL to view its results. You also find out whether the build is currently running, its duration, and the estimated time it would take. The query also shows the result of the build (success or failure) and the agent it ran on.

This query requires you to select a project, and it returns only the builds that started within the dashboard time range. It also includes a derived FailedSince field that reports when a run of consecutive failures began, which is useful for tracking time to restore service. The other query types aren’t affected by the dashboard time range.

The query returns the following fields:

Build queue

The Jenkins build queue manages and prioritizes build requests waiting for available resources. When a project build is triggered but no executors are free, the request enters this waiting room. This ensures builds run in turn, and administrators can track pending tasks and workload.

The Build Queue query returns a list of all builds currently waiting in the build queue. For each build, you see its unique ID, whether it’s currently buildable or blocked, whether it’s been canceled or is stuck, and how long it’s been in the queue. It also tells you why it’s waiting, the name of the project it belongs to, and a URL to view more details.

The query returns the following fields:

Nodes

A Jenkins node, also known as an agent, is a machine (physical or virtual) that connects to the main Jenkins server and executes build tasks.

The Nodes query returns a list of all nodes connected to your Jenkins server. For each node, you see its name, description, assigned labels (for categorizing it), and the number of tasks it can run at once. It also tells you whether the node is idle or offline, and if offline, the reason why.

The query returns the following fields:

Node labels

A Jenkins node label is a custom tag or category assigned to a Jenkins node, allowing you to run specific builds only on nodes that have that label.

The Node Labels query returns a list of node labels used to organize your Jenkins nodes. For each label, you see its name, how many executors (slots for running tasks) are currently busy or idle, and the total number available under that label. It also indicates whether any nodes associated with that label are offline, and lists the names of the nodes themselves.

The query returns the following fields:

Example use cases

The following examples show common ways to combine query types with panels and transformations.

Show a project status overview

Use a Projects query with a table or stat panel to see the health of every project at a glance:

1. Add a panel and select the Projects query type.
2. Use a Table visualization to list projects, or a Stat visualization keyed on the Color or Disabled field to highlight broken or disabled projects.
3. Optionally, add an Organize fields transformation to hide the build-number and URL fields you don’t need.

Track build results over time

Use a Project Builds query to visualize how a project’s builds trend across the dashboard time range:

1. Add a panel and select the Project Builds query type.
2. Select a project, or set the project field to a template variable such as $project.
3. Use a State timeline visualization on the Result field to see successes and failures over time, or a Time series visualization on Duration to spot builds that are getting slower.
4. Expand the dashboard time range to include the builds you want to analyze.

Measure time to restore service

Use the derived FailedSince field from a Project Builds query to support the DORA time-to-restore metric:

1. Add a Project Builds query for the project you want to measure.
2. Add a Stat or Time series visualization on the FailedSince field to show when the most recent run of failures began.

Monitor the build queue

Use a Build Queue query to surface work that’s waiting on capacity:

1. Add a panel and select the Build Queue query type.
2. Use a Table visualization to list queued items, and display the Why, Stuck, and Blocked fields to explain why each item is waiting.
3. Add a Stat panel with a Reduce calculation such as Count to alert your team when the queue grows.

Monitor node and executor capacity

Use Nodes and Node Labels queries to track agent availability:

1. Add a panel and select the Nodes query type to list agents and their online or offline status.
2. Add a second panel with the Node Labels query type to compare busy and idle executors per label, which helps you find labels that are starved for capacity.

Next steps

• Use template variables with the Jenkins data source
• Troubleshoot the Jenkins data source
• Use Explore to query data without building a dashboard.