Using the Graylog cluster support bundle

A Graylog support bundle gives engineers and outside support a single snapshot of a cluster to diagnose from. This page explains how to collect one, read it in a fixed order and share it without exposing secrets.

On this page

When a Graylog support bundle is the right first step

Collect a support bundle before anyone changes a setting when a Graylog cluster is degraded and the team needs one shared, point-in-time record of what each node reports. A support bundle captures the state of the cluster at the moment it is taken, so it answers a different question from a live search or dashboard. Searches show what the log data says about your systems. A bundle shows how Graylog itself is behaving: node configuration, component status, logs and related diagnostic output that a vendor or partner engineer can review without access to your live environment. Because a bundle is frozen, several people can work from the same facts while the cluster keeps changing underneath them.

Three situations justify collecting one. The first is before escalating to Graylog support or to an implementation partner, since a complete bundle shortens the first exchange and avoids repeated requests. The second is an ingestion slowdown with no obvious cause, where the bundle lets you compare the processing and output picture across nodes before you tune anything. The third is when nodes disagree, for example one Graylog node reports healthy while its peers do not, or the search backend reports different state to different nodes. In each case, the bundle is the record you want before you start making changes.

Confirm the collection method, the file list and the packaging against the Graylog documentation for the exact version you run, because the supplied facts do not describe the bundle itself. Check how it is generated on a multi-node cluster, whether it must be produced from each node or from one entry point, and which data it includes or excludes. Record the version, the time of collection and which node produced each file, so the evidence stays usable. Treat the bundle as sensitive from the moment it is created, since it may contain configuration values that need redaction before anyone outside your organization sees it.

What the bundle contains and what each part shows

A support bundle is a snapshot of one moment in the cluster, so each part answers a different question about the same incident. Read the parts together, starting from version and node identity, then configuration, logs, backend status and TLS material. Confirm the exact contents for your Graylog version in the current documentation before you rely on any part.

Node and version identity

This part records which Graylog version, plugins and nodes the bundle came from. It answers whether every node runs the same build, which matters after a partial upgrade or a rolling restart. Check the version against the compatibility matrix for your MongoDB and search backend before comparing symptoms with other incidents. Confirm in the current docs which node identifiers and host details are included, since you will need them to match log lines to the right node.

Configuration with secrets

The server configuration shows how inputs, the journal, processing buffers, the search backend connection and authentication were set at the time of the incident. It is the first place to look for a mismatched setting, such as a node flagged as leader when it should be a follower. Expect secrets such as passwords, tokens and the password secret to appear in some form, so review and redact before sharing. Confirm which keys are masked by default in your release.

Server and application logs

Logs show what each node did in the minutes before and after a failure: input connection errors, journal writes, search timeouts and plugin load failures. They answer when a problem started and which component reported it first. Align timestamps across nodes and note the time zone before drawing conclusions. Confirm the log level and rotation settings captured, because a bundle built at a low log level may omit the lines you need.

Cluster and backend status

This part reflects the state of MongoDB and the search backend, including cluster health, index and shard status, and node membership as Graylog sees it. It answers whether the problem sits in Graylog or in the storage layer underneath. A yellow or red search cluster state, or a MongoDB replica set without a primary, points the diagnosis away from Graylog settings. Confirm which backend details are collected for Data Node and for self-managed OpenSearch, since the two differ.

Certificate and TLS material

This part lists the certificates and trust settings Graylog uses for its API, inputs and backend connections, including expiry dates. It answers whether an expired or mismatched certificate explains failed logins, dropped TLS inputs or nodes that cannot reach each other. Check expiry against the incident time, then confirm the chain and hostnames match the endpoints clients use. Confirm in the current docs whether private keys are excluded from the bundle, and whether the bundle contains only certificate metadata.

A diagnosis order for reading the bundle

