Skip to content

Commit 1c8ec3b

Browse files
trentmtrentm
authored
fix(semantic-conventions): Remove the subset of DB_SYSTEM_NAME_VALUE_* exports that are unstable from the @opentelemetry/semantic-conventions entry point. (#5690)
1 parent 85f1bcc commit 1c8ec3b

File tree

12 files changed

+394
-222
lines changed

12 files changed

+394
-222
lines changed

‎scripts/semconv/generate.sh

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ git fetch origin "${SPEC_VERSION}" --depth=1
2727
git reset --hard FETCH_HEAD
2828
cd ${SCRIPT_DIR}
2929

30+
# Generate "semantic-conventions/src/stable_*.ts".
3031
docker run --rm --platform linux/amd64 \
3132
-v ${SCRIPT_DIR}/semantic-conventions/model:/source \
3233
-v ${SCRIPT_DIR}/templates:/weaver/templates \
@@ -35,7 +36,19 @@ docker run --rm --platform linux/amd64 \
3536
registry generate \
3637
--registry=/source \
3738
--templates=/weaver/templates \
38-
stable \
39+
ts-stable \
40+
/output/
41+
42+
# Generate "semantic-conventions/src/experimental_*.ts".
43+
docker run --rm --platform linux/amd64 \
44+
-v ${SCRIPT_DIR}/semantic-conventions/model:/source \
45+
-v ${SCRIPT_DIR}/templates:/weaver/templates \
46+
-v ${ROOT_DIR}/semantic-conventions/src/:/output \
47+
otel/weaver:$GENERATOR_VERSION \
48+
registry generate \
49+
--registry=/source \
50+
--templates=/weaver/templates \
51+
ts-experimental \
3952
/output/
4053

4154
# Ensure semconv compiles

‎scripts/semconv/templates/registry/ts-experimental/attributes.ts.j2

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{%- import 'docstring.ts.j2' as d %}
2+
/*
3+
* Copyright The OpenTelemetry Authors
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* https://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
//----------------------------------------------------------------------------------------------------------
19+
// DO NOT EDIT, this is an Auto-generated file from scripts/semconv/templates/registry/stable/attributes.ts.j2
20+
//----------------------------------------------------------------------------------------------------------
21+
22+
{% for attribute in ctx.attributes | attribute_sort %}
23+
{% if attribute.name not in params.excluded_attributes %}
24+
{% if attribute is not stable %}
25+
{{d.docstring(attribute, "attribute")}}
26+
{% if attribute.type is not template_type %}
27+
export const ATTR_{{ attribute.name | screaming_snake_case }} = '{{attribute.name}}' as const;
28+
29+
{% else %}
30+
export const ATTR_{{ attribute.name | screaming_snake_case }} = (key: string) => `{{attribute.name}}.${key}`;
31+
32+
{% endif %}
33+
{% endif %}
34+
{% if attribute.type is mapping %}
35+
{% for espec in attribute.type.members | sort(attribute='value') %}
36+
{#- Grandfather NETWORK_TRANSPORT_VALUE_QUIC as stable until v1.34.0 is released. #}
37+
{% if espec is not stable and not (attribute.name == 'network.transport' and espec.value == 'quic') %}
38+
/**
39+
* Enum value {{ espec.value | print_member_value }} for attribute {@link ATTR_{{ attribute.name | screaming_snake_case }}}.
40+
*/
41+
export const {{ attribute.name | screaming_snake_case }}_VALUE_{{ espec.id | screaming_snake_case }} = {{ espec.value | print_member_value }} as const;
42+
43+
{% endif %}
44+
{% endfor %}
45+
{% endif %}
46+
{% endif %}
47+
{% endfor %}

‎scripts/semconv/templates/registry/stable/docstring.ts.j2 renamed to ‎scripts/semconv/templates/registry/ts-experimental/docstring.ts.j2

File renamed without changes.

‎scripts/semconv/templates/registry/stable/metrics.ts.j2 renamed to ‎scripts/semconv/templates/registry/ts-experimental/metrics.ts.j2

File renamed without changes.

‎scripts/semconv/templates/registry/stable/weaver.yaml renamed to ‎scripts/semconv/templates/registry/ts-experimental/weaver.yaml

Lines changed: 27 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,23 @@
1-
2-
params:
3-
excluded_attributes: ["messaging.client_id"]
4-
5-
# https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md#comment-filter
6-
comment_formats:
7-
jsdoc:
8-
format: markdown
9-
header: '/**'
10-
# Note: This results in trailing whitespace on empty lines. IMHO the
11-
# 'comment' filter should handle those.
12-
prefix: ' * '
13-
footer: ' */'
14-
trim: true
15-
indent_first_level_list_items: true
16-
escape_backslashes: true
17-
default_comment_format: jsdoc
1+
# ts-experimental/... generates the "semantic-conventions/src/experimental_*.ts"
2+
# files.
183

194
# Notes:
205
# - Use `""` and `null` with `exclude_stability` to skip attributes/metrics that
216
# accidentally do not have a stability set
227
# (e.g. https://github.com/open-telemetry/semantic-conventions/issues/1777).
238
templates:
24-
- pattern: attributes.ts.j2
25-
file_name: "stable_attributes.ts"
26-
filter: >
27-
semconv_attributes({
28-
"stable_only": true
29-
}) | {
30-
attributes: .
31-
}
32-
application_mode: single
339
- pattern: attributes.ts.j2
3410
file_name: "experimental_attributes.ts"
11+
# This "exclude_stability" does *not* exclude "stable" because it needs
12+
# to process *stable* enums that might have *unstable* members. (e.g.,
13+
# `db.system.name` is stable, but some of its enum values are not.)
3514
filter: >
3615
semconv_attributes({
37-
"exclude_stability": ["stable", "", null]
16+
"exclude_stability": ["", null]
3817
}) | {
3918
attributes: .
4019
}
4120
application_mode: single
42-
- pattern: metrics.ts.j2
43-
file_name: "stable_metrics.ts"
44-
filter: >
45-
semconv_metrics({
46-
"stable_only": true
47-
}) | {
48-
metrics: .
49-
}
50-
application_mode: single
5121
- pattern: metrics.ts.j2
5222
file_name: "experimental_metrics.ts"
5323
filter: >
@@ -58,6 +28,27 @@ templates:
5828
}
5929
application_mode: single
6030

