server: add --fine-grain-log-levels CLI argument for startup log verbosity by Retr0-XD · Pull Request #44067 · envoyproxy/envoy

Retr0-XD · 2026-03-21T10:16:24Z

Description

Currently, fine-grain logging (per-source-file log level control) can only be configured at runtime via the admin API. This is inconvenient for containerized deployments (e.g. Kubernetes) where users want file-level log verbosity from startup without admin access.

This PR adds --fine-grain-log-levels as a startup CLI argument that accepts a comma-separated list of glob:level pairs, mirroring the format already supported by the admin /logging?paths=… endpoint.

Example usage

envoy --enable-fine-grain-logging \
      --fine-grain-log-levels "*filter*:debug,source/common/common/*:trace"

Glob patterns follow the existing FineGrainLogContext::safeFileNameMatch semantics:

Patterns without / are matched against the base filename only.
Patterns with / are matched against the full source path.

Changes

File	Change
`envoy/server/options.h`	Added `fineGrainLogLevels()` PURE virtual method
`source/server/options_impl_base.h`	Added `fine_grain_log_levels_` member + accessor
`source/server/options_impl.cc`	Added `--fine-grain-log-levels` TCLAP arg + `parseFineGrainLogLevels()`
`source/server/options_impl.h`	Declared `parseFineGrainLogLevels()`
`source/exe/main_common.cc`	Applied levels via `getFineGrainLogContext().updateVerbositySetting()` at startup
`api/envoy/admin/v3/server_info.proto`	Added `fine_grain_log_levels` field (field 43)
`test/mocks/server/options.h`	Mocked `fineGrainLogLevels()`
`test/server/options_impl_test.cc`	Added 4 new tests

Risk

Low. The flag is completely opt-in — it is a no-op unless `--enable-fine-grain-logging` is also set, and it calls the same `updateVerbositySetting` API already used by the admin endpoint.

AI disclosure: GitHub Copilot was used during implementation and test writing. I fully understand all changes made in this PR.

Commit Message: See PR title
Risk Level: Low
Testing: Unit tests added/verified
Docs Changes: N/A
Release Notes: N/A
Platform Specific Features: N/A

repokitteh-read-only · 2026-03-21T10:16:31Z

Hi @Retr0-XD, welcome and thank you for your contribution.

We will try to review your Pull Request as quickly as possible.

In the meantime, please take a look at the contribution guidelines if you have not done so already.

🐱

Caused by: #44067 was opened by Retr0-XD.

see: more, trace.

repokitteh-read-only · 2026-03-21T10:16:36Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @adisuissa
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #44067 was opened by Retr0-XD.

see: more, trace.

agrawroh · 2026-03-21T21:44:07Z

@Retr0-XD Please fix the DCO.

/wait

Retr0-XD · 2026-03-22T05:56:15Z

@Retr0-XD Please fix the DCO.

/wait

Added DCO

adisuissa

/lgtm api

adisuissa · 2026-03-23T18:55:18Z

Assigning @botengyao as code-owner
/assign @botengyao

Retr0-XD · 2026-03-25T17:47:30Z

@botengyao please review this PR :)

botengyao · 2026-03-25T17:56:41Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a new command-line option, --fine-grain-log-levels, to enable file-level logging verbosity configuration. This feature allows users to specify log levels for specific file patterns, building upon the existing --enable-fine-grain-logging functionality. The changes include updating the CommandLineOptions proto, extending the Options interface, implementing argument parsing and validation in options_impl.cc, and applying these settings to the FineGrainLogContext. Feedback from the review suggests improving the Doxygen comment for the new fineGrainLogLevels method for clarity and optimizing the parseFineGrainLogLevels function by utilizing absl::string_view to enhance memory efficiency.

gemini-code-assist · 2026-03-25T18:06:02Z

+   * @return const std::vector<std::pair<std::string, spdlog::level::level_enum>>& pair of
+   * glob-pattern,log-level for all configured fine-grain log overrides.


The Doxygen comment for @return is a bit confusing as it includes the return type, and the description is awkwardly phrased across two lines. For better clarity and adherence to common Doxygen style, consider rephrasing it to focus only on the description of the returned value on a single line.

* @return A vector of (glob-pattern, log-level) pairs for fine-grain log overrides.

kind of leaning towards this AI comment ;-)

gemini-code-assist · 2026-03-25T18:06:02Z

+  std::vector<std::string> log_levels = absl::StrSplit(fine_grain_log_levels, ',');
+  for (auto& level : log_levels) {
+    std::vector<std::string> glob_level = absl::StrSplit(level, absl::MaxSplits(':', 1));
+    if (glob_level.size() != 2) {
+      logError(
+          fmt::format("error: fine-grain log level not correctly specified '{}'", level));
+    }
+    const std::string glob = glob_level[0];
+    auto status_or_error = parseAndValidateLogLevel(glob_level[1]);
+    if (!status_or_error.status().ok()) {
+      logError(std::string(status_or_error.status().message()));
+    }
+    fine_grain_log_levels_.push_back(std::make_pair(glob, status_or_error.value()));
+  }