This sequence moves from the broadest facts about the deployment, its version and compatibility pairing, down to the specific components and logs, so each finding is read in the context of the one before it. The result is a short list of likely causes that you can check against the live cluster before changing anything.

  1. Confirm the Graylog version and compatibility pairing

    Start by reading the Graylog server version, the MongoDB version and the search backend version from the bundle, then compare them with the compatibility matrix for that release. Graylog 7.0 to 7.2 pair with MongoDB 7.x up to 8.2.x and with OpenSearch 1.1.x up to 3.7.x, and Graylog Security needs OpenSearch 2.0 or later. A version outside those ranges points to the root cause before any other check, and OpenSearch 1.x is deprecated since Graylog 7.0 and scheduled for removal in Graylog 8.0, so a 1.x backend is a planning item even when the cluster is healthy. Confirm the pairing with the matrix before moving on.

  2. Check node roles and cluster membership

    Next, read the node list and confirm that every expected Graylog server node is present, running the same version and reporting a valid lifecycle state. In a multi-node layout, exactly one node should act as the leader, and follower nodes should carry is_leader set to false in their configuration. A missing node, a version split across nodes, or two nodes claiming leadership suggests a failed upgrade, a configuration drift or a load balancer sending traffic to a node that is not ready. The step is complete when you can name each node, its role and its state.

  3. Verify the search backend health

    Check the cluster health of the search backend, whether that is Graylog Data Node or a self-managed OpenSearch cluster, using the health and node information captured in the bundle. Look for a red or yellow status, unassigned shards, nodes that have left the cluster, and disk watermark warnings. Most journal growth traces back to a backend that is slow or unreachable, so an unhealthy backend at this stage explains many later symptoms. Record the status and the specific indices or shards at fault before moving on.

  4. Review MongoDB configuration and replica set state

    Confirm that MongoDB is reachable from every Graylog node and that the replica set has a primary and healthy secondaries, since Graylog keeps configuration and metadata there. Check the MongoDB version against the compatibility matrix again, because a mismatch can cause startup or configuration errors that look like server faults. Errors about lost connections, missing primaries or failed writes indicate a database problem rather than a Graylog problem. The step is complete when the replica set status is recorded and any database-side errors are either ruled out or noted for follow-up.

  5. Read journal and buffer state on each node

    Review the message journal utilization and the process and output buffer figures for each node. A journal that is filling while buffers are full usually means processing is slower than ingest, often because of expensive pipeline rules or a stalled output. A journal that is filling while buffers are empty usually means the search backend is not accepting writes. Compare these figures across nodes, since one node with high utilization often points to uneven load balancing rather than a cluster-wide fault. Record which side of the pipeline is the bottleneck before deciding what to fix.

  6. Check certificate expiry and TLS configuration

    Inspect the certificates referenced by the bundle, including the Graylog HTTP certificate, any certificates used between nodes and the TLS settings for the search backend and MongoDB. Note each certificate's expiry date and the names or addresses it covers. An expired certificate or a name mismatch often causes connection failures that appear as backend or database errors, so confirm this check before concluding that the backend itself is at fault. Record the expiry dates in your own notes, since the bundle captures the state at collection time and certificates may have been renewed since.

  7. Correlate the server logs with the findings

    Finally, read the Graylog server logs for the time window around the symptom and match each error to the findings from the earlier steps. Repeated timeouts to the search backend, authentication failures against MongoDB, and journal or buffer warnings should line up with the states already recorded. An error that does not match any earlier finding is a lead to investigate further rather than a conclusion. The step is complete when each symptom has a single most likely cause, a list of checks to confirm it on the live cluster, and a note of what to redact before the bundle is shared.

Checking certificate expiry from the bundle

An expired certificate is one of the quickest causes of cluster trouble to rule out, so check it early. Graylog server nodes, the search backend and the web interface and inputs all rely on TLS certificates, and when one lapses the symptoms often look like something else: nodes that cannot see each other, a search backend that appears unreachable, or a browser warning that users dismiss before anyone looks at the root cause. Node-to-node traffic, connections from Graylog to Data Node or OpenSearch, and HTTPS on the web interface and any TLS-enabled input each use their own certificate chain, so a single expired file can break one path while the rest of the cluster looks healthy.

Start by reading validity dates from the certificate material in the bundle, then confirm them on the live hosts, because the bundle is a snapshot taken at collection time. For each PEM file, run openssl x509 -noout -subject -issuer -enddate to read the subject, issuer and notAfter date, and check the chain with the intermediate and root files that were collected alongside it. On each live node, run the same command against the endpoint with openssl s_client -connect to see what is actually presented. Then confirm which file each component loads by reading its configuration: the TLS settings in server.conf for Graylog, the Data Node or OpenSearch security configuration, and any reverse proxy or load balancer. A mismatch between the file on disk and the certificate served at runtime is a finding in its own right.

