Skip to content

Commit 705db94

Browse files
trasktrask
authored
Update RPC stability warning (#2805)
1 parent e5aad75 commit 705db94

File tree

4 files changed

+79
-34
lines changed

4 files changed

+79
-34
lines changed

‎.chloggen/2805.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Use this changelog template to create an entry for release notes.
2+
#
3+
# If your change doesn't affect end users you should instead start
4+
# your pull request title with [chore] or use the "Skip Changelog" label.
5+
6+
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
7+
change_type: enhancement
8+
9+
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
10+
component: rpc
11+
12+
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
13+
note: Update the RPC stability warning and guidance for instrumentation authors
14+
15+
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
16+
# The values here must be integers.
17+
issues: [2718]
18+
19+
# (Optional) One or more lines of additional information to render under the primary note.
20+
# These lines will be padded with 2 spaces and then inserted directly into the document.
21+
# Use pipe (|) for multiline entries.
22+
subtext:

‎docs/rpc/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,31 @@ linkTitle: RPC
99
This document defines semantic conventions for remote procedure calls (RPC)
1010
, also called "remote method invocations" (RMI).
1111

12+
> **Warning**
13+
> Existing RPC instrumentations that are using
14+
> [v1.37.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/README.md)
15+
> (or prior):
16+
>
17+
> * SHOULD NOT change the version of the RPC conventions that they emit by
18+
> default in their existing major version. Conventions include (but are not
19+
> limited to) attributes, metric and span names, and unit of measure.
20+
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
21+
> in their existing major version as a comma-separated list of category-specific values
22+
> (e.g., http, databases, rpc). The list of values includes:
23+
> * `rpc` - emit the stable RPC conventions, and stop emitting
24+
> the experimental RPC conventions that the instrumentation emitted
25+
> previously.
26+
> * `rpc/dup` - emit both the experimental and stable RPC conventions,
27+
> allowing for a phased rollout of the stable semantic conventions.
28+
> * The default behavior (in the absence of one of these values) is to continue
29+
> emitting whatever version of the old experimental RPC conventions
30+
> the instrumentation was emitting previously.
31+
> * Note: `rpc/dup` has higher precedence than `rpc` in case both values are present
32+
> * SHOULD maintain (security patching at a minimum) their existing major version
33+
> for at least six months after it starts emitting both sets of conventions.
34+
> * MAY drop the environment variable in their next major version and emit only
35+
> the stable RPC conventions.
36+
1237
Semantic conventions for RPC are defined for the following signals:
1338

1439
* [RPC Spans](rpc-spans.md): Semantic Conventions for RPC client and server *spans*.

‎docs/rpc/rpc-metrics.md‎

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -33,29 +33,28 @@ metrics can be filtered for finer grain analysis.
3333

3434
> **Warning**
3535
> Existing RPC instrumentations that are using
36-
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md)
36+
> [v1.37.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-metrics.md)
3737
> (or prior):
3838
>
39-
> * SHOULD NOT change the version of the networking conventions that they emit by default
40-
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
41-
> include stabilization of a core set of networking conventions which are also used
42-
> in RPC instrumentations). Conventions include, but are not limited to, attributes,
43-
> metric and span names, and unit of measure.
39+
> * SHOULD NOT change the version of the RPC conventions that they emit by
40+
> default in their existing major version. Conventions include (but are not
41+
> limited to) attributes, metric and span names, and unit of measure.
4442
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
45-
> in the existing major version as a comma-separated list of category-specific values
46-
> (e.g., http, databases, messaging). The list of values includes:
47-
> * `http` - emit the new, stable networking conventions,
48-
> and stop emitting the old experimental networking conventions
49-
> that the instrumentation emitted previously.
50-
> * `http/dup` - emit both the old and the stable networking conventions,
51-
> allowing for a seamless transition.
43+
> in their existing major version as a comma-separated list of category-specific values
44+
> (e.g., http, databases, rpc). The list of values includes:
45+
> * `rpc` - emit the stable RPC conventions, and stop emitting
46+
> the experimental RPC conventions that the instrumentation emitted
47+
> previously.
48+
> * `rpc/dup` - emit both the experimental and stable RPC conventions,
49+
> allowing for a phased rollout of the stable semantic conventions.
5250
> * The default behavior (in the absence of one of these values) is to continue
53-
> emitting whatever version of the old experimental networking conventions
51+
> emitting whatever version of the old experimental RPC conventions
5452
> the instrumentation was emitting previously.
55-
> * Note: `http/dup` has higher precedence than `http` in case both values are present
56-
> * SHOULD maintain (security patching at a minimum) the existing major version
53+
> * Note: `rpc/dup` has higher precedence than `rpc` in case both values are present
54+
> * SHOULD maintain (security patching at a minimum) their existing major version
5755
> for at least six months after it starts emitting both sets of conventions.
58-
> * SHOULD drop the environment variable in the next major version.
56+
> * MAY drop the environment variable in their next major version and emit only
57+
> the stable RPC conventions.
5958
6059
## Metric instruments
6160

‎docs/rpc/rpc-spans.md‎

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -25,29 +25,28 @@ This document defines how to describe remote procedure calls
2525

2626
> **Warning**
2727
> Existing RPC instrumentations that are using
28-
> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md)
28+
> [v1.37.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-spans.md)
2929
> (or prior):
3030
>
31-
> * SHOULD NOT change the version of the networking conventions that they emit by default
32-
> until the HTTP semantic conventions are marked stable (HTTP stabilization will
33-
> include stabilization of a core set of networking conventions which are also used
34-
> in RPC instrumentations). Conventions include, but are not limited to, attributes,
35-
> metric and span names, and unit of measure.
31+
> * SHOULD NOT change the version of the RPC conventions that they emit by
32+
> default in their existing major version. Conventions include (but are not
33+
> limited to) attributes, metric and span names, and unit of measure.
3634
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
37-
> in the existing major version as a comma-separated list of category-specific values
38-
> (e.g., http, databases, messaging). The list of values includes:
39-
> * `http` - emit the new, stable networking conventions,
40-
> and stop emitting the old experimental networking conventions
41-
> that the instrumentation emitted previously.
42-
> * `http/dup` - emit both the old and the stable networking conventions,
43-
> allowing for a seamless transition.
35+
> in their existing major version as a comma-separated list of category-specific values
36+
> (e.g., http, databases, rpc). The list of values includes:
37+
> * `rpc` - emit the stable RPC conventions, and stop emitting
38+
> the experimental RPC conventions that the instrumentation emitted
39+
> previously.
40+
> * `rpc/dup` - emit both the experimental and stable RPC conventions,
41+
> allowing for a phased rollout of the stable semantic conventions.
4442
> * The default behavior (in the absence of one of these values) is to continue
45-
> emitting whatever version of the old experimental networking conventions
43+
> emitting whatever version of the old experimental RPC conventions
4644
> the instrumentation was emitting previously.
47-
> * Note: `http/dup` has higher precedence than `http` in case both values are present
48-
> * SHOULD maintain (security patching at a minimum) the existing major version
45+
> * Note: `rpc/dup` has higher precedence than `rpc` in case both values are present
46+
> * SHOULD maintain (security patching at a minimum) their existing major version
4947
> for at least six months after it starts emitting both sets of conventions.
50-
> * SHOULD drop the environment variable in the next major version.
48+
> * MAY drop the environment variable in their next major version and emit only
49+
> the stable RPC conventions.
5150
5251
## Common remote procedure call conventions
5352

0 commit comments

Comments
 (0)