31+
params:
32+
excluded_attributes: ["messaging.client_id"]
33+
34+
##
35+
# Everything below here is expected to be the same as in "../ts-*/weaver.yaml".
36+
##
37+
38+
# https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md#comment-filter
39+
comment_formats:
40+
jsdoc:
41+
format: markdown
42+
header: '/**'
43+
# Note: This results in trailing whitespace on empty lines. IMHO the
44+
# 'comment' filter should handle those.
45+
prefix: ' * '
46+
footer: ' */'
47+
trim: true
48+
indent_first_level_list_items: true
49+
escape_backslashes: true
50+
default_comment_format: jsdoc
51+
6152
# Whitespace control settings to simplify the definition of templates
6253
whitespace_control:
6354
trim_blocks: true

‎scripts/semconv/templates/registry/stable/attributes.ts.j2 renamed to ‎scripts/semconv/templates/registry/ts-stable/attributes.ts.j2

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,14 @@ export const ATTR_{{ attribute.name | screaming_snake_case }} = (key: string) =>
3131
{% endif %}
3232
{% if attribute.type is mapping %}
3333
{% for espec in attribute.type.members | sort(attribute='value') %}
34+
{#- Grandfather NETWORK_TRANSPORT_VALUE_QUIC as stable until v1.34.0 is released. #}
35+
{% if espec is stable or (attribute.name == 'network.transport' and espec.value == 'quic') %}
3436
/**
3537
* Enum value {{ espec.value | print_member_value }} for attribute {@link ATTR_{{ attribute.name | screaming_snake_case }}}.
3638
*/
3739
export const {{ attribute.name | screaming_snake_case }}_VALUE_{{ espec.id | screaming_snake_case }} = {{ espec.value | print_member_value }} as const;
3840

41+
{% endif %}
3942
{% endfor %}
4043
{% endif %}
4144
{% endif %}

‎scripts/semconv/templates/registry/ts-stable/docstring.ts.j2

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{% macro strong_rfc2119(string) -%}{{ string | regex_replace("\\b(MUST NOT|MUST|REQUIRED|SHALL NOT|SHALL|SHOULD NOT|SHOULD|RECOMMENDED|MAY|OPTIONAL)\\b", "**$1**") }}{% endmacro -%}
2+
3+
{% macro docstring(obj, type="value") -%}
4+
{%- set examples_jsdoc %}
5+
{% if obj.examples is sequence %}
6+
{% for example in obj.examples %}
7+
@example {{ example }}
8+
{% endfor %}
9+
{% elif obj.examples %}
10+
@example {{ obj.examples | print_member_value }}
11+
{% endif %}
12+
{% endset -%}
13+
14+
{%- if obj.note %}
15+
{% set note_jsdoc = "@note " ~ strong_rfc2119(obj.note) %}
16+
{% endif -%}
17+
18+
{%- if obj.stability != "stable" %}
19+
{% set stability_jsdoc = "@experimental This " ~ type ~ " is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`." %}
20+
{% endif -%}
21+
22+
{%- if obj is deprecated %}
23+
{%- set deprecated_jsdoc = "\n@deprecated " ~ strong_rfc2119(obj.deprecated.note) -%}
24+
{%- endif -%}
25+
26+
{{ [
27+
strong_rfc2119(obj.brief) | trim,
28+
"\n",
29+
examples_jsdoc,
30+
note_jsdoc,
31+
stability_jsdoc,
32+
deprecated_jsdoc,
33+
] | comment }}
34+
{%- endmacro -%}

‎scripts/semconv/templates/registry/ts-stable/metrics.ts.j2

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{%- import 'docstring.ts.j2' as d %}
2+
/*
3+
* Copyright The OpenTelemetry Authors
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* https://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
//----------------------------------------------------------------------------------------------------------
19+
// DO NOT EDIT, this is an Auto-generated file from scripts/semconv/templates/register/stable/metrics.ts.j2
20+
//----------------------------------------------------------------------------------------------------------
21+
22+
{% for metric in ctx.metrics | sort(attribute="metric_name") %}
23+
{{d.docstring(metric, "metric")}}
24+
export const METRIC_{{ metric.metric_name | screaming_snake_case }} = '{{metric.metric_name}}' as const;
25+
26+
{% endfor %}

‎scripts/semconv/templates/registry/ts-stable/weaver.yaml

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# ts-stable/... generates the "semantic-conventions/src/stable_*.ts" files.
2+
3+
templates:
4+
- pattern: attributes.ts.j2
5+
file_name: "stable_attributes.ts"
6+
filter: >
7+
semconv_attributes({
8+
"stable_only": true
9+
}) | {
10+
attributes: .
11+
}
12+
application_mode: single
13+
- pattern: metrics.ts.j2
14+
file_name: "stable_metrics.ts"
15+
filter: >
16+
semconv_metrics({
17+
"stable_only": true
18+
}) | {
19+
metrics: .
20+
}
21+
application_mode: single
22+
23+
params:
24+
excluded_attributes: ["messaging.client_id"]
25+
26+
##
27+
# Everything below here is expected to be the same as in "../ts-*/weaver.yaml".
28+
##
29+
30+
# https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md#comment-filter
31+
comment_formats:
32+
jsdoc:
33+
format: markdown
34+
header: '/**'
35+
# Note: This results in trailing whitespace on empty lines. IMHO the
36+
# 'comment' filter should handle those.
37+
prefix: ' * '
38+
footer: ' */'
39+
trim: true
40+
indent_first_level_list_items: true
41+
escape_backslashes: true
42+
default_comment_format: jsdoc
43+
44+
# Whitespace control settings to simplify the definition of templates
45+
whitespace_control:
46+
trim_blocks: true
47+
lstrip_blocks: true
48+
49+
text_maps:
50+
js_types:
51+
int: number
52+
double: number
53+
boolean: boolean
54+
string: string
55+
string[]: string[]

‎semantic-conventions/CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ All notable changes to the semantic-conventions package will be documented in th
77

88
### :boom: Breaking Changes
99

10+
* fix: Remove the subset of `DB_SYSTEM_NAME_VALUE_*` exports that are unstable from the `@opentelemetry/semantic-conventions` entry point. [#5690](https://github.com/open-telemetry/opentelemetry-js/pull/5690)
11+
* Version 1.33.0 erroneously included all `DB_SYSTEM_NAME_VALUE_*` constants in the stable entry point. Some of those enum values are not yet stable. They have been moved back to the unstable `@opentelemetry/semantic-conventions/incubating` entry point. See the PR description for a full list.
12+
1013
### :rocket: Features
1114

1215
### :bug: Bug Fixes

0 commit comments

Comments
 (0)