Generate a Debug Bundle in Linux

Use rpk or Redpanda Console to generate a debug bundle to diagnose issues yourself, or send it to the Redpanda support team to help resolve your issue.

Prerequisites

You must have rpk installed on your host machine.

Generate a debug bundle with rpk

To generate a debug bundle with rpk, you can run the rpk debug bundle command on each broker in the cluster.

  1. Execute the rpk debug bundle command on a broker:

    rpk debug bundle

    If you have an upload URL from the Redpanda support team, provide it in the --upload-url flag to upload your debug bundle to Redpanda.

    rpk debug bundle \
  --upload-url <url>

    Example output:

    Creating bundle file...

Debug bundle saved to "/var/lib/redpanda/1675440652-bundle.zip"

  2. On your host machine, make a directory in which to save the debug bundle:

    mkdir debug-bundle

  3. Copy the debug bundle ZIP file to the debug-bundle directory on your host machine.

  4. Unzip the file on your host machine.

    cd debug-bundle
unzip <bundle-name>.zip

  5. Remove the debug bundle from the Redpanda broker:

    rm /var/lib/redpanda/<bundle-name>.zip
    To avoid manually deleting debug bundles, you can configure the debug_bundle_auto_removal_seconds property to automatically remove them after a period of time. See Automatically remove debug bundles.

When you’ve finished troubleshooting, remove the debug bundle from your host machine:

rm -r debug-bundle

For a description of the files and directories, see [Contents of the debug bundle].

Generate a debug bundle with Redpanda Console

See Manage Debug Bundles in Redpanda Console.

Automatically remove debug bundles

To avoid manually deleting debug bundles, you can configure the debug_bundle_auto_removal_seconds property. This cluster configuration property automatically deletes debug bundles after the specified number of seconds. By default, this property is not set, meaning debug bundles are retained indefinitely.

Only one debug bundle can exist at a time. If you generate a new debug bundle, any existing bundle from a previous run will be automatically deleted.

Changes to this property take effect immediately and do not require a cluster restart.

To set this property, use the rpk cluster config command:

rpk cluster config set debug_bundle_auto_removal_seconds <seconds>

For example, to retain debug bundles for 1 day:

rpk cluster config set debug_bundle_auto_removal_seconds 86400

Choose where the debug bundle is saved

The debug_bundle_storage_dir property allows you to specify a custom directory for storing debug bundles. By default, debug bundles are stored in the Redpanda data directory. Configuring a custom storage directory can help manage storage capacity and isolate debug data from operational data.

Changes to this property take effect immediately and do not require a cluster restart.

Before you change this property:

  • Ensure that your chosen directory has sufficient storage capacity to handle debug bundles.

    Factors such as the volume of logs can increase the bundle size. While it is difficult to define an exact storage requirement due to variability in bundle size, 200 MB should be sufficient for most cases.

  • Verify the directory’s permissions to ensure Redpanda can write to it. By default, Redpanda operates as the redpanda user within the redpanda group.

To set a custom debug bundle storage directory, use the rpk cluster config command:

rpk cluster config set debug_bundle_storage_dir <path-to-directory>

For example, to store debug bundles in /var/log/redpanda/debug_bundles:

rpk cluster config set debug_bundle_storage_dir /var/log/redpanda/debug_bundles