Record every expiry date in the diagnosis notes, together with the component, the file path and the node, before you move to escalation. Set a renewal check with a named owner and a date that falls comfortably before the earliest notAfter value, and confirm with your certificate authority or internal PKI team how long their renewal process takes, since that lead time is not something the bundle can tell you. If a certificate has already expired, say so in the first line of the escalation so the vendor or partner does not spend time on symptoms that a renewal would fix.

Which collection scope fits which symptom

This table compares three collection scopes for a Graylog support bundle: a single node, the full cluster, and a targeted set of logs and configuration. Read each row against the symptom you are chasing, then check the options your Graylog version and deployment method actually offer. A narrower scope is smaller and faster to hand over, but a cluster-wide fault often shows up only when every node is included.

Collection scopeBest fit for this symptomWhat it includes and leaves outTrade-off on size, sensitivity and time
Single nodeOne Graylog server node shows high journal use, a stuck process buffer, or errors that appear only on that hostNode-local logs, JVM and system details, and that node's configuration. Other nodes, MongoDB and the search backend are usually absent.Smallest and quickest to collect, but it carries less secret material. It can miss a cause that lives on another node or on the search backend.
Full clusterSearches fail or time out across nodes, nodes disagree on state, or leader and follower behavior looks wrongData from every Graylog node in the cluster, giving a view of the whole deployment. Confirm in the docs whether the search backend and MongoDB are included for your version.Largest and slowest to collect and review. It carries the most sensitive configuration, so redaction takes longer before you share it.
Targeted logs and configurationA known fault after a change, such as a certificate problem, a failed upgrade step, or an input that stopped receiving messagesSelected log files and configuration files for the components involved. Anything outside the chosen set is left out.Fastest to review and easiest to redact, but only as complete as your guess about the cause. Add scope if the first review does not point to a cause.
Certificate and TLS checkClients or inputs fail with handshake errors, or the web interface reports an expired or untrusted certificateCertificate files and TLS settings on the nodes concerned. Private keys must be excluded from anything you share.Small and low sensitivity when keys are removed, but it shows nothing about journal or search problems.
Version and deployment method checkAny scope choice where the bundle contents differ by release or by package, Docker or Kubernetes installWhatever the bundle tooling collects for your specific release and install method. Behavior differs between versions, so the contents are not fixed.Costs time up front to confirm contents, but prevents sending a bundle that lacks the file you need.

Redacting secrets before sharing by audience

Engineers inside your organization usually need the operational detail in a bundle: node roles, journal figures, index state, error stack traces and configuration shape. They still should not see live credentials, because a bundle often outlives the incident and gets copied into tickets, chat threads and laptops. Treat the redacted copy as the working copy and keep the raw bundle in controlled storage.

  • Remove credentials: strip the password_secret, root_password_sha2, API tokens, and any password or secret values from configuration excerpts and log lines.
  • Mask connection strings: replace the credentials inside MongoDB and OpenSearch or Data Node URIs while leaving the host names and ports that the diagnosis needs.
  • Keep: version numbers, node and cluster identifiers, buffer and journal metrics, index names and sizes, and timestamps.
  • Review personal data in messages: log samples in the bundle can contain user names, email addresses and IP addresses from the sources you ingest, so mask them unless the engineer needs one specific value.
  • Verify: run a search for common secret patterns across the redacted archive and record who performed the check.

Before sharing internally, confirm that the recipient's role already has access to the source logs the bundle samples.

Collecting a bundle on a running cluster

