> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cockroach debug merge-logs

The `cockroach debug merge-logs` [command](https://docs.cockroachlabs.com/docs/stable/cockroach-commands.md) merges log files from multiple nodes into a single time-ordered stream of messages with an added per-message prefix to indicate the corresponding node. You can use it in conjunction with logs collected using the [`debug zip`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-zip) command to aid in debugging.

> [!CAUTION]
>
> The file produced by `cockroach debug zip` can contain highly [sensitive, identifiable information](https://docs.cockroachlabs.com/docs/stable/configure-logs.md#redact-logs), such as usernames, hashed passwords, and possibly your table's data. You can use the [`--redact`](#example) flag to redact the sensitive data out of log files and crash reports before sharing them with Cockroach Labs.

## Subcommands

While the `cockroach debug` command has a few subcommands, users are expected to use only the [`zip`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-zip), [`upload`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-upload), [`encryption-active-key`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-encryption-active-key), [`merge-logs`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-merge-logs), [`list-files`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-list-files), [`tsdump`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-tsdump), and [`ballast`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-ballast) subcommands.

We recommend using the [`encryption-decrypt`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-encryption-decrypt) and [`job-trace`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-job-trace) subcommands only when directed by the [Cockroach Labs support team](https://docs.cockroachlabs.com/docs/stable/support-resources.md).

The other `debug` subcommands are useful only to Cockroach Labs. Output of `debug` commands may contain sensitive or secret information.

## Synopsis

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug merge-logs [log file directory] [flags]
```

## Flags

The `debug merge-logs` subcommand supports the following flags:

| Flag | Description |
| - | - |
| `--format` | **Required** The [format of the logs](https://docs.cockroachlabs.com/docs/stable/log-formats.md) in the log file directory. The logs in a `.zip` generated using [`cockroach debug zip`](https://docs.cockroachlabs.com/docs/stable/cockroach-debug-zip) are of type [`crdb-v1`](https://docs.cockroachlabs.com/docs/stable/log-formats#format-crdb-v1). |
| `--filter` | Limit the results to the specified regular expression |
| `--from` | Start time for the time range filter. |
| `--to` | End time for the time range filter. |
| `--redact` | Redact [sensitive data](https://docs.cockroachlabs.com/docs/stable/configure-logs.md#redact-logs) from the log files. |

## Example

Generate a debug zip file:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach debug zip ./cockroach-data/logs/debug.zip --insecure
```

Unzip the file:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
unzip ./cockroach-data/logs/debug.zip
```

Merge the logs in the debug folder:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1
```

Alternatively, filter the merged logs for a specified time range:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1 --from="231031 19:19:50.917185" --to="231031 19:19:57.189263"
```

You can also filter the merged logs for a regular expression:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1 --filter="ALL SECURITY CONTROLS HAVE BEEN DISABLED"
```

You can redact sensitive information from the merged logs:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1 --redact
```

## Considerations

As of v23.2, logs can be configured to use a [timezone with formats `crdb-v1` or `crdb-v2`](https://docs.cockroachlabs.com/docs/stable/configure-logs#set-timezone). This is a [backward-incompatible change](https://docs.cockroachlabs.com/docs/releases/v23.2.md). `cockroach debug merge-logs` requires v23.2 or later if run against logs with the timezone configured. With versions prior to v23.2, `cockroach debug merge-logs` will return an error if run against logs with the timezone configured.

## See also

* [Support Resources](https://docs.cockroachlabs.com/docs/stable/support-resources.md)
* [`cockroach` Commands Overview](https://docs.cockroachlabs.com/docs/stable/cockroach-commands)
* [Troubleshooting Overview](https://docs.cockroachlabs.com/docs/stable/troubleshooting-overview.md)