cli,server: add --exclude-log-severities flag to debug zip by aa-joshi · Pull Request #165802 · cockroachdb/cockroach

aa-joshi · 2026-03-16T10:24:31Z

Add an --exclude-log-severities flag to debug zip that filters out
log entries by severity server-side. For large clusters, INFO-level
logs can be extremely voluminous and often aren't needed for debugging.
This flag allows operators to exclude specific severity levels
(e.g. --exclude-log-severities=INFO) to reduce both network transfer
and zip file size.

The implementation adds a new exclude_severities repeated field to
the LogFileRequest protobuf message. The LogFile() RPC handler
builds an exclusion set and skips matching entries during the decode
loop. On the CLI side, severity names are validated early in
runDebugZip and converted to proto values before being passed in
each per-node LogFileRequest.

Rolling upgrade compatibility is maintained without a version gate:
old servers ignore the unknown protobuf field (graceful degradation),
and old clients send an empty field (no filtering).

Epic: none
Fixes: CRDB-61602

Release note (cli change): Added --exclude-log-severities flag to
cockroach debug zip that filters log entries by severity server-side.
For example, --exclude-log-severities=INFO excludes all INFO-level log
entries from the collected log files, which can significantly reduce
zip file size for large clusters. Valid severity names are INFO,
WARNING, ERROR, and FATAL. The flag accepts a comma-delimited list or
can be specified multiple times.

trunk-io · 2026-03-16T10:24:35Z

😎 Merged successfully - details.

cockroach-teamcity · 2026-03-16T10:24:46Z

This change is

Abhinav1299 · 2026-03-17T06:15:19Z

pkg/cli/zip.go

+	// Validate excluded log severities.
+	for _, name := range zipCtx.excludeLogSeverities {
+		if _, ok := logpb.SeverityByName(name); !ok {
+			return errors.Newf(
+				"unknown log severity %q; valid values are INFO, WARNING, ERROR, FATAL",
+				name,
+			)
+		}
+	}
+


NIT: We are doing the same parsing again in zip_per_node.go file for converting severity names to its proto values. Can we convert it at one place only? Just after validation here seems logical as other conversion is done in zip_per_node file which is for every node. We can store the severity detail in ZipCtx here.

I thought about it. With your suggestion, the ZipCtx would have redundant declaration: one for array of string and another one for array of logSeverity. I am trying to avoid it here.

Abhinav1299 · 2026-03-17T06:18:16Z

pkg/cli/zip.go

