Support Bundle Diagnostics in Jenkins
A book-style guide to the Support Core plugin's diagnostic bundle — what it captures, how it works internally, how to read it during an incident, and how to use it safely and effectively in production.
Imagine a commercial airliner after a rough landing. Investigators do not start by guessing what happened. They pull the flight data recorder and the cockpit voice recorder, two boxes that were quietly capturing everything the whole time, and read them to reconstruct exactly what occurred, in order, without relying on anyone’s memory. Nobody had to remember to turn the recorders on mid-flight; they were always running.
A Jenkins support bundle is that flight recorder for your automation server. When a controller behaves strangely, hangs, or crashes, you do not want to be improvising which log file to check first. You want one command that instantly packages everything an expert would ask for — thread dumps, logs, configuration, plugin versions, system metrics — into a single file you can attach to a support ticket or study yourself. This guide explains, from the ground up, what that bundle contains, how it is built internally, and how to use it to solve real problems quickly.
1What a Support Bundle Is and Why It Exists
Before opening a bundle, it helps to understand the problem it was built to solve.
The old way of diagnosing Jenkins problems
Before this feature existed, diagnosing a sick Jenkins controller meant manually hunting down a scattered set of files and settings: the main log, several plugin-specific logs, thread dumps taken by hand at the right moment, the list of installed plugins and their versions, environment variables, and system resource numbers. Every engineer collected a slightly different, slightly incomplete set, and by the time all the pieces were gathered, the problem had often already changed or disappeared.
What the Support Core plugin does
The Support Core plugin, which ships as part of the standard Jenkins distribution and is installed by default in most setups, adds a “Support” section to Jenkins administration. With a few clicks, or a single API call, it gathers dozens of individual pieces of diagnostic information and packages them into one downloadable archive: the support bundle. It is designed to answer, in one file, the question “what does this Jenkins controller look like right now?”
Asking someone to describe every symptom before a doctor’s visit rarely produces a complete picture, because people forget details or don’t know what’s relevant. A full blood panel and an X-ray, ordered as a standard bundle of tests, catches things nobody thought to ask about. A support bundle is that standard panel of tests for Jenkins.
Who uses support bundles
Jenkins administrators
Use it to self-diagnose slowdowns, plugin conflicts and memory pressure without needing outside help.
Commercial support teams
Vendors offering paid Jenkins support routinely ask customers for a bundle as the very first step of any ticket, because it answers most preliminary questions at once.
Open-source contributors
When reporting a bug against Jenkins core or a plugin, a bundle gives maintainers the environment context needed to reproduce or understand the report.
Internal platform teams
Large organisations running many controllers use bundles as a standard artifact captured before and after major changes, such as plugin upgrades.
2Core Concepts: Components, Content and Format
A support bundle is not one big file of raw data; it is an organised archive built from many small, independent pieces.
The building block: a component
Internally, the Support Core plugin is built around a simple idea called a component. A component is a self-contained unit responsible for gathering one specific kind of information, such as “the main Jenkins log,” “the list of installed plugins,” or “a thread dump.” Each component knows how to collect its own data and write it into the bundle, independent of every other component. This modular design is what lets other plugins add their own components without touching Support Core itself.
About component
Captures the Jenkins version, the Java version, the operating system, and other basic identifying facts about the environment.
Thread Dump component
Captures a snapshot of every thread running inside the Jenkins process at the moment the bundle is generated.
Plugin List component
Captures every installed plugin, its version, and whether it is enabled, which lets a reviewer instantly spot an outdated or unusual plugin combination.
System Configuration component
Captures relevant global settings, node definitions and other configuration facts, with sensitive values automatically redacted.
Log Recorders component
Captures the content of any custom log recorders an administrator has configured to watch specific loggers at specific levels.
Node Monitors component
Captures resource information for every connected agent: available disk space, response time, and clock skew relative to the controller.
What the archive looks like
A generated bundle is a single ZIP file, typically named with a timestamp, containing a folder structure where each component writes its output as one or more plain text, JSON or log files. Nothing inside requires special tools to read; every file opens directly in a text editor, which is deliberate, since a support engineer or an automated script should be able to inspect it without installing anything extra.
Because every component writes ordinary text or JSON, a bundle can be searched with a simple text search tool, diffed against an older bundle from the same controller, or fed into a script, without any proprietary format getting in the way.
3Architecture: How the Plugin Assembles a Bundle
Understanding the assembly process explains both the bundle’s strengths and its practical limits.
flowchart TD
A["Admin clicks Generate Bundle, or API call arrives"] --> B["Support Core discovers all registered components"]
B --> C["Each component runs its own collection logic"]
C --> D["Component 1: writes about.md"]
C --> E["Component 2: writes thread-dump.txt"]
C --> F["Component 3: writes plugins.txt"]
C --> G["Component N: writes its own file(s)"]
D --> H["Content Filters redact sensitive values"]
E --> H
F --> H
G --> H
H --> I["Files packaged into a single ZIP archive"]
I --> J["Download offered to the admin"]
Component discovery
When a bundle is requested, Support Core does not hold a fixed, hardcoded list of components. Instead it discovers every component registered by any installed plugin, including its own built-in set. This is why installing a plugin such as one for a cloud provider, a specific SCM, or a build tool often adds new, specialised sections to your bundles automatically, with no separate configuration needed.
Parallel and independent collection
Each component gathers its own data independently, so a slow or failing component, in principle, should not stop the others from completing. This matters especially on a struggling controller: even if one component times out gathering an especially large piece of data, the rest of the bundle should still assemble and download successfully, giving you a partial but still useful picture.
The redaction layer
Before anything is written into the final archive, a filtering layer runs over the collected content looking for patterns that resemble secrets: passwords, API tokens, and other credential-shaped strings, replacing them with a placeholder. This redaction is pattern-based, which is an important detail explored further in the security chapter, because pattern matching can miss secrets that do not look like the patterns it knows about.
Automated redaction catches common credential patterns, but a bundle should still be treated as sensitive until a human has reviewed it, especially before sending it outside the organisation.
4Generating a Bundle: The Three Ways
Jenkins offers three practical ways to produce a bundle, suited to different situations.
The web UI
Under Manage Jenkins, the Support section lets an administrator select which components to include, or simply choose all, and click a button to generate and download the ZIP immediately.
The REST API
A dedicated URL can be called with an authenticated request to generate and download a bundle programmatically, useful for scripting or for triggering a capture from a monitoring alert.
Automatic periodic bundles
Support Core can be configured to automatically generate and retain bundles on a recurring schedule, keeping a rolling history so that a bundle exists from just before an incident even if nobody thought to capture one manually.
Automatic periodic bundles are like a building’s security cameras recording continuously to a rolling buffer. Nobody has to remember to hit record when something happens; the last several hours are already saved by the time anyone asks for them.
Choosing which components to include
The generation screen lets you select a subset of components rather than always capturing everything. This matters for two reasons: a smaller bundle is faster to generate and easier to review, and some components (such as ones capturing large log files or extensive thread dumps) can be genuinely heavy on a struggling controller. A common practice is to keep a lightweight default selection for routine captures and add heavier components only when actively investigating a specific problem.
A bundle captures a snapshot of the current moment. If a controller becomes slow and then recovers before anyone downloads a bundle, that transient state is gone. Whenever possible, capture during the problem, not after it has resolved itself.
5Thread Dumps: Reading the Heartbeat of the JVM
The thread dump is arguably the single most valuable piece of information in a bundle for diagnosing hangs and slowdowns, so it deserves its own close look.
What a thread dump actually is
Jenkins runs inside a Java Virtual Machine, and at any moment that JVM is juggling many threads: separate lines of execution handling web requests, running build steps, checking queued jobs and more. A thread dump is a snapshot listing every one of those threads, showing exactly which line of code each one is executing and, crucially, what each thread is waiting on if it is blocked.
graph TD
A["Thread Dump Snapshot"] --> B["Thread: Handling-Request-1042"]
A --> C["Thread: Executor-3"]
A --> D["Thread: Queue-Maintenance"]
B --> B1["State: BLOCKED, waiting on lock held by Thread D"]
C --> C1["State: RUNNABLE, executing build step"]
D --> D1["State: RUNNABLE, holding lock B is waiting for"]
What to look for
A blocked thread
A thread waiting to acquire a lock held by another thread. One blocked thread is normal; many threads blocked on the same lock for a long time signals contention worth investigating.
A deadlock
Two or more threads each waiting on a lock the other holds, so neither can ever proceed. Jenkins’ thread dump explicitly calls out detected deadlocks, making them easy to spot.
A stuck executor
A build executor thread that has been running the same line of code for an unusually long time, often pointing to a hung external process or an infinite loop in a plugin.
Thread pool exhaustion
Every thread in a pool busy or blocked at once, with new requests unable to get a thread at all, often showing up as the controller simply stopping to respond to new web requests.
Reading a thread dump is like walking into a busy kitchen during a rush and asking every cook, one by one, exactly what they are doing right now. Most say “chopping vegetables” or “plating a dish.” But if half the cooks say “waiting for the one knife, which cook 7 is holding,” and cook 7 says “waiting for the cutting board, which is with cook 3, who is waiting on me for the knife,” you have just found your deadlock.
Capturing multiple dumps for trends
A single thread dump is a snapshot; a real hang is best confirmed by capturing two or three dumps a few seconds apart and comparing them. If the same threads are stuck at the exact same line of code across every dump, that is strong evidence of a genuine hang rather than a normal, momentary busy period.
If a controller becomes unresponsive, generate the bundle immediately, even if the web UI itself feels sluggish. A thread dump taken during the hang is far more valuable than a perfectly healthy one taken after a restart has already cleared the problem.
6Logs Inside the Bundle
Alongside the thread dump, the bundle’s log content is where most root causes are eventually confirmed.
The main Jenkins log
The bundle includes the primary Jenkins log, which records startup messages, plugin loading, security events and unhandled errors. This is usually the very first file worth searching for exceptions, stack traces or warning messages around the time the problem occurred.
Custom log recorders
Jenkins lets an administrator define a log recorder that watches a specific logger, such as one belonging to a particular plugin, at a chosen verbosity level, from informational messages up to detailed debug output. If any log recorders are configured, the bundle captures their recent output as its own component, which is invaluable when the main log is too general to show what a specific plugin was doing.
Example: diagnosing a flaky source control plugin
If builds are intermittently failing to check out code, an administrator can add a log recorder targeting the source control plugin’s package at debug level, reproduce the failure once, then generate a bundle. The captured recorder output shows the exact network calls and responses the plugin made, something the main log would never reveal at its default verbosity.
Agent and build logs
Depending on which components are selected, the bundle can also include per-agent connection logs, showing when an agent connected, disconnected or reported an error, which is essential when the problem is isolated to specific build machines rather than the controller itself.
| Log source | Best for diagnosing |
|---|---|
| Main Jenkins log | Startup errors, plugin load failures, unhandled exceptions |
| Custom log recorders | Deep, plugin-specific behaviour not visible at default verbosity |
| Agent connection logs | Problems isolated to specific build machines |
| Node monitor data | Resource exhaustion (disk, memory) on a specific agent |
A log recorder only captures activity from the moment it is turned on. If a problem is intermittent, turn on the relevant recorder proactively and leave it running at a reasonable level, so the next occurrence is captured rather than missed again.
7Configuration, Plugins and Environment Data
Beyond logs and thread dumps, the bundle captures the “shape” of the Jenkins installation itself, which is often where compatibility problems hide.
The plugin list
Every installed plugin and its exact version appears in the bundle, along with whether each one is enabled. This single list answers a huge number of support questions instantly: is the reported plugin actually installed, is it an old version with a known bug, and are there two plugins installed together that are known to conflict.
System and environment information
Java and OS details
The exact Java Virtual Machine version, vendor and the host operating system, which matters because Jenkins and plugin compatibility is often tied to specific Java versions.
JVM memory settings
The configured heap size and garbage collection settings, essential for diagnosing out-of-memory errors or excessive garbage collection pauses.
Environment variables
The process environment as Jenkins sees it, useful for spotting a missing or incorrect variable that a plugin or pipeline depends on.
Node and cloud configuration
The definitions of connected agents and any cloud-based dynamic agent providers, showing exactly how build capacity is configured.
Why this matters more than it seems
A surprising number of production incidents trace back not to a bug in the code being built, but to a mismatch: a plugin upgraded without its dependency, a Java version incompatible with a newer plugin, or a memory setting left over from a much smaller installation years ago. Because the bundle captures this “shape” data every time, comparing an old bundle to a new one after a change is often the fastest way to spot exactly what shifted.
A car mechanic doesn’t just listen to the engine noise; they also check the model year, the mileage and the maintenance history, because a noise that is normal for one car is a warning sign for another. The plugin list and environment data are Jenkins’ equivalent of the vehicle’s specification sheet.
8Node and Agent Diagnostics
Many real-world Jenkins problems live on the agents doing the actual building, not on the controller, and the bundle reaches there too.
Node monitors
Jenkins continuously runs a small set of built-in checks against every connected agent, called node monitors: available disk space on the workspace and temporary directories, free swap space, response time to a simple ping, and clock difference between the agent and the controller. The bundle captures the latest readings from all of these for every agent in one place.
flowchart LR
C["Jenkins Controller"] --> M["Node Monitors"]
M --> A1["Agent build-01: Disk 4% free"]
M --> A2["Agent build-02: Clock skew 45s"]
M --> A3["Agent build-03: Healthy"]
A1 --> R["Marked temporarily offline"]
A2 --> W["Build timestamps may look wrong"]
Why agent problems often masquerade as controller problems
An agent running critically low on disk space can cause build failures that look, at first glance, like a Jenkins bug: mysterious checkout failures, incomplete workspace files, or strange permission errors. Because the bundle’s node monitor data is captured for every agent side by side, a reviewer can often spot the one agent with 2 percent disk free among a dozen healthy ones far faster than by logging into each machine individually.
Example: clock skew breaking certificate validation
An agent whose system clock had drifted by several minutes started failing TLS handshakes, because the certificates it was validating appeared to be issued in the future from its own skewed point of view. The node monitor’s clock-skew reading in the bundle pointed directly at the cause, well before anyone thought to check the agent’s system time manually.
When a build fails intermittently, it is easy to focus only on the agent that ran the failing build. The bundle’s side-by-side node monitor view often reveals that a completely different, seemingly unrelated agent is the one under resource pressure, affecting scheduling for everyone.
9A Practical Triage Workflow
Having a bundle is only useful if you know a repeatable order in which to read it. This chapter offers a structured path through the archive.
Start with the About and manifest files
Confirm the Jenkins version, Java version and generation time first, so every later observation is anchored to the right context.
Check the plugin list for anything recently changed
Look for plugins updated close to when the problem began, or an unusually old plugin sitting alongside much newer ones.
Scan the main log around the incident time
Search for exceptions, warnings or repeated messages clustered near the moment things went wrong.
Read the thread dump for blocking or stuck executors
If the symptom was slowness or a hang, this is usually where the real answer is hiding.
Check node monitor data for the affected agents
Rule out disk, memory or clock problems on the machines actually involved in the failing builds.
Cross-reference the JVM memory and garbage collection data
Look for signs of memory pressure that could explain slowness independent of any single plugin.
Form a hypothesis and confirm it with a second bundle
If possible, reproduce the issue, capture a fresh bundle, and confirm the same signal appears again before concluding the root cause.
Restarting Jenkins often makes a hang or a memory problem disappear, but it also erases the exact state you need a bundle to capture. Whenever it is safe to do so, generate the bundle before restarting, not after.
10Comparing Bundles Over Time
A single bundle answers “what does Jenkins look like right now?” Two bundles, taken at different times, can answer the much more powerful question “what changed?”
Before-and-after captures
A disciplined practice is to generate a bundle immediately before any risky operation — a plugin upgrade, a Jenkins core upgrade, a major configuration change — and another immediately after. If something breaks afterward, comparing the plugin list, environment data and configuration files between the two bundles frequently surfaces the exact change responsible, without needing to remember every step taken during the maintenance window.
flowchart LR
A["Bundle Before Upgrade"] --> C["Diff Plugin Lists"]
B["Bundle After Upgrade"] --> C
A --> D["Diff Config Files"]
B --> D
A --> E["Diff Environment"]
B --> E
C --> F["Root Cause Candidate Identified"]
D --> F
E --> F
Trend spotting with periodic bundles
Where automatic periodic bundle generation is enabled, a rolling history lets you look back and notice gradual trends: a plugin count creeping upward, memory usage slowly climbing over weeks, or a particular warning message that started appearing regularly a certain number of days before a serious incident. These gradual patterns are often invisible in any single snapshot but obvious once several are laid side by side.
Example: catching a slow memory leak early
A platform team reviewing weekly automatic bundles noticed the reported heap usage climbing steadily after each restart, week over week, long before it caused an actual outage. The trend, visible only by comparing several bundles, prompted an investigation that found a plugin failing to release listeners it registered, well before the leak became severe enough to crash the controller.
Retaining a modest history of past bundles, especially ones taken around known-good states, turns diagnosis from guesswork into comparison. Store them somewhere searchable rather than letting each one disappear after a single use.
11Security and Redaction
A bundle is, by design, an extremely information-dense file, and treating it with the wrong level of care is one of the most common mistakes teams make.
What automated redaction does and does not catch
The built-in filtering layer scans collected text for patterns commonly associated with secrets, such as strings following common credential-like formats, and masks them before the bundle is written. This is a genuine safety feature, but it is pattern-based, meaning it recognises the shapes of secrets it has been taught to look for. A custom internal token format, a secret embedded inside an unusual log message, or a credential pasted into a build parameter in an unexpected way can slip past it.
Treat every generated bundle as potentially containing sensitive information until a human has reviewed it, especially before attaching it to a public issue tracker, a third-party support portal, or any channel outside your organisation’s control.
What tends to appear even after redaction
Internal hostnames and URLs
Configuration and logs frequently reveal internal system names, network topology and service addresses that are not secrets in the credential sense, but are still information a company may not want public.
Usernames and email addresses
Build history, configuration and logs can include real employee names and emails, which matters for privacy, not just security.
Job and pipeline names
The names of jobs, branches and folders can themselves reveal product names, unreleased features or business details that are sensitive in context.
Unusual secret formats
A credential formatted differently from the patterns the redaction filter expects may pass through untouched, especially custom internal token schemes.
Handling and storage
Because of this exposure, a downloaded bundle deserves the same handling discipline as any other sensitive internal document: stored in an access-controlled location, not emailed unencrypted to a personal address, and deleted once its diagnostic purpose is served, rather than accumulating indefinitely in a shared downloads folder.
Problem
An engineer attaches a raw, unreviewed support bundle directly to a public bug tracker issue to speed up getting help.
Why It’s Harmful
Automated redaction is not a guarantee, so the public archive may end up containing internal hostnames, employee names, or an unrecognised secret format, permanently visible to anyone.
Correct Approach
Review the bundle’s contents first, share it through a private support channel when possible, and manually strip anything sensitive that automated redaction missed before any public sharing.
12Performance Impact of Bundle Generation
Generating a bundle is not entirely free, and understanding its cost helps you use it wisely on a controller that is already under stress.
Where the cost comes from
Most components are lightweight, reading small configuration or metadata files. A few, however, are genuinely more expensive: gathering very large log files, producing a thread dump on a controller with an enormous number of threads, or scanning across a great many jobs and builds to compile summary statistics. On a controller that is already resource-constrained, these heavier components can add real, if usually brief, extra load exactly when the system can least afford it.
Advantages of capturing anyway
- A snapshot taken during the problem is far more diagnostic than one taken afterward
- Most components complete in well under a second even under load
- Selective component choice lets you keep the capture lightweight
Trade-offs to be aware of
- A few heavy components can add noticeable transient load on a severely struggling controller
- Very large installations may produce a very large archive that takes time to download and review
- Automatic periodic generation adds a small recurring background cost
Taking a photograph of a traffic jam to understand its cause takes a moment and does not fix the jam, but it also does not make it meaningfully worse. Generating a bundle during a struggling controller’s slow period is much the same: a brief, worthwhile cost for a picture you cannot get any other way.
If a controller is so overloaded that even the web UI barely responds, prefer a targeted API call requesting only the essential components — thread dump, main log, plugin list — over a full capture of every available component.
13Extending Support Bundles: Custom Components
The same modular design that makes the bundle so complete also makes it open to extension, which matters for teams running their own plugins or custom setups.
Why a plugin author would add a component
Any plugin can register its own component with Support Core, contributing whatever diagnostic information is relevant to that plugin’s own domain: its connection state to an external system, its own internal queue depth, or a summary of recent errors it has encountered. This means the bundle grows more useful the more of your installed plugins participate, without any central team needing to maintain a master list.
Example: a cloud agent plugin’s own component
A plugin that provisions build agents on demand from a cloud provider might contribute a component listing recent provisioning attempts, their success or failure, and the reported error from the cloud API, turning an otherwise opaque “agent failed to launch” symptom into a documented, reviewable history.
What good custom components have in common
Fast and non-blocking
A well-behaved component finishes quickly and never risks stalling the entire bundle generation if its own data source is unavailable.
Respects redaction
A component that gathers anything sensitive routes it through the same filtering layer the rest of the system uses, rather than writing raw, unfiltered content.
Plain and structured output
Following the archive’s convention of readable text or JSON, so the component’s data is just as easy to search and diff as the built-in ones.
Because components are discovered automatically, a badly behaved custom component installed by one plugin can add noticeable delay, or even hang, every future bundle generation on that controller. Test custom components under realistic load before relying on them in production.
14Design Patterns and Anti-Patterns
Teams that rely on support bundles heavily tend to converge on a similar set of good habits, and a similar set of avoidable mistakes.
Patterns that work
Bundle-first incident response
Make generating a bundle the very first step of any production Jenkins incident, before any troubleshooting or restart, so the actual state at the time of the problem is preserved no matter what happens next.
Bundles around every risky change
Capture one immediately before and one immediately after every plugin upgrade, core upgrade or significant configuration change, building a natural audit trail for troubleshooting later.
A retained, searchable archive
Store bundles in a shared, access-controlled location with clear naming, rather than letting each engineer keep their own copy scattered across personal machines.
Purpose-built log recorders left running
For known trouble spots, keep a targeted log recorder enabled at a moderate level permanently, so the next occurrence of an intermittent issue is captured automatically in the next bundle.
Problem
The team’s habit during any incident is to restart Jenkins immediately, “just to see if it helps,” before capturing any diagnostic bundle.
Why It’s Harmful
A restart clears the exact JVM state, thread dump and in-memory conditions that would have explained the problem, often turning a solvable mystery into a recurring, undiagnosed one.
Correct Approach
Generate a bundle first whenever it is safe to do so, then restart if that remains the right next step.
Problem
A bundle is emailed as an unencrypted attachment to an outside vendor without anyone reviewing its contents first.
Why It’s Harmful
Automated redaction can miss internal hostnames, employee details or an unusual secret format, and once sent, that exposure cannot be undone.
Correct Approach
Review the bundle, use a secure sharing channel, and remove anything sensitive the automated filter did not catch.
15Real-World Examples
The following stories are composites of patterns that repeat across organisations using Jenkins at scale.
A media company diagnosing a mysterious weekly slowdown
A streaming platform noticed its Jenkins controller slowed noticeably every Monday morning. Weekly automatic bundles, compared over a month, showed heap usage climbing steadily right before each slowdown and dropping after a scheduled Monday restart, pointing to a memory leak tied to a reporting plugin that ran only on weekly triggers. The trend, invisible in any single bundle, was obvious across several.
A logistics company resolving a support ticket in one round-trip
A logistics company opened a ticket with its Jenkins support vendor after intermittent build failures. Attaching a bundle up front let the vendor identify a known incompatibility between two plugin versions directly from the plugin list, resolving the ticket in a single reply instead of the usual back-and-forth of clarifying questions.
A fintech company catching a clock-skew issue before it caused an outage
During a routine before-and-after capture around a data center migration, a platform team noticed one relocated agent’s node monitor data showing a growing clock skew. They corrected the agent’s time synchronisation before any build was affected, avoiding certificate validation failures that had caused an outage during a previous, similar migration.
An e-commerce company using bundles to justify a hardware upgrade
By comparing bundles taken every month for a year, a platform team built a clear, evidence-based case that thread pool exhaustion was becoming a recurring pattern as build volume grew, using the concrete data to secure budget for additional controller capacity rather than relying on anecdotal complaints.
16Advantages, Trade-offs and Best Practices
Every diagnostic tool has honest costs alongside its benefits. Knowing both lets you use support bundles well rather than reflexively.
Advantages
- Consolidates dozens of diagnostic signals into a single, portable file
- Captures thread dumps and logs that are otherwise lost the moment a problem resolves or Jenkins restarts
- Extensible, so plugin-specific diagnostics arrive automatically as plugins are installed
- Plain text and JSON output that works with any search, diff or scripting tool
- Automated redaction reduces, though does not eliminate, accidental secret exposure
- Enables meaningful before-and-after and trend-based analysis over time
Disadvantages / Trade-offs
- Redaction is pattern-based and can miss unusual secret formats
- Heavier components can add transient load on an already struggling controller
- A bundle is only a snapshot; it captures nothing before it was generated or after
- Large installations can produce large archives that take time to review thoroughly
- Requires disciplined storage and handling to avoid becoming a data exposure risk itself
Best practices at a glance
Capture during the problem
Generate a bundle before restarting or otherwise clearing the state you are trying to diagnose.
Bundle before and after risky changes
Turn every plugin or core upgrade into a natural before-and-after comparison opportunity.
Enable automatic periodic bundles
Keep a rolling history so a useful snapshot exists even for incidents nobody saw coming.
Review before sharing externally
Never treat automated redaction as a substitute for a human check before sending a bundle outside the organisation.
Follow a consistent triage order
Read About, plugins, logs, thread dump, then node monitors, rather than jumping around at random.
Keep log recorders on trouble spots running
Leave targeted recorders enabled so intermittent issues get captured the next time they occur.
17Frequently Asked Questions
No. It ships as part of the standard Jenkins distribution and is typically installed and enabled by default, so the Support section is usually already available under Manage Jenkins.
No. Generating a bundle is a read-only operation. It gathers a snapshot of the current state and writes it into a downloadable archive; it does not modify configuration, jobs or plugins.
No, not fully. It is pattern-based and catches common credential shapes reliably, but an unusual internal token format or a secret embedded in an unexpected place can slip through. Always review before sharing a bundle outside your organisation.
Usually because one or more heavier components, such as those scanning many jobs or a very large log file, are taking longer under current system load. Selecting a smaller, targeted set of components speeds this up.
Two or three, taken a few seconds apart, are usually enough to distinguish a genuine hang, where the same threads stay stuck at the same point, from a normal, momentarily busy system.
Yes. Support Core includes an option to periodically generate bundles automatically and retain a rolling history, and the REST API also allows scripting a custom schedule if you need different retention or triggering logic.
Many do. Because the component system is discovered automatically, any installed plugin that has registered its own component contributes its data without any extra configuration from the administrator.
Yes. Node monitor data, agent connection logs and related components specifically capture agent-side resource and connectivity information, which is often exactly where an intermittent build failure actually originates.
18Summary and Key Takeaways
Support bundle diagnostics turn Jenkins troubleshooting from a scattered scavenger hunt into a structured, repeatable process. A single click or API call captures thread dumps, logs, plugin versions, environment data and agent health into one file, giving you or an external support team the same complete picture at the same moment, without relying on anyone’s memory of what happened. Used well — captured early, compared over time, and handled with appropriate care for the sensitive information it contains — the support bundle becomes one of the highest-leverage tools available for keeping a Jenkins installation healthy and understood.
Key Takeaways
- A bundle is a modular snapshot, not a monolithic dump — independent components each capture one kind of information, and plugins can add their own automatically.
- The thread dump is the single most valuable file for hangs and slowdowns — capture several a few seconds apart to distinguish a real hang from a busy moment.
- Capture before you restart — a restart erases exactly the state a bundle exists to preserve.
- Redaction is a safety net, not a guarantee — always review a bundle’s contents before sharing it outside your organisation.
- Comparing two bundles is often more powerful than reading one — before-and-after captures around risky changes quickly isolate what actually shifted.
- Agent problems often hide inside controller symptoms — node monitor data surfaces disk, memory and clock issues on the machines actually doing the building.
- Treat bundles as an ongoing practice, not a one-off tool — periodic automatic captures and a retained, searchable archive turn diagnostics into a habit rather than a scramble.