open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Transition plan for HTTP breaking changes where both old and new attributes can be sent for a while (#3443)

This commit is contained in:
Trask Stalnaker 2023-05-08 12:00:16 -07:00 committed by GitHub
parent 8f0a652071
commit 3f8cd16996
6 changed files with 144 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
specification/metrics/semantic_conventions/http-metrics.md
View File

@ -26,6 +26,30 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
<!-- tocstop -->
> **Warning**
> Existing HTTP instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md)
> (or prior):
>
> * SHOULD NOT change the version of the HTTP or networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in HTTP instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which supports the following values:
> * `none` - continue emitting whatever version of the old experimental
> HTTP and networking attributes the instrumentation was emitting previously.
> This is the default value.
> * `http` - emit the new, stable HTTP and networking attributes,
> and stop emitting the old experimental HTTP and networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable HTTP and networking attributes,
> allowing for a seamless transition.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
## HTTP Server
### Metric: `http.server.duration`

24
specification/metrics/semantic_conventions/rpc-metrics.md
View File

@ -28,6 +28,30 @@ metrics can be filtered for finer grain analysis.
<!-- tocstop -->
> **Warning**
> Existing RPC instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md)
> (or prior):
>
> * SHOULD NOT change the version of the networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in RPC instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which supports the following values:
> * `none` - continue emitting whatever version of the old experimental
> networking attributes the instrumentation was emitting previously.
> This is the default value.
> * `http` - emit the new, stable networking attributes,
> and stop emitting the old experimental networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable networking attributes,
> allowing for a seamless transition.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
## Metric instruments
The following metric instruments MUST be used to describe RPC operations. They

24
specification/trace/semantic_conventions/database.md
View File

@ -21,6 +21,30 @@
<!-- tocstop -->
> **Warning**
> Existing Database instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/database.md)
> (or prior):
>
> * SHOULD NOT change the version of the networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in Database instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which supports the following values:
> * `none` - continue emitting whatever version of the old experimental
> database attributes the instrumentation was emitting previously.
> This is the default value.
> * `http` - emit the new, stable networking attributes,
> and stop emitting the old experimental networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable networking attributes,
> allowing for a seamless transition.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
**Span kind:** MUST always be `CLIENT`.
The **span name** SHOULD be set to a low cardinality value representing the statement executed on the database.

24
specification/trace/semantic_conventions/http.md
View File

@ -27,6 +27,30 @@ and various HTTP versions like 1.1, 2 and SPDY.
<!-- tocstop -->
> **Warning**
> Existing HTTP instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)
> (or prior):
>
> * SHOULD NOT change the version of the HTTP or networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in HTTP instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which supports the following values:
> * `none` - continue emitting whatever version of the old experimental
> HTTP and networking attributes the instrumentation was emitting previously.
> This is the default value.
> * `http` - emit the new, stable HTTP and networking attributes,
> and stop emitting the old experimental HTTP and networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable HTTP and networking attributes,
> allowing for a seamless transition.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
## Name
HTTP spans MUST follow the overall [guidelines for span names](../api.md#span).

24
specification/trace/semantic_conventions/messaging.md
View File

@ -37,6 +37,30 @@
<!-- tocstop -->
> **Warning**
> Existing Messaging instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/messaging.md)
> (or prior):
>
> * SHOULD NOT change the version of the networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in Messaging instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which supports the following values:
> * `none` - continue emitting whatever version of the old experimental
> networking attributes the instrumentation was emitting previously.
> This is the default value.
> * `http` - emit the new, stable networking attributes,
> and stop emitting the old experimental networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable networking attributes,
> allowing for a seamless transition.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
## Definitions
### Message

24
specification/trace/semantic_conventions/rpc.md
View File

@ -29,6 +29,30 @@ This document defines how to describe remote procedure calls
<!-- tocstop -->
> **Warning**
> Existing RPC instrumentations that are using
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md)
> (or prior):
>
> * SHOULD NOT change the version of the networking attributes that they emit
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
> include stabilization of a core set of networking attributes which are also used
> in RPC instrumentations).
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in the existing major version which supports the following values:
> * `none` - continue emitting whatever version of the old experimental
> networking attributes the instrumentation was emitting previously.
> This is the default value.
> * `http` - emit the new, stable networking attributes,
> and stop emitting the old experimental networking attributes
> that the instrumentation emitted previously.
> * `http/dup` - emit both the old and the stable networking attributes,
> allowing for a seamless transition.
> * SHOULD maintain (security patching at a minimum) the existing major version
> for at least six months after it starts emitting both sets of attributes.
> * SHOULD drop the environment variable in the next major version (stable
> next major version SHOULD NOT be released prior to October 1, 2023).
## Common remote procedure call conventions
A remote procedure calls is described by two separate spans, one on the client-side and one on the server-side.