Expand metric instrument name allowed characters to support Windows performance counter names

[cijothomas]

Description

Expands the metric instrument name allowed character set to include :, \, (, ), %, *, and space, and drops the requirement that the first character be alphabetic. This enables Windows performance counter style names (e.g. \Processor(_Total)\% Processor Time). Closes #4736 (:), #4371 (leading non-alphabetic characters), and (alongside the spec change) makes open-telemetry/opentelemetry-rust#2527's experimental feature flag obsolete. Backwards-compatible: all currently valid names remain valid.

Everything else stays as-is: ASCII-only, case-insensitive, maximum length 255 characters.

Motivation

Linked issues:

• #4736 — names containing :.
• #4371 — names starting with a non-alphabetic character.
• open-telemetry/opentelemetry-rust#2527 — Windows performance-counter names (e.g. \Processor(_Total)\% Processor Time). The current spec forces SDKs to either reject these names or ship workarounds; OTel Rust shipped an unofficial Cargo feature flag (experimental_metrics_disable_name_validation) to bypass validation entirely. With this PR, the spec accepts the full Windows perf-counter name shape so the workaround can be retired.

This PR addresses the specific characters that have been requested in open issues, rather than opening the door to arbitrary UTF-8. Per the SIG discussion on the earlier broader proposal (see comments in this PR), maintainers prefer expanding the allowlist over accepting any UTF-8.

Verifying impact on the OpenTelemetry Collector / OTTL

open-telemetry/opentelemetry-collector-contrib#48345 (merged) added unit tests confirming OTTL accepts arbitrary characters in metric.name — so this PR's allowlist expansion has no impact on OTTL.

[reyang]

Even many language runtimes do not have good support for supplementary planes, does this mean the SDKs targeting these runtimes are not compliant with the spec?

[dashpole]

was originally chosen for Prometheus compatibility

This doesn't seem correct to me. The character set we chose for our SDKs wasn't compatible with Prometheus. OTel has always allow UTF-8 at the protocol level, which is why Prometheus expanded to UTF-8. Prometheus didn't particularly want to expand their character set, and still strongly recommends using the simpler character set.

I would rather we expand the character set to include characters as needed. But I would probably not want to have whitespace in names from SDKs.

[cijothomas]

Even many language runtimes do not have good support for supplementary planes, does this mean the SDKs targeting these runtimes are not compliant with the spec?

Good point. Adopted the same convention as the Instrument description field directly below in api.md (L233-237): MUST support BMP, MAY support additional Unicode Planes. This matches the precedent already established for the description field in the same section.

[cijothomas]

@dashpole

You were right and my memory was probably wrong — I couldn't find any such discussion (Prometheus-compat or otherwise) in the original PR (#1557).

On expanding incrementally: we've been doing this for years (#3422 added /, then : came separately in #4736, leading - in #4371, \ in open-telemetry/opentelemetry-rust#2527, space asks in the SIG, ...), and a new character keeps showing up. I'd push back on continuing one-by-one — better to align with what Prometheus already accepts (any UTF-8 with UTF-8 mode) and stop arbitrarily restricting. The PR keeps the conservative subset as guidance: it adds a normative requirement that API documentation point users at [A-Za-z][A-Za-z0-9_./-]{0,254} for maximum portability.

[cijothomas]

@dashpole @ywwg — you were right. Revalidated against current Prometheus (v3.11.3 with translation_strategy: NoTranslation): all leading special characters (-, ., :, \, emoji, even leading digit) are preserved byte-identically. The behavior I originally observed was specific to the older NoUTF8EscapingWithSuffixes strategy and is no longer the case. Removing the paragraph from compatibility/prometheus_and_openmetrics.md and dropping the claim from the PR description.

[reyang]

I don't think we want metrics names to be any/arbitrary UTF-8 strings. At least I have very strong opinion about control/invisible characters and spaces/separators.

[cijothomas]