This sequence collects a Graylog support bundle from a live cluster without pausing ingestion, and ends with a complete, readable archive that is logged and stored under access control. Each step has a check so the bundle can be trusted before anyone starts diagnosing from it.

  1. Confirm version and nodes in scope

    The engineer on call records the Graylog server version on every node, the Data Node or OpenSearch version, and the MongoDB version, then lists each Graylog node, including followers where is_leader is set to false. Compare the versions against the compatibility matrix for the release in use, since the bundle reflects the running build. Done when the node inventory matches the node list in the cluster configuration and every version is written into the incident or change record. Confirm the exact version lookup path and node listing method in the current Graylog documentation before you rely on them.

  2. Record time and cluster state

    Before collecting anything, note the current UTC time, the incident start time if one exists, and the cluster state as shown in the system overview: node health, journal utilization, input and output status, and any active alerts. Capture a screenshot or export of the same view so the state can be compared later. This record separates conditions that existed before collection from anything collection itself might have changed. Done when the timestamped state note is saved with the ticket. Confirm where the web interface shows these values in your Graylog version.

  3. Check access and collection permissions

    Confirm that the person collecting the bundle holds an administrator role that allows it, and that the account used is named, not shared. Check that the browser or command-line session reaches every node's API address directly, since a load balancer may route the request to one node only. Done when a test request to each node returns the expected response. Confirm the required role and the documented collection method for your version in the current Graylog documentation.

  4. Run the documented collection on each node

    Run the support bundle collection that the Graylog documentation describes for your version, either from the web interface or the documented command or API route, and repeat it on each node in scope. Collection reads logs, configuration and runtime state, so it does not stop ingestion, but the team should avoid restarts or configuration changes during the run. Record the start and end time and the node name for each archive. Done when every node has produced one archive and the run log shows no errors. Confirm the exact method, output location and whether the bundle is cluster-wide in the current Graylog documentation.

  5. Check that every node contributed

    Open the inventory of archives and match each file against the node inventory from the first step. Look for the node name or identifier inside each archive and confirm the node's configuration, log and version files are present and non-empty. A missing or zero-byte archive means the bundle is incomplete and the affected node must be collected again before diagnosis starts. Done when the count of archives equals the count of nodes in scope and each one contains the expected files. Confirm the file names and layout for your version before you write this check into a runbook.

  6. Confirm the archive opens and reads cleanly

    Extract each archive into a scratch directory on a machine that is not the Graylog node, then list the contents and open the main configuration and log files to confirm they are readable text and the archive is not truncated. Check that timestamps in the logs cover the window recorded in the second step. Done when every archive extracts without errors and the expected time range appears in the logs. If an archive fails to extract, collect that node again rather than repairing the file by hand.

  7. Store the bundle with an access record

    Move the verified archives into a restricted storage location that only the incident team can read, with encryption at rest where your policy requires it. Write an access record listing the bundle identifiers, the collecting person, the collection time, the nodes covered, the storage location and everyone granted access. Do not attach the raw archives to tickets or chat. Done when the storage location, the access list and the record all match and the record is linked to the incident. Redaction happens before any bundle leaves the team, so check the separate redaction step before sharing.

Secrets and access risks in a support bundle

A support bundle gathers configuration, logs and runtime state from several components in one archive, so one careless share can expose more than a single file would. The cards below cover the risks that recur when a bundle leaves your environment, and the control to put in place before anyone collects or sends one.

Configuration secrets in server config

The server configuration holds values such as the server secret and root credentials. Treat any copy of that configuration inside a bundle as a live secret, because anyone holding it may be able to sign in or impersonate the server. Before sending, check the collected configuration for these keys and confirm with the vendor how the bundle handles them, since this page does not claim the bundle masks them. If a value has been shared, rotate it on the Graylog nodes and update every node that uses it.

Backend credentials in connection settings

Connection strings for MongoDB and the search backend, whether Graylog Data Node or self-managed OpenSearch, may carry usernames and passwords. These credentials often grant wider access than the Graylog service needs, because they reach the configuration database or the log indices directly. Search the bundle for connection URIs and credential fields before sharing. Rotate any backend password that appears in a bundle, and confirm that the Graylog service account has only the roles it needs.

Private keys and certificate chains

Bundles that include certificate or keystore material can expose private keys, which allow impersonation of the Graylog web interface or inputs with TLS. Public certificates are lower risk but still reveal internal host names and trust paths. Confirm whether your bundle includes key files, and if one has been exposed, reissue the certificate and retire the old key. Keep certificate expiry checks in the diagnosis, but share only the expiry dates and subject names, not the key material.

Personal and regulated data in logs

