Skip to content

Commit 67f0516

Browse files
lmolkovalmolkova
authoredFeb 13, 2025··
Updating experimental -> development in docs (#1895)
·
v1.31.0
1 parent 152a9c3 commit 67f0516

8 files changed

+72
-77
lines changed
 

‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -227,7 +227,7 @@ Semantic conventions are validated for name formatting and backward compatibilit
227227
Here's [the full list of compatibility checks](./policies/compatibility.rego).
228228

229229
Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead.
230-
It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes.
230+
It applies to stable and unstable conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes.
231231

232232
You can run backward compatibility check (along with other policies) in all yaml files with the following command:
233233

‎docs/general/semantic-convention-groups.md

+14-14
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,13 @@ for the details.
3535

3636
## Group Stability
3737

38-
<!-- TODO: this section will need to change when https://github.com/open-telemetry/semantic-conventions/issues/1096 is implemented -->
38+
Semantic Convention groups can have the following [stability levels][MaturityLevel]:
39+
`development`, `alpha`, `beta`, `release_candidate`, and `stable`.
3940

40-
Semantic Convention groups can be `stable` (corresponds to
41-
[Stable maturity level][MaturityLevel]) or `experimental` (corresponds to [Development maturity level][MaturityLevel])
42-
if stability level is not specified, it's assumed to be `experimental`.
41+
Stability level is required on groups of all types except `attribute_group`.
42+
If stability level is not specified, it's assumed to be `development`.
4343

44-
Group stability MUST NOT change from `stable` to `experimental`.
44+
Group stability MUST NOT change from `stable` to any other level.
4545

4646
Semantic convention group of any stability level MUST NOT be removed
4747
to preserve code generation and documentation for legacy instrumentations.
@@ -60,31 +60,31 @@ Stability guarantees on a group apply to the group properties (such as type, id
6060
signal-specific properties) as well as overridden properties of stable attributes
6161
referenced by this group.
6262

63-
Stability guarantees on a group level **do not** apply to experimental attribute references.
63+
Stability guarantees on a group level **do not** apply to unstable attribute references.
6464

65-
**Experimental groups:**
65+
**Unstable groups:**
6666

67-
- MAY add or remove references to stable or experimental attributes
67+
- MAY add or remove references to stable or unstable attributes
6868
- MAY change requirement level and other properties of attribute references
6969

7070
**Stable groups:**
7171

72-
- MAY add or remove references to experimental attributes with `opt_in`
72+
- MAY add or remove references to unstable attributes with `opt_in`
7373
requirement level.
74-
- SHOULD NOT have references to experimental attributes with requirement level
74+
- SHOULD NOT have references to unstable attributes with requirement level
7575
other than `opt_in`.
76-
The requirement level of an experimental attribute reference
76+
The requirement level of an unstable attribute reference
7777
MAY be changed when this attribute becomes stable in cases allowed by the
7878
[Versioning and Stability][Stability].
7979
- MUST NOT remove references to stable attributes.
8080

81-
Stable instrumentations MUST NOT report telemetry following the experimental part
82-
of semantic conventions by default. They MAY support experimental part and allow
81+
Stable instrumentations MUST NOT report telemetry following the unstable part
82+
of semantic conventions by default. They MAY support unstable part and allow
8383
users to opt into it.
8484

8585
<!-- TODO: SchemaURL needs to contain some indication of stability level, e.g. as a suffix -->
8686
<!-- https://github.com/open-telemetry/semantic-conventions/issues/1511 -->
8787

8888
[Stability]: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability
89-
[MaturityLevel]: https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md
89+
[MaturityLevel]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.41.0/oteps/0232-maturity-of-otel.md
9090
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

‎docs/non-normative/code-generation.md

+5-6
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Language SIGs that ship semantic conventions library may decide to ship a stable
2828
Possible solutions include:
2929

3030
- Generate all Semantic Conventions for a given version in specific folder while keeping old versions intact. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern.
31-
- Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python puts experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change.
31+
- Follow language-specific conventions to annotate unstable parts. For example, Semantic Conventions in Python puts unstable attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change.
3232
- Ship two different artifacts: one that contains stable Semantic Conventions and another one with all available conventions. For example, [semantic-conventions in Java](https://github.com/open-telemetry/semantic-conventions-java) are shipped in two artifacts: `opentelemetry-semconv` and `opentelemetry-semconv-incubating`.
3333

3434
> Note:
@@ -37,16 +37,16 @@ Possible solutions include:
3737
> experimental conventions, the latter would be resolved leading to compilation or runtime issues in the application.
3838
3939
Instrumentation libraries should depend on the stable (part of) semantic convention artifact or copy relevant definitions into their own code base.
40-
Experimental semantic conventions are intended for end-user applications.
40+
Unstable semantic conventions artifact is intended for end-user applications.
4141

4242
### Deprecated Conventions
4343

4444
It's recommended to generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark them as deprecated.
45-
Conventions have a `stability` property which provide the stability level at the deprecation time (`experimental` or `stable`) and
45+
Conventions have a `stability` property which provide the stability level at the deprecation time (`development`, `alpha`, `beta`, `release_candidate` or `stable`) and
4646
the `deprecated` property that describes deprecation reason which can be used to generate documentation.
4747

4848
- Deprecated conventions that reached stability should not be removed without major version update according to SemVer.
49-
- Conventions that were deprecated while being experimental should still be generated and kept in the preview (part of) semantic conventions artifact. It minimizes runtime issues
49+
- Conventions that were deprecated while being unstable should still be generated and kept in the preview (part of) semantic conventions artifact. It minimizes runtime issues
5050
and breaking changes in user applications.
5151

5252
Keep stable convention definitions inside the preview (part of) semantic conversions artifact. It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside the preview artifact and point users to the stable location in generated documentation.
@@ -58,7 +58,7 @@ This section contains suggestions on how to structure semantic convention artifa
5858

5959
- Artifact name:
6060
- `opentelemetry-semconv` - stable conventions
61-
- `opentelemetry-semconv-incubating` - (if applicable) the preview artifact containing all (stable and experimental) conventions
61+
- `opentelemetry-semconv-incubating` - (if applicable) the preview artifact containing all (stable and unstable) conventions
6262
- Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating`
6363
- All supported Schema URLs should be listed to allow different instrumentations in the same application to provide the exact version of conventions they follow.
6464
- Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below:
@@ -181,7 +181,6 @@ Notable changes on helper methods:
181181
- `attr.brief | to_doc_brief | indent` -> `attr.brief | comment(indent=4)`, check out extensive [comment formatting configuration](https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md#comment-filter)
182182
- stability/deprecation checks:
183183
- `attribute is stable` if checking one attribute, `attributes | select("stable")` to filter stable attributes
184-
- `attribute is experimental` if checking one attribute, `attributes | select("experimental")` to filter experimental attributes
185184
- `attribute is deprecated` if checking one attribute, `attributes | select("deprecated")` to filter deprecated attributes
186185
- check if attribute is a template: `attribute.type is template_type`
187186
- new way to simplify switch-like logic: `key | map_text("map_name")`. Maps can be defined in the weaver config.

‎docs/non-normative/db-migration.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ See [Metric `db.client.operation.duration` v1.28.0 (RC)](https://github.com/open
9494

9595
### Experimental connection metrics
9696

97-
Database connection metrics are still experimental, but there have been several changes in the latest release.
97+
Database connection metrics are not stable yet, but there have been several changes in the latest release.
9898

9999
#### Database client connection count
100100

‎docs/runtime/jvm-metrics.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -433,7 +433,7 @@ Note that the JVM does not provide a definition of what "recent" means.
433433

434434
**Status**: [Development][DocumentStatus]
435435

436-
**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `jvm.`
436+
**Description:** In-development Java Virtual Machine (JVM) metrics captured under `jvm.`
437437

438438
### Metric: `jvm.memory.init`
439439

‎docs/runtime/nodejs-metrics.md

+19-24
Original file line numberDiff line numberDiff line change
@@ -10,30 +10,25 @@ This document describes semantic conventions for Node.js Runtime metrics in Open
1010

1111
<!-- toc -->
1212

13-
- [Development](#development)
14-
- [Metric: `nodejs.eventloop.delay.min`](#metric-nodejseventloopdelaymin)
15-
- [Metric: `nodejs.eventloop.delay.max`](#metric-nodejseventloopdelaymax)
16-
- [Metric: `nodejs.eventloop.delay.mean`](#metric-nodejseventloopdelaymean)
17-
- [Metric: `nodejs.eventloop.delay.stddev`](#metric-nodejseventloopdelaystddev)
18-
- [Metric: `nodejs.eventloop.delay.p50`](#metric-nodejseventloopdelayp50)
19-
- [Metric: `nodejs.eventloop.delay.p90`](#metric-nodejseventloopdelayp90)
20-
- [Metric: `nodejs.eventloop.delay.p99`](#metric-nodejseventloopdelayp99)
21-
- [Metric: `nodejs.eventloop.utilization`](#metric-nodejseventlooputilization)
22-
- [Metric: `nodejs.eventloop.time`](#metric-nodejseventlooptime)
13+
- [Metric: `nodejs.eventloop.delay.min`](#metric-nodejseventloopdelaymin)
14+
- [Metric: `nodejs.eventloop.delay.max`](#metric-nodejseventloopdelaymax)
15+
- [Metric: `nodejs.eventloop.delay.mean`](#metric-nodejseventloopdelaymean)
16+
- [Metric: `nodejs.eventloop.delay.stddev`](#metric-nodejseventloopdelaystddev)
17+
- [Metric: `nodejs.eventloop.delay.p50`](#metric-nodejseventloopdelayp50)
18+
- [Metric: `nodejs.eventloop.delay.p90`](#metric-nodejseventloopdelayp90)
19+
- [Metric: `nodejs.eventloop.delay.p99`](#metric-nodejseventloopdelayp99)
20+
- [Metric: `nodejs.eventloop.utilization`](#metric-nodejseventlooputilization)
21+
- [Metric: `nodejs.eventloop.time`](#metric-nodejseventlooptime)
2322

2423
<!-- tocstop -->
2524

26-
## Development
27-
28-
**Status**: [Development][DocumentStatus]
29-
30-
**Description:** Experimental Node.js Runtime metrics captured under `nodejs`.
25+
**Description:** In-development Node.js Runtime metrics captured under `nodejs`.
3126

3227
Note: The metrics for eventloop delay are split into separated values instead of a single histogram, because node runtime
3328
only returns single values through [`perf_hooks.monitorEventLoopDelay([options])`][Eventloop] and not the entire
3429
histogram, so it's not possible to convert it to an OpenTelemetry histogram.
3530

36-
### Metric: `nodejs.eventloop.delay.min`
31+
## Metric: `nodejs.eventloop.delay.min`
3732

3833
This metric is [recommended][MetricRecommended].
3934

@@ -55,7 +50,7 @@ This metric is [recommended][MetricRecommended].
5550
<!-- END AUTOGENERATED TEXT -->
5651
<!-- endsemconv -->
5752

58-
### Metric: `nodejs.eventloop.delay.max`
53+
## Metric: `nodejs.eventloop.delay.max`
5954

6055
This metric is [recommended][MetricRecommended].
6156

@@ -77,7 +72,7 @@ This metric is [recommended][MetricRecommended].
7772
<!-- END AUTOGENERATED TEXT -->
7873
<!-- endsemconv -->
7974

80-
### Metric: `nodejs.eventloop.delay.mean`
75+
## Metric: `nodejs.eventloop.delay.mean`
8176

8277
This metric is [recommended][MetricRecommended].
8378

@@ -99,7 +94,7 @@ This metric is [recommended][MetricRecommended].
9994
<!-- END AUTOGENERATED TEXT -->
10095
<!-- endsemconv -->
10196

102-
### Metric: `nodejs.eventloop.delay.stddev`
97+
## Metric: `nodejs.eventloop.delay.stddev`
10398

10499
This metric is [recommended][MetricRecommended].
105100

@@ -121,7 +116,7 @@ This metric is [recommended][MetricRecommended].
121116
<!-- END AUTOGENERATED TEXT -->
122117
<!-- endsemconv -->
123118

124-
### Metric: `nodejs.eventloop.delay.p50`
119+
## Metric: `nodejs.eventloop.delay.p50`
125120

126121
This metric is [recommended][MetricRecommended].
127122

@@ -143,7 +138,7 @@ This metric is [recommended][MetricRecommended].
143138
<!-- END AUTOGENERATED TEXT -->
144139
<!-- endsemconv -->
145140

146-
### Metric: `nodejs.eventloop.delay.p90`
141+
## Metric: `nodejs.eventloop.delay.p90`
147142

148143
This metric is [recommended][MetricRecommended].
149144

@@ -165,7 +160,7 @@ This metric is [recommended][MetricRecommended].
165160
<!-- END AUTOGENERATED TEXT -->
166161
<!-- endsemconv -->
167162

168-
### Metric: `nodejs.eventloop.delay.p99`
163+
## Metric: `nodejs.eventloop.delay.p99`
169164

170165
This metric is [recommended][MetricRecommended].
171166

@@ -187,7 +182,7 @@ This metric is [recommended][MetricRecommended].
187182
<!-- END AUTOGENERATED TEXT -->
188183
<!-- endsemconv -->
189184

190-
### Metric: `nodejs.eventloop.utilization`
185+
## Metric: `nodejs.eventloop.utilization`
191186

192187
This metric is [recommended][MetricRecommended].
193188

@@ -209,7 +204,7 @@ This metric is [recommended][MetricRecommended].
209204
<!-- END AUTOGENERATED TEXT -->
210205
<!-- endsemconv -->
211206

212-
### Metric: `nodejs.eventloop.time`
207+
## Metric: `nodejs.eventloop.time`
213208

214209
This metric is [recommended][MetricRecommended].
215210

‎docs/runtime/v8js-metrics.md

+11-16
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,17 @@ This document describes semantic conventions for V8 JS Engine Runtime metrics in
1010

1111
<!-- toc -->
1212

13-
- [Development](#development)
14-
- [Metric: `v8js.gc.duration`](#metric-v8jsgcduration)
15-
- [Metric: `v8js.memory.heap.limit`](#metric-v8jsmemoryheaplimit)
16-
- [Metric: `v8js.memory.heap.used`](#metric-v8jsmemoryheapused)
17-
- [Metric: `v8js.heap.space.available_size`](#metric-v8jsheapspaceavailable_size)
18-
- [Metric: `v8js.heap.space.physical_size`](#metric-v8jsheapspacephysical_size)
13+
- [Metric: `v8js.gc.duration`](#metric-v8jsgcduration)
14+
- [Metric: `v8js.memory.heap.limit`](#metric-v8jsmemoryheaplimit)
15+
- [Metric: `v8js.memory.heap.used`](#metric-v8jsmemoryheapused)
16+
- [Metric: `v8js.heap.space.available_size`](#metric-v8jsheapspaceavailable_size)
17+
- [Metric: `v8js.heap.space.physical_size`](#metric-v8jsheapspacephysical_size)
1918

2019
<!-- tocstop -->
2120

22-
## Development
21+
**Description:** In-development V8 JS Engine Runtime metrics captured under `v8js`.
2322

24-
**Status**: [Development][DocumentStatus]
25-
26-
**Description:** Experimental V8 JS Engine Runtime metrics captured under `v8js`.
27-
28-
### Metric: `v8js.gc.duration`
23+
## Metric: `v8js.gc.duration`
2924

3025
This metric is [recommended][MetricRecommended].
3126

@@ -66,7 +61,7 @@ of `[ 0.01, 0.1, 1, 10 ]`.
6661
<!-- END AUTOGENERATED TEXT -->
6762
<!-- endsemconv -->
6863

69-
### Metric: `v8js.memory.heap.limit`
64+
## Metric: `v8js.memory.heap.limit`
7065

7166
This metric is [recommended][MetricRecommended].
7267

@@ -106,7 +101,7 @@ This metric is [recommended][MetricRecommended].
106101
<!-- END AUTOGENERATED TEXT -->
107102
<!-- endsemconv -->
108103

109-
### Metric: `v8js.memory.heap.used`
104+
## Metric: `v8js.memory.heap.used`
110105

111106
This metric is [recommended][MetricRecommended].
112107

@@ -146,7 +141,7 @@ This metric is [recommended][MetricRecommended].
146141
<!-- END AUTOGENERATED TEXT -->
147142
<!-- endsemconv -->
148143

149-
### Metric: `v8js.heap.space.available_size`
144+
## Metric: `v8js.heap.space.available_size`
150145

151146
This metric is [recommended][MetricRecommended].
152147

@@ -186,7 +181,7 @@ This metric is [recommended][MetricRecommended].
186181
<!-- END AUTOGENERATED TEXT -->
187182
<!-- endsemconv -->
188183

189-
### Metric: `v8js.heap.space.physical_size`
184+
## Metric: `v8js.heap.space.physical_size`
190185

191186
This metric is [recommended][MetricRecommended].
192187

‎policies_test/group_stability_test.rego

+20-14
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,29 @@ package after_resolution
22
import future.keywords
33

44
test_fails_on_experimental_not_opt_in_attribute_in_stable_group if {
5-
count(deny) == 1 with input as {"groups": [{ "id": "span.foo",
5+
experimental_stabilities := ["experimental", "development", "alpha", "beta", "release_candidate"]
6+
every stability in experimental_stabilities {
7+
count(deny) == 1 with input as {"groups": [{ "id": "span.foo",
8+
"type": "span",
9+
"stability": "stable",
10+
"attributes": [{
11+
"name": "test.experimental",
12+
"stability": stability,
13+
"requirement_level": "required"
14+
}]}]}
15+
}
16+
}
17+
18+
test_passes_on_experimental_opt_in_attribute_in_stable_group if {
19+
experimental_stabilities := ["experimental", "development", "alpha", "beta", "release_candidate"]
20+
every stability in experimental_stabilities {
21+
count(deny) == 0 with input as {"groups": [{ "id": "span.foo",
622
"type": "span",
723
"stability": "stable",
824
"attributes": [{
925
"name": "test.experimental",
10-
"stability": "experimental",
11-
"requirement_level": "required"
26+
"stability": stability,
27+
"requirement_level": "opt_in"
1228
}]}]}
13-
}
14-
15-
test_passes_on_experimental_opt_in_attribute_in_stable_group if {
16-
count(deny) == 0 with input as {"groups": [{ "id": "span.foo",
17-
"type": "span",
18-
"stability": "stable",
19-
"attributes": [{
20-
"name": "test.experimental",
21-
"stability": "experimental",
22-
"requirement_level": "opt_in"
23-
}]}]}
29+
}
2430
}

0 commit comments

Comments
 (0)
Please sign in to comment.