Thanks @dashpole @reyang — taking the pivot. Reverted the broader UTF-8 / first-char relaxation. The PR is now scoped to exactly the specific characters that have come back in open issues (: for #4736, \ for the Rust Windows perf-counter ask) plus dropping the first-char-alphabetic restriction (#4371, also needed for \Processor(...)\... Windows names). Everything else is status quo: ASCII, case-insensitive, max 255 characters. No whitespace, control chars, or separators. Future requests for additional characters can come back as their own focused PRs.

[cijothomas]

@reyang following up on your "very strong opinion about ... spaces/separators" comment — would you elaborate specifically on space? Windows performance counter names rely heavily on space (e.g. \Processor(_Total)\% Processor Time, \Memory\Available Bytes), and that's the concrete use case driving open-telemetry/opentelemetry-rust#2527. The current PR adds space to the allowlist specifically to enable these names. Are there specific harms (display, parsing, escaping in some downstream format?) you want us to avoid, or is the concern more general?

I left \0–\x1F (ASCII control chars) and zero-width / invisible Unicode codepoints out of scope by sticking to ASCII-only.

[reyang]

@reyang following up on your "very strong opinion about ... spaces/separators" comment — would you elaborate specifically on space? Windows performance counter names rely heavily on space (e.g. \Processor(_Total)\% Processor Time, \Memory\Available Bytes), and that's the concrete use case driving open-telemetry/opentelemetry-rust#2527. The current PR adds space to the allowlist specifically to enable these names. Are there specific harms (display, parsing, escaping in some downstream format?) you want us to avoid, or is the concern more general?

I left \0–\x1F (ASCII control chars) and zero-width / invisible Unicode codepoints out of scope by sticking to ASCII-only.

I think at least we should be very clear that we don't want something like foobar or foobar .
To summarize, I don't have a problem if we have valid cases and want to relax the limit/restrictions, however, I don't want us to be in a jungle where we allow arbitrary strings.

[cijothomas]

@reyang following up on your "very strong opinion about ... spaces/separators" comment — would you elaborate specifically on space? Windows performance counter names rely heavily on space (e.g. \Processor(_Total)\% Processor Time, \Memory\Available Bytes), and that's the concrete use case driving open-telemetry/opentelemetry-rust#2527. The current PR adds space to the allowlist specifically to enable these names. Are there specific harms (display, parsing, escaping in some downstream format?) you want us to avoid, or is the concern more general?
I left \0–\x1F (ASCII control chars) and zero-width / invisible Unicode codepoints out of scope by sticking to ASCII-only.

I think at least we should be very clear that we don't want something like foobar or foobar . To summarize, I don't have a problem if we have valid cases and want to relax the limit/restrictions, however, I don't want us to be in a jungle where we allow arbitrary strings.

Got it. Yes I want to make sure Windows Perf Counters can be supported. It is a valid scenario. Give a thumbs up here if you agree, and then I'll rework the PR to adjust to it. (Yes agree with the idea of not opening the door without concrete scenario)

[cijothomas]

Moving to draft while waiting to see if we are okay to relax restrictions to support Windows Perf Counters.

[reyang]

LGTM.

[cijothomas]

Moving to draft while waiting to see if we are okay to relax restrictions to support Windows Perf Counters.

Updated and ready for review now. Based on feedback from David and Reiley, we are not relaxing to support full UTF, but just enough where there is concrete demand (via previous issues, in particular about Windows Perf Counter names)

Draft PRs in .NET and Rust implementing this proposed spec relaxation, to be un-drafted if this PR merges here:
open-telemetry/opentelemetry-rust#3517
open-telemetry/opentelemetry-dotnet#7297

[cijothomas]

cc @jsuereth @jack-berg @jmacd — would appreciate your eyes on this.

[dashpole]

@cijothomas can you help me understand the intended use-case here? Are we adding official instrumentation and defining semantic conventions with names including these characters? Are we bridging these metrics from other systems?

If we are bridging from other systems, the metric producer interface is probably the right way for these to be bridged, and has no naming restrictions. If we are planning to add these to semantic conventions, that doesn't seem like the right thing to do to me. I think there is a lot of value in keeping the character set of metric names used in instrumentation tighter, unless we have a very good reason to expand it.

We did expand the list in the past to support migrating from OpenCensus. That made sense to me since providing a migration path from OpenCensus was part of our founding charter. I'm not as convinced that this case meets the bar.

[cijothomas]

@cijothomas can you help me understand the intended use-case here? Are we adding official instrumentation and defining semantic conventions with names including these characters? Are we bridging these metrics from other systems?

If we are bridging from other systems, the metric producer interface is probably the right way for these to be bridged, and has no naming restrictions. If we are planning to add these to semantic conventions, that doesn't seem like the right thing to do to me. I think there is a lot of value in keeping the character set of metric names used in instrumentation tighter, unless we have a very good reason to expand it.

We did expand the list in the past to support migrating from OpenCensus. That made sense to me since providing a migration path from OpenCensus was part of our founding charter. I'm not as convinced that this case meets the bar.

No plan of adding any instrumentation library, and not proposing any semantic-convention changes. Semantic conventions already have their own naming rules and (to my knowledge) none of them use any of
these special characters. I opened open-telemetry/semantic-conventions#3721 to make it more explicit!

The motivation is much narrower: we have users who want to migrate existing instrumentation to OTel, and the current OTel naming restriction is the only thing blocking them. Their existing names come from third-party
libraries, legacy systems, OS-level counters, etc. — names they can't easily change. They export to backends that already handle these names just fine — including the Microsoft backends my team works with, which is
what motivated the OTel .NET Geneva exporter workaround. (OTLP itself carries these names without any trouble; the protocol/wire format isn't part of the issue.) Similarly the OTel Rust
experimental_metrics_disable_name_validation feature flag was added for the same kind of user, and we'd love to be able to retire both of these hacks.

Is there a specific aspect of the proposal that you find concerning? I want to make sure I'm understanding the worry correctly so I can address it?
(Also, from what I can tell, Prometheus client also don't have this restrictions)

[dashpole]

Wearing my Googler hat, Google would not be able to support the proposed character set today (it supports [A-Za-z0-9_./-], although - is not documented). My understanding from the team is that it would be a substantial amount of work to expand that set. It would mean that customers could come to us with valid, OpenTelemetry instrumented applications that we couldn't support until that work was done (at least not without some friction).

Wearing my OTel hat again, I don't think experimental_metrics_disable_name_validation is a good idea. We probably shouldn't allow disabling behavior mandated by the specification with feature flags. Not a big deal, but I would like to avoid that becoming a standard practice.

They export to backends that already handle these names just fine

The goal is for metrics from OTel instrumentation is generally to be compatible with all backends.

When i've had similar naming discussions with internal teams at Google, my advice has been to migrate the instrumentation to use names that adhere to semantic convention guidelines, and use Views (which have no naming restrictions) to keep whatever existing names they need to use for backwards-compatibility.

[cijothomas]

use Views (which have no naming restrictions

Using View to bypass instrument name restrictions is a new learning for me. The spec is not very explicit about that. In OTel .NET and Rust implementations, the new metric name one provides via View is subject to the same restriction as the instrument name. But Go and Java do not do it that way. Seems like the spec should clarify this to avoid such a big drift between language implementations. Should we first clarify the spec's intended behavior?

I opened a PR to clarify spec: #5094

If that merges, then this PR can be closed.- we can fix .NET and Rust implementations, and then recommend users to bypass name restrictions by using views.