Log excerpts in a bundle reflect whatever your sources sent, which can include personal, health, payment or other regulated data. A bundle taken to debug a parsing problem may carry real messages from production streams. Limit the log portion to the time window and streams that the issue needs, and review sample messages before they leave your environment. Where the data is regulated, agree in writing how the vendor will handle, store and delete it.

Access to the bundle store

A collected bundle sits on the node or in storage until someone deletes it, and any user who can download it gains the same view as the operator. Restrict which roles can request or download bundles, keep the storage location on a controlled path, and record who collected each bundle and when. Remove old bundles on a fixed schedule so that stale copies do not accumulate. Ask your team to confirm the current permissions for the bundle directory on each node.

Sharing through unapproved channels

Emailing a bundle, posting it in a public ticket or uploading it to a general file service sends secrets and log data to places your handling rules do not cover. Agree the approved transfer method and the support contact before collection starts, and state that the bundle is confidential. Ask the vendor for their written handling terms, including retention and deletion. Send only to the named recipient, and confirm receipt through a channel you control.

Questions teams ask before collecting or sharing a bundle

Can our own team read a Graylog support bundle without a partner?

Yes, a team that already runs Graylog can read most of a support bundle, provided it knows which files describe the server, the journal, the search backend and the certificates. The bundle is a snapshot of configuration and state, so the hard part is not opening the files but knowing which symptom points to which file and which values are normal for your cluster size. Teams without a Graylog operator on call usually benefit from a written diagnosis order and a second pair of eyes on the first few incidents. Start with the Graylog documentation for your running version, because file layouts and settings can change between the 7.x releases.

How long does a support bundle diagnosis usually take?

The time depends on how many nodes are involved, how clearly the symptom is described and whether the problem sits in one component or spans several. A single stalled node with a visible certificate error is quick to narrow down. A cluster with journal growth, slow search and intermittent authentication failures needs each symptom traced to its source before any fix is chosen. Ask any partner to state, in the written scope, which bundles, nodes and environments are covered and what happens if the first findings point to a component outside that scope. We do not publish a fixed duration for this work.

What does a partner need from us before diagnosing a bundle?

A partner needs the bundle itself, a short description of the symptom with its start time, the Graylog and backend versions in use, and the cluster layout (number of Graylog nodes, MongoDB members and Data Nodes or OpenSearch nodes). Access to the environment is usually not needed for the first pass, but a named contact who can answer questions about your network, load balancer and certificate authority saves time. Share the bundle only after redaction, as described in the redaction question, and agree on a secure channel and retention period for it in writing.

What drives the cost of a Graylog support bundle diagnosis?

The cost has three main parts: the time to read and correlate the bundle across nodes, the time to reproduce or confirm the finding in your environment if that is needed, and the time to write up a remediation plan. Costs rise with the number of nodes, the number of separate symptoms, the amount of work needed to redact and review files, and any need for follow-up sessions with your staff. Fixed-scope work is agreed in writing before it starts, so a quote should list the bundles covered, the environments in scope, the deliverable (for example a written diagnosis with prioritized actions), and what is excluded, such as implementing the fix or upgrading the cluster. Ask whether follow-up questions after delivery are included or billed separately.

What should we do when the bundle shows an expired certificate?

Treat an expired certificate as a service-impacting finding, because Graylog nodes, the search backend and clients can fail to connect once a certificate lapses. First, identify which certificate expired from the bundle and check its subject, issuer and validity dates against the certificate files and the configuration keys that reference them. Next, confirm which clients depend on it, such as forwarders, load balancers or inter-node traffic, and schedule the renewal with the certificate owner. Replace the certificate through your normal process, restart or reload the affected components in the order your runbook sets, and then confirm the new validity dates in a fresh bundle. Review your monitoring so the next expiry is alerted well before the date.

Can we send a support bundle to Graylog or another vendor under our contract?

Whether a bundle can leave your environment depends on your contract with the vendor, your data classification rules and any data processing terms that apply to your organization. A bundle contains configuration, logs about the platform and often hostnames, IP addresses and usernames, so it is sensitive even when it holds no customer records. Check with your legal, privacy and security teams before sharing, and confirm what the vendor's support terms say about handling and retention. Redact secrets first. DeployOpen does not issue vendor agreements on your behalf, so the terms that govern a bundle shared with a vendor are those you negotiate with that vendor.