+		if _, ok := logpb.SeverityByName(name); !ok {
+			return errors.Newf(


Should we also add a validation for case sensitivity here? User can input --exclude-log-severity=info or --exclude-log-severity=INFO

SeverityByName func is converting to upper case and then performing validation.

Abhinav1299 · 2026-03-17T06:22:53Z

pkg/cli/cliflags/flags.go

+<PRE>
+
+</PRE>


This PRE block seems to be empty, was it intentional?

It is intentional to avoid text wrapping in --help command.

Abhinav1299 · 2026-03-17T06:24:16Z

pkg/cli/cliflags/flags.go

 	}

+	ZipExcludeLogSeverity = FlagInfo{
+		Name: "exclude-log-severity",


NIT: can we change the flag name to exclude-log-severities

Abhinav1299 · 2026-03-17T06:27:25Z

pkg/cli/zip.go

+		if _, ok := logpb.SeverityByName(name); !ok {
+			return errors.Newf(
+				"unknown log severity %q; valid values are INFO, WARNING, ERROR, FATAL",
+				name,


Currently there are 7 severity levels possible, should we add a check to limit unwanted severities? Like UNKNOWN and NONE ?

The UNKNOWN and NONE log severities for unexpected and rare events. It means that we can not determine the log severity. In such situation, it make sense to include log of such severities all the time.

Add an `--exclude-log-severities` flag to `debug zip` that filters out log entries by severity server-side. For large clusters, INFO-level logs can be extremely voluminous and often aren't needed for debugging. This flag allows operators to exclude specific severity levels (e.g. `--exclude-log-severities=INFO`) to reduce both network transfer and zip file size. The implementation adds a new `exclude_severities` repeated field to the `LogFileRequest` protobuf message. The `LogFile()` RPC handler builds an exclusion set and skips matching entries during the decode loop. On the CLI side, severity names are validated early in `runDebugZip` and converted to proto values before being passed in each per-node `LogFileRequest`. Rolling upgrade compatibility is maintained without a version gate: old servers ignore the unknown protobuf field (graceful degradation), and old clients send an empty field (no filtering). Epic: none Fixes: CRDB-61602 Release note (cli change): Added `--exclude-log-severities` flag to `cockroach debug zip` that filters log entries by severity server-side. For example, `--exclude-log-severities=INFO` excludes all INFO-level log entries from the collected log files, which can significantly reduce zip file size for large clusters. Valid severity names are INFO, WARNING, ERROR, and FATAL. The flag accepts a comma-delimited list or can be specified multiple times.

aa-joshi

@aa-joshi made 5 comments and resolved 1 discussion.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on Abhinav1299, arjunmahishi, and kyle-a-wong).

aa-joshi · 2026-03-17T08:19:27Z

pkg/cli/zip.go

+		if _, ok := logpb.SeverityByName(name); !ok {
+			return errors.Newf(


SeverityByName func is converting to upper case and then performing validation.

aa-joshi · 2026-03-17T08:19:28Z

pkg/cli/zip.go

+		if _, ok := logpb.SeverityByName(name); !ok {
+			return errors.Newf(
+				"unknown log severity %q; valid values are INFO, WARNING, ERROR, FATAL",
+				name,


The UNKNOWN and NONE log severities for unexpected and rare events. It means that we can not determine the log severity. In such situation, it make sense to include log of such severities all the time.

aa-joshi · 2026-03-17T08:19:28Z

pkg/cli/zip.go

+	// Validate excluded log severities.
+	for _, name := range zipCtx.excludeLogSeverities {
+		if _, ok := logpb.SeverityByName(name); !ok {
+			return errors.Newf(
+				"unknown log severity %q; valid values are INFO, WARNING, ERROR, FATAL",
+				name,
+			)
+		}
+	}
+


I thought about it. With your suggestion, the ZipCtx would have redundant declaration: one for array of string and another one for array of logSeverity. I am trying to avoid it here.

aa-joshi · 2026-03-17T08:19:28Z

pkg/cli/cliflags/flags.go

 	}

+	ZipExcludeLogSeverity = FlagInfo{
+		Name: "exclude-log-severity",


aa-joshi · 2026-03-17T08:19:29Z

pkg/cli/cliflags/flags.go

+<PRE>
+
+</PRE>


It is intentional to avoid text wrapping in --help command.

Abhinav1299

LGTM
few NITs:

Can we update the commit and PR description to have --exclude-log-severities instead of --exclude-log-severity.
Can you check the failing CI check.

aa-joshi

TFTR!

@aa-joshi made 1 comment.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on Abhinav1299, arjunmahishi, and kyle-a-wong).

aa-joshi force-pushed the introduce_log_filters branch from 14e4cbb to 94b867b Compare March 16, 2026 15:28

aa-joshi marked this pull request as ready for review March 16, 2026 15:29

aa-joshi requested review from a team as code owners March 16, 2026 15:29

aa-joshi requested review from Abhinav1299, arjunmahishi and kyle-a-wong and removed request for a team March 16, 2026 15:29

Abhinav1299 reviewed Mar 17, 2026

View reviewed changes

aa-joshi force-pushed the introduce_log_filters branch from 94b867b to f3e946d Compare March 17, 2026 08:18

aa-joshi commented Mar 17, 2026

View reviewed changes

Abhinav1299 approved these changes Mar 17, 2026

View reviewed changes

aa-joshi changed the title ~~cli,server: add --exclude-log-severity flag to debug zip~~ cli,server: add --exclude-log-severities flag to debug zip Mar 17, 2026

aa-joshi commented Mar 17, 2026

View reviewed changes

trunk-io bot merged commit fa98ab3 into cockroachdb:master Mar 17, 2026
51 of 56 checks passed

celeste-cockroachdb bot added the target-release-26.2.0 label Mar 17, 2026

		if _, ok := logpb.SeverityByName(name); !ok {
		return errors.Newf(

		<PRE>

		</PRE>

		<PRE>

		</PRE>

Conversation

aa-joshi commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

trunk-io bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cockroach-teamcity commented Mar 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhinav1299 Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aa-joshi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhinav1299 left a comment

Choose a reason for hiding this comment

Uh oh!

aa-joshi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aa-joshi commented Mar 16, 2026 •

edited

Loading

trunk-io bot commented Mar 16, 2026 •

edited

Loading

Abhinav1299 Mar 17, 2026 •

edited

Loading