otel: create migration mechanism to semantic convention attribute names

[fcfort]

Commit Message: otel: create migration mechanism to semantic convention attribute names

Additional Description:

This change implements the ability to bring Envoy’s OpenTelemetry tracer in alignment with the stable OpenTelemetry HTTP Semantic Conventions.

The architecture avoids adding additional string comparisons at core call sites by utilizing C++ overload resolution within the tracing driver APIs (setTag overload for typed Tracing::Tag).

Stability Opt-In Levels:

• UNKNOWN: Defaults to legacy tags only (backward-compatible default behavior).
• LEGACY: Emits only the legacy Envoy attributes.
• LEGACY_AND_SEMCONV: Emits BOTH stable OTel and legacy Envoy attributes simultaneously.
• SEMCONV: Emits only the stable OpenTelemetry HTTP/Network semantic convention attributes.

This was loosely inspired by the approach outlined in https://opentelemetry.io/docs/specs/semconv/http/ regarding OTEL_SEMCONV_STABILITY_OPT_IN.

Tag Migration Mapping:

The following table defines the exact mapping of span tags that will be migrated from the legacy Envoy naming conventions to the stable OpenTelemetry HTTP and Network semantic conventions under the respective opt-in levels:

Legacy Envoy Tag Name	Stable OpenTelemetry Semantic Convention Tag Name
http.method	http.request.method
http.status_code	http.response.status_code
http.url	url.full
peer.address	network.peer.address
request_size	http.request.body.size
response_size	http.response.body.size
retry.count	http.request.resend_count
user_agent	user_agent.original

Note: http.protocol is deliberately NOT migrated to url.scheme or any other semantic convention name because its semantics differ. It is unaffected by the opt-in levels and continues to emit only as http.protocol.

Risk Level: Low (Adds standardized stability opt-in tags, defaults to backward-compatible legacy behavior).

Testing:

• Enhanced opentelemetry_tracer_impl_test.cc with the new ExportOTLPSpanWithLegacyOptIn unit test to validate the LEGACY configuration behavior.
• Re-ran and verified existing OpenTelemetry tests (//test/extensions/tracers/opentelemetry:opentelemetry_test) and affected core tracing and routing tests (//test/common/http:async_client_impl_test and //test/common/router:router_test).

Docs Changes: None.
Release Notes: Added otel_semconv_stability_opt_in configuration to support stable HTTP semantic convention attribute names in the OpenTelemetry tracer.
Platform Specific Features: None.
Fixes #30821.

[Disclosed usage of generative AI: Yes, used to assist in code modifications.]

[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 @adisuissa
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #45184 was opened by fcfort.

see: more, trace.

[adisuissa]

Please add a short comment about each enum value (potentially with a link to the places in the OTEL spec they relate to).

[adisuissa]

These need to be in the enum description

[adisuissa]

One thing to consider:
if you think a specific config might be needed for each value (e.g., a specific config knob that is relevant to the semantic-conv option), then it may be better to use a message-type for of these entries instead.

[adisuissa]

Was choosing the enum over bool fields preferred over boolean fields intentional?
The reason for my question: LEGACY_AND_SEMCONV implies that both flags are set. If another new flag is added, then we'll end up with 4 more enum values: NEW, LEGACY_AND_NEW, SEMCONV_AND_NEW, and LEGACY_AND_SEMCONV_AND_NEW.
It may be better to have a different message-type here (which makes this opt-in), and then each of the legacy/semconv as a BoolValue type.