How do we redact secrets from a bundle before sharing it?

Remove or replace every value that grants access or reveals internal structure before the bundle leaves your network. That includes passwords, tokens, API keys, password secrets used for encryption, private keys, MongoDB and OpenSearch credentials, and connection strings that embed them. Keep the key names so the reader can still see that a setting exists and whether it is set. Check log excerpts for session identifiers and personal data too. Record which files you changed and how, so the diagnosing team knows the redaction did not remove the evidence they need. Keep an unredacted copy inside your environment under your normal retention policy.

What to confirm for your Graylog version and environment

A support bundle reflects one version, one deployment method and one backend at one moment. The cards below list what to confirm with your platform owner, security team and Graylog support before you collect, share or interpret a bundle, so the evidence you gather matches the cluster you actually run.

Bundle contents for your exact version

Confirm which files a support bundle contains for the exact Graylog release you run, because the current documentation covers Graylog 7.2 and earlier releases may differ. Ask your platform owner to run the collection on a test node first and list the files it produces. Keep that list with your runbook so the team knows what each file should look like before an incident. Check the release notes for your version before relying on any file name in this guide.

Deployment type and collected data

Confirm with the team that runs your Graylog whether it uses packages, Docker Compose or Kubernetes, because the way logs, configuration files and service status are exposed changes between them. In containers, the bundle may not include host-level files you expect, so ask which paths and sidecars are in scope. Agree in advance how the team will gather any missing host data separately.

Data Node or OpenSearch backend evidence

Confirm whether your search backend is Graylog Data Node or self-managed OpenSearch, since the backend health data you need to diagnose a stalled search or a full journal comes from different tools. Ask your search platform owner which cluster health and shard views they will attach to the bundle. Also confirm which OpenSearch version you run, because the compatibility matrix limits supported versions and deprecates OpenSearch 1.x.

TLS and certificate management

Confirm who owns the certificates used by Graylog nodes, the load balancer and the search backend, and where their expiry dates are tracked. The bundle may show certificate details, but it will not replace your certificate inventory. Ask the owner to name the certificate paths, the renewal process and the contact who receives expiry alerts, so the expiry check in your diagnosis order has a clear answer.

Retention and sharing rules for bundles

Confirm with your security and compliance leads how long bundles may be kept, where they may be stored and who may receive them, because a bundle can contain configuration, hostnames and sensitive values. Ask whether your sector requires a log of who accessed support material. Agree the redaction steps and the approved transfer channel before anyone collects a bundle during an incident.

Multi-node state at one moment

Confirm whether the bundle you collect captures one node or every node in the cluster, and whether the snapshots are taken at the same time. In a multi-node deployment with several Graylog and MongoDB nodes, comparing files taken minutes apart can mislead a diagnosis. Ask your platform owner to collect from each node in a short window and record the collection time per node before drawing conclusions about the leader or journal state.

How DeployOpen scopes and supports Graylog diagnosis work

DeployOpen treats support bundle diagnosis as a defined piece of work on your running Graylog cluster, inside your own infrastructure. We agree the scope, the evidence to collect and the redaction rules in writing before anything is shared outside your network.

How we scope

  • Written scope names the Graylog nodes, MongoDB and search backend whose bundles will be reviewed.
  • Scope states which symptoms are in question, such as journal growth, certificate errors or failed searches.
  • Scope sets the redaction standard and who on your side approves any file leaving your environment.

How we build

  • Diagnosis follows a fixed order: cluster health first, then journal and buffers, then backends and certificates.
  • Certificate expiry checks are run against each node's configured certificates and recorded with dates found.
  • Findings are tested against the live cluster where possible, so each conclusion has a reproducible check behind it.

How we hand over

  • Deliverables include a written diagnosis, the commands used, and the file-by-file reading of the bundle.
  • Redacted copies of any bundle shared with a vendor or auditor are documented with the redaction steps applied.
  • Your team receives a checklist to repeat the diagnosis order on future bundles without outside help.

How we support

  • Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
  • Ongoing support, upgrades and continuous testing are available as a retainer for clusters that need regular review.
  • Quotes follow from the written scope, so ask for the bundle types, nodes and symptoms included when comparing options.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.