feat: fix stderrthreshold not honored when logtostderr is set (#212) + two new flags

[pierluigilenoci]

Description

This PR fixes a long-standing issue (#212) where the -stderrthreshold flag is completely ignored when -logtostderr=true, preventing users from filtering logs by severity level when logging to stderr.

The solution introduces two new flags while maintaining 100% backward compatibility through opt-in behavior.

What type of PR is this?

/kind feature
/kind bug

What this PR does / why we need it

Problem

When -logtostderr=true is set, klog writes all logs to stderr regardless of the -stderrthreshold setting. This causes excessive noise in log outputs and makes it impossible to filter logs by severity, which is particularly problematic for applications that want to reduce log verbosity (see #212 and Azure/secrets-store-csi-driver-provider-azure#387).

Solution

This PR adds two new flags:

1. -legacy_stderr_threshold_behavior (default: true)

   • true (default): Maintains current behavior - all logs go to stderr when -logtostderr=true
   • false: New behavior - honors -stderrthreshold even when -logtostderr=true

2. -alsologtostderrthreshold (default: INFO)

   • Provides severity filtering specifically for -alsologtostderr=true
   • Default value maintains backward compatibility (all logs mirror to stderr)
   • Can be set to WARNING or ERROR for finer control

Additional Fix

Fixed a bug in severityValue.Set() where it was hardcoded to always set logging.stderrThreshold, preventing multiple severityValue instances from working independently.

Usage Examples

Enable severity filtering (new behavior):

./myapp -logtostderr=true \
        -legacy_stderr_threshold_behavior=false \
        -stderrthreshold=ERROR

Result: Only ERROR and FATAL messages appear in stderr.

Filter logs when mirroring to stderr:

./myapp -logtostderr=false \
        -alsologtostderr=true \
        -alsologtostderrthreshold=WARNING \
        -log_dir=/var/log/myapp

Result: All logs in files, only WARNING+ to stderr.

Which issue(s) this PR fixes

Fixes #212

Special notes for your reviewer

• Backward compatibility: All existing behavior is preserved by default. The new functionality is strictly opt-in.
• Testing: Added comprehensive unit tests covering both legacy and new behavior
• No breaking changes: All existing applications continue to work without modification

Does this PR introduce a user-facing change?

Add optional severity filtering for stderr output when -logtostderr=true through new -legacy_stderr_threshold_behavior flag (default: true for backward compatibility). Add -alsologtostderrthreshold flag for finer control when using -alsologtostderr=true.

Additional documentation

See the example in examples/stderr_threshold_fix/main.go for a practical demonstration.

Migration Guide

For end users: No action required. Default behavior unchanged.

To opt into severity filtering:

1. Set -legacy_stderr_threshold_behavior=false
2. Use -stderrthreshold=ERROR (or WARNING) to filter logs

Related PRs/Issues

• Original PR (reverted due to breaking changes): stderrthreshold is useless if logtostderr is set #31
• Revert PR: Revert default changes #50
• Previous attempt: Stderr threshold issue fix #221
• Related issue: Problems with log configurations  Azure/secrets-store-csi-driver-provider-azure#387

[k8s-ci-robot]

This issue is currently awaiting triage.

If klog contributors determine this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[pierluigilenoci]

@harshanarayana @thockin @dims @pohly @mengjiao-liu I'm tagging you to get your feedback.

@aramase @neolit123 @yagonobre @yuzhiquan @serathius @mtaufen @DirectXMan12 @vincepri @shsjshentao @dims @justinsb I'm tagging you too because you were involved in the discussion and attempted to resolve this issue several years ago.

[pohly]

I'm undecided whether it's worth fixing this. But at least now it's not a breaking change, so I am okayish with trying. I haven't looked at all code changes yet.

[pierluigilenoci]

@pohly, do you have any news about this PR?

[pohly]

@pierluigilenoci: it took you more than two years to come up with this PR since we last discussed the issue. It's not urgent, is it? So please understand that reviewers are not immediately jumping on reviewing this. For example, I am on vacation.

[pierluigilenoci]

@pohly Thanks for the heads-up, and enjoy your vacation!

You’re right—it took me a long time to open this PR. I just hadn’t had the time or mental bandwidth to tackle a change this complex earlier. Now that I’ve finally put together a solution, I’m confident it’s non-breaking and a net positive: logs would finally be handled in accordance with the flags.

No urgency at all—please take your time. When you or other reviewers are available, I’d appreciate any feedback. I’m happy to adjust the implementation, add tests, or split things up if that helps.

[pierluigilenoci]

@pohly, would you be able to take a look at this PR in the following days?

[pierluigilenoci]

@pohly, do you think you'll have time to review my PR?

[pohly]

I can't promise anything at this point. IMHO it has low priority and there's always something else that needs my attention more urgently.

[pohly]

Some minor nits. I don't see any problem with the logic, but there's always a risk that I am missing something. Therefore I'm still unsure whether it really makes sense to extend klog. We've long said that it's feature set is frozen.

@pierluigilenoci: are you really going to use the new flags or did you just submit the PR to get closure on a years old issue?

@aramase, @deyanp, @tallclair, @kcone, @nyejon: you all commented on #212 at some point. Does it really still make sense to fix that issue?

[pierluigilenoci]

@pierluigilenoci: are you really going to use the new flags or did you just submit the PR to get closure on a years old issue?

The next step, at least for me, would be to fix the tools I use that are driving me crazy with this bug.

And of course, if @aramase agree, to fix this Azure/secrets-store-csi-driver-provider-azure#387

[pierluigilenoci]

@pohly I've implemented both of your suggested changes in commit 39c4c76:

1. ✅ Moved alsologtostderrthreshold initialization: Both stderrThreshold and alsologtostderrthreshold are now initialized at the beginning of init(), grouped together before the commandLine.Var() calls for better organization.

2. ✅ Simplified conditional logic: Combined the separate checks into a single if statement with || operators spread across multiple lines. This avoids redundant .get() calls when alsoToStderr is already true and improves readability.

All tests continue to pass. Thanks for the review feedback!

[pierluigilenoci]

@pohly I wanted to share some thoughts on how to frame this PR.

While I understand the concern about adding features to a frozen codebase, I'd like to suggest viewing this more as a bug fix rather than a new feature. The current behavior where -stderrthreshold is completely ignored when -logtostderr=true has been causing issues for years (as evidenced by #212 and related discussions). Users reasonably expect that a flag designed to filter logs by severity should work, but it simply doesn't in this common configuration.

The approach I've taken ensures zero breaking changes through the opt-in legacy_stderr_threshold_behavior flag (defaulting to true). Existing applications continue to work exactly as before without any modifications. The new behavior only activates when users explicitly choose it, making this a very safe addition.

I believe that once klog consumers discover this capability exists, many will adopt it naturally because it solves a real pain point—excessive log noise when using stderr output. The fact that this issue has persisted for years and keeps resurfacing in discussions suggests there's genuine need for this functionality.

In essence, we're not adding new features to klog—we're fixing a long-standing bug in a backward-compatible way that finally makes the existing flags work as users would intuitively expect them to.

Thank you for taking the time to review this carefully. I appreciate your thoughtful feedback!

[BenTheElder]

@pierluigilenoci I suggest only referring back to this in the PR bodies instead of the commits, it's really hard to follow the history of this thread.