This function can be made more efficient by using absl::string_view to avoid intermediate string allocations when splitting the input string. absl::StrSplit can produce a vector of string_views which refer to slices of the original input string, which is more memory-efficient than creating new strings for each split part.

std::vector<absl::string_view> log_levels = absl::StrSplit(fine_grain_log_levels, ','); for (absl::string_view level : log_levels) { std::vector<absl::string_view> glob_level = absl::StrSplit(level, absl::MaxSplits(':', 1)); if (glob_level.size() != 2) { logError( fmt::format("error: fine-grain log level not correctly specified '{}'", level)); } const std::string glob(glob_level[0]); auto status_or_error = parseAndValidateLogLevel(glob_level[1]); if (!status_or_error.status().ok()) { logError(std::string(status_or_error.status().message())); } fine_grain_log_levels_.emplace_back(glob, status_or_error.value()); }

I agree with AI.

botengyao

sorry for the delay, and thanks for the great contribution. Could you pls also add a changelog at changelogs/current.yaml?

/wait

botengyao · 2026-03-26T13:58:23Z

@@ -722,6 +722,8 @@ def check_source_line(self, line, file_path, report_error):
            report_error("Don't use 'using testing::Test;, elaborate the type instead")
        if line.startswith("using testing::TestWithParams;"):
            report_error("Don't use 'using testing::Test;, elaborate the type instead")
+        if re.match(r"^\s*using\s+\w+\s*=\s*[^;]*\*[^;]*;", line) and "(" not in line:
+            report_error("Don't type alias raw pointers")
        if "[[fallthrough]];" in line:
            report_error("Use 'FALLTHRU;' instead like the other parts of the code")
        if self.config.re["test_name_starting_lc"].search(line):


opa below should be removed?

botengyao · 2026-03-26T14:09:04Z

@@ -722,6 +722,8 @@ def check_source_line(self, line, file_path, report_error):
            report_error("Don't use 'using testing::Test;, elaborate the type instead")
        if line.startswith("using testing::TestWithParams;"):
            report_error("Don't use 'using testing::Test;, elaborate the type instead")
+        if re.match(r"^\s*using\s+\w+\s*=\s*[^;]*\*[^;]*;", line) and "(" not in line:


could you remind me why the check format is added here?

botengyao · 2026-03-26T14:20:08Z

+    if (!status_or_error.status().ok()) {
+      logError(std::string(status_or_error.status().message()));
+    }
+    fine_grain_log_levels_.push_back(std::make_pair(glob, status_or_error.value()));


prefer avoiding the std::make_pair temp construct, and it can be fine_grain_log_levels_.emplace_back(glob, level)

Retr0-XD · 2026-03-26T17:51:23Z

Will update the PR based on the comments and will share the changelog

botengyao · 2026-03-27T14:21:12Z

could you fix DCO please?

Retr0-XD · 2026-03-27T14:38:24Z

fixed

botengyao · 2026-03-27T22:52:10Z

please don't force push, since don't know what is the change since last review.

botengyao · 2026-03-27T22:53:46Z

looks like the comments are not addressed.

/wait

Adds a new CLI flag --fine-grain-log-levels that allows per-file log verbosity control when fine-grain logging is enabled. Accepts a comma-separated list of glob-pattern:log-level pairs. Requires --enable-fine-grain-logging to be set. Signed-off-by: Retr0-XD <sakthi.harish@edgeverve.com>

Retr0-XD · 2026-03-31T12:05:46Z

Apologies for force push , I'm facing restriction from my organization device. Please let me know once reviewed :)

botengyao

lgtm, thanks module the gemini comments.

/wait

botengyao · 2026-04-02T04:39:22Z

+   * @return const std::vector<std::pair<std::string, spdlog::level::level_enum>>& pair of
+   * glob-pattern,log-level for all configured fine-grain log overrides.


kind of leaning towards this AI comment ;-)

botengyao · 2026-04-02T04:42:26Z

+  std::vector<std::string> log_levels = absl::StrSplit(fine_grain_log_levels, ',');
+  for (auto& level : log_levels) {
+    std::vector<std::string> glob_level = absl::StrSplit(level, absl::MaxSplits(':', 1));
+    if (glob_level.size() != 2) {
+      logError(
+          fmt::format("error: fine-grain log level not correctly specified '{}'", level));
+    }
+    const std::string glob = glob_level[0];
+    auto status_or_error = parseAndValidateLogLevel(glob_level[1]);
+    if (!status_or_error.status().ok()) {
+      logError(std::string(status_or_error.status().message()));
+    }
+    fine_grain_log_levels_.push_back(std::make_pair(glob, status_or_error.value()));
+  }


I agree with AI.

Retr0-XD had a problem deploying to external-contributors March 21, 2026 10:16 — with GitHub Actions Error

