stats: new element scope based API

[wbpcode]

Commit Message: stats: new element scope based API
Additional Description:

This PR added new element based API which all developer to specific the tag of stats in-orderly. With the PR, we can avoid the current tag/label extraction system under the premise of keep the compatibility to default stats.

This new API also have great performance improvement for stats creation by avoid stats labels/tags extraction. Here is the benchmark result for cluster stats creation:

BM_CreateClusterStatsWithTlsLegacyScope/0         162172 ns       162153 ns         4368 items_per_second=6.167k/s
BM_CreateClusterStatsWithTlsLegacyScope/100       160762 ns       160737 ns         4451 items_per_second=6.22136k/s
BM_CreateClusterStatsWithTlsLegacyScope/1000      163782 ns       163760 ns         4405 items_per_second=6.1065k/s
BM_CreateClusterStatsWithTlsElementScope/0         65222 ns        65172 ns        13126 items_per_second=15.344k/s
BM_CreateClusterStatsWithTlsElementScope/100       63036 ns        63029 ns        12809 items_per_second=15.8658k/s
BM_CreateClusterStatsWithTlsElementScope/1000      63687 ns        63681 ns        11965 items_per_second=15.7033k/s

The new API is guarded by a command line option. We will have more PRs to migrate the existing API usage to new API gradually. The best time to grow up a tree is ten years ago, the second best time is now. :)

NOTE: This PR only provided new API implementation and an option to enable new API. We still need to do lots of jobs to make sure the new API works perfectly for all existing metrics.

Risk Level: low. won't affect any existing logic if the command line option is not enabled.
Testing: unit.
Docs Changes: n/a.
Release Notes: n/a.
Platform Specific Features: n/a.

[repokitteh-read-only]

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

🐱

Caused by: #45146 was opened by wbpcode.

see: more, trace.

[wbpcode]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces an element-based stats scope and store implementation, gated by a new --enable-stats-element-scope command-line flag. The changes include new data structures like StatElement and StatElementView, as well as extensions to the Scope and Store interfaces to support structured stat creation. Feedback highlights a logic error in the legacy prefix parsing where tag values could incorrectly include multiple dot-separated tokens and identifies a style violation regarding trailing underscores on public data members in the StatElementBase template.

[Copilot]

Pull request overview

This PR introduces an opt-in element-based stats scope/store API intended to reduce stat creation overhead while preserving legacy behavior when disabled.

Changes:

• Adds --enable-stats-element-scope plumbing through server options, admin command-line proto output, and store construction.
• Adds StatElement APIs to stats Scope/Store interfaces with implementations for isolated and thread-local stores.
• Adds tests and benchmarks for element-based scope stat creation.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
api/envoy/admin/v3/server_info.proto	Exposes the new CLI option in admin command-line options.
envoy/server/options.h	Adds the server option accessor.
envoy/stats/BUILD	Adds dependencies for new stats tag types.
envoy/stats/scope.h	Adds element-based scope/stat creation APIs.
envoy/stats/store.h	Adds element-scope capability reporting and store helper.
envoy/stats/tag.h	Defines structured stat element types.
source/common/stats/BUILD	Adds dependencies for tag utility changes.
source/common/stats/isolated_store_impl.cc	Implements element scopes for isolated stores.
source/common/stats/isolated_store_impl.h	Declares element-scope isolated store support.
source/common/stats/tag_utility.cc	Adds element join/tag helper logic.
source/common/stats/tag_utility.h	Declares element tag utility APIs.
source/common/stats/thread_local_store.cc	Implements element scopes for thread-local stores.
source/common/stats/thread_local_store.h	Declares thread-local element-scope support.
source/exe/stripped_main_base.cc	Passes the option into the production stats store.
source/server/config_validation/server.cc	Uses the option during validation stats store setup.
source/server/options_impl.cc	Parses and serializes the new CLI option.
source/server/options_impl_base.h	Stores and exposes the new option.
test/common/stats/BUILD	Updates deps for stats tests/benchmark.
test/common/stats/isolated_store_impl_test.cc	Adds isolated-store element-scope coverage.
test/common/stats/thread_local_store_speed_test.cc	Adds cluster stat creation benchmarks.
test/common/stats/thread_local_store_test.cc	Adds thread-local element-scope coverage.
test/integration/server.h	Forwards element-scope APIs through test wrappers.
test/mocks/server/options.cc	Adds mock default for the new option.
test/mocks/server/options.h	Adds mocked accessor.
test/mocks/stats/mocks.h	Adds element API overrides to mock scope.
test/server/options_impl_test.cc	Tests parsing, defaults, and proto conversion.

Comments suppressed due to low confidence (2)

source/common/stats/isolated_store_impl.cc:191

• This legacy gaugeFromStatNameWithTags override also bypasses tag extraction when tags are not provided, contrary to the Scope API contract for the legacy methods. Please keep absent-tag calls on the legacy extraction path so existing isolated-store users do not observe different tag sets when element scopes are enabled.

Gauge& ElementScopeImpl::gaugeFromStatNameWithTags(const StatName& name,
                                                   StatNameTagVectorOptConstRef tags,
                                                   Gauge::ImportMode import_mode) {
  StatElementVec elements;
  elements.emplace_back(StatElement{.value_ = name});

source/common/stats/thread_local_store.cc:969

• Like the counter path, this legacy gaugeFromStatNameWithTags override treats absent tags as an empty tag list and never runs the configured tag extractor, which changes the documented behavior of the legacy API under element scopes. Please preserve extraction for absl::nullopt tags or make the contract explicit before routing existing callers through this implementation.

Gauge& ThreadLocalStoreImpl::ElementScopeImpl::gaugeFromStatNameWithTags(
    const StatName& name, StatNameTagVectorOptConstRef tags, Gauge::ImportMode import_mode) {
  StatElementVec elements;
  elements.emplace_back(StatElement{.value_ = name});
  TagUtility::mergeTagsToElements(elements, tags);

[wbpcode]

/coverage

[repokitteh-read-only]

Coverage for this Pull Request will be rendered here:

https://storage.googleapis.com/envoy-cncf-pr/45146/coverage/index.html

For comparison, current coverage on main branch is here:

https://storage.googleapis.com/envoy-cncf-postsubmit/main/coverage/index.html

The coverage results are (re-)rendered each time the CI Envoy/Checks (coverage) job completes.

🐱

Caused by: a #45146 (comment) was created by @wbpcode.

see: more, trace.

[kyessenov]

This feels to me like a runtime flag setting since the intent would probably be turn it on long term.

[wbpcode]

I guess restart runtime flag is also fine, but not sure whether the runtime is ready or not when we creating the thread local store. I will take a check to that.

[wbpcode]

We need to detect the flag when our first scope is created to ensure the old API and new API be separated strictly. But the runtime system self will depends on stats, so it's hard to use a runtime flag to control it.
🤔