repokitteh-read-only Bot added the api label Mar 21, 2026

repokitteh-read-only Bot assigned adisuissa Mar 21, 2026

repokitteh-read-only Bot added the waiting label Mar 21, 2026

Retr0-XD force-pushed the feat/fine-grain-log-cli-arg-41028 branch from 8ff12d4 to 20992b5 Compare March 22, 2026 06:08

repokitteh-read-only Bot removed the waiting label Mar 22, 2026

Retr0-XD had a problem deploying to external-contributors March 22, 2026 06:08 — with GitHub Actions Error

adisuissa reviewed Mar 23, 2026

View reviewed changes

Comment thread api/envoy/admin/v3/server_info.proto

repokitteh-read-only Bot removed the api label Mar 23, 2026

repokitteh-read-only Bot assigned botengyao Mar 23, 2026

gemini-code-assist Bot reviewed Mar 25, 2026

View reviewed changes

Retr0-XD had a problem deploying to external-contributors March 25, 2026 18:39 — with GitHub Actions Error

Retr0-XD force-pushed the feat/fine-grain-log-cli-arg-41028 branch from 0e1625c to 02f5844 Compare March 26, 2026 13:45

Retr0-XD had a problem deploying to external-contributors March 26, 2026 13:45 — with GitHub Actions Error

botengyao reviewed Mar 26, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Mar 26, 2026

Retr0-XD had a problem deploying to external-contributors March 26, 2026 17:56 — with GitHub Actions Error

repokitteh-read-only Bot removed the waiting label Mar 26, 2026

Retr0-XD force-pushed the feat/fine-grain-log-cli-arg-41028 branch from 5fb40c3 to 6c4dadf Compare March 27, 2026 14:36

Retr0-XD temporarily deployed to external-contributors March 27, 2026 14:36 — with GitHub Actions Inactive

repokitteh-read-only Bot added the waiting label Mar 27, 2026

Retr0-XD had a problem deploying to external-contributors March 30, 2026 06:38 — with GitHub Actions Error

repokitteh-read-only Bot removed the waiting label Mar 30, 2026

Retr0-XD had a problem deploying to external-contributors March 30, 2026 06:41 — with GitHub Actions Error

Retr0-XD force-pushed the feat/fine-grain-log-cli-arg-41028 branch from 44a8431 to 5f8518b Compare March 30, 2026 07:47

Retr0-XD had a problem deploying to external-contributors March 30, 2026 07:47 — with GitHub Actions Error

Retr0-XD had a problem deploying to external-contributors March 30, 2026 08:07 — with GitHub Actions Error

Retr0-XD had a problem deploying to external-contributors March 30, 2026 08:12 — with GitHub Actions Error

Retr0-XD force-pushed the feat/fine-grain-log-cli-arg-41028 branch from d4507d8 to cd4c5d5 Compare March 30, 2026 08:17

Retr0-XD temporarily deployed to external-contributors March 30, 2026 08:17 — with GitHub Actions Inactive

botengyao reviewed Apr 2, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Apr 2, 2026

		* @return const std::vector<std::pair<std::string, spdlog::level::level_enum>>& pair of
		* glob-pattern,log-level for all configured fine-grain log overrides.

Conversation

Retr0-XD commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Example usage

Changes

Risk

Low. The flag is completely opt-in — it is a no-op unless --enable-fine-grain-logging is also set, and it calls the same updateVerbositySetting API already used by the admin endpoint.

Uh oh!

repokitteh-read-only Bot commented Mar 21, 2026

Uh oh!

repokitteh-read-only Bot commented Mar 21, 2026

Uh oh!

agrawroh commented Mar 21, 2026

Uh oh!

Retr0-XD commented Mar 22, 2026

Uh oh!

adisuissa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adisuissa commented Mar 23, 2026

Uh oh!

Retr0-XD commented Mar 25, 2026

Uh oh!

botengyao commented Mar 25, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

botengyao Apr 2, 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!

gemini-code-assist Bot Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

botengyao Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

botengyao left a comment

Choose a reason for hiding this comment

Uh oh!

botengyao Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

botengyao Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

botengyao Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Retr0-XD commented Mar 26, 2026

Uh oh!

botengyao commented Mar 27, 2026

Uh oh!

Retr0-XD commented Mar 27, 2026

Uh oh!

botengyao commented Mar 27, 2026

Uh oh!

botengyao commented Mar 27, 2026

Uh oh!

Retr0-XD commented Mar 31, 2026

Uh oh!

botengyao left a comment

Choose a reason for hiding this comment

Uh oh!

botengyao Apr 2, 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!

botengyao Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Retr0-XD commented Mar 21, 2026 •

edited

Loading

Low. The flag is completely opt-in — it is a no-op unless `--enable-fine-grain-logging` is also set, and it calls the same `updateVerbositySetting` API already used by the admin endpoint.

botengyao Apr 2, 2026 •

edited

Loading

botengyao Apr 2, 2026 •

edited

Loading