Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.03%. Comparing base (4e2703c) to head (36ffadd).
Report is 5 commits behind head on main.

@@           Coverage Diff           @@
##             main    #5690   +/-   ##
=======================================
  Coverage   95.03%   95.03%           
=======================================
  Files         310      310           
  Lines        7992     7992           
  Branches     1614     1614           
=======================================
  Hits         7595     7595           
  Misses        397      397           

Implementation note: While the weaver config and templates were split into two dirs, it may be useful to see how scripts/semconv/templates/registry/ts-stable and scripts/semconv/templates/registry/ts-experimental differ:

% diff -ur ts-stable ts-experimental
diff -ur ts-stable/attributes.ts.j2 ts-experimental/attributes.ts.j2
--- ts-stable/attributes.ts.j2	2025-05-15 14:55:51
+++ ts-experimental/attributes.ts.j2	2025-05-15 14:55:51
@@ -21,6 +21,7 @@

 {% for attribute in ctx.attributes | attribute_sort %}
 {% if attribute.name not in params.excluded_attributes %}
+{% if attribute is not stable %}
 {{d.docstring(attribute, "attribute")}}
 {% if attribute.type is not template_type %}
 export const ATTR_{{ attribute.name | screaming_snake_case }} = '{{attribute.name}}' as const;
@@ -29,9 +30,10 @@
 export const ATTR_{{ attribute.name | screaming_snake_case }} = (key: string) => `{{attribute.name}}.${key}`;

 {% endif %}
+{% endif %}
 {% if attribute.type is mapping %}
 {% for espec in attribute.type.members | sort(attribute='value') %}
-{% if espec is stable %}
+{% if espec is not stable %}
 /**
  * Enum value {{ espec.value | print_member_value }} for attribute {@link ATTR_{{ attribute.name | screaming_snake_case }}}.
  */
diff -ur ts-stable/weaver.yaml ts-experimental/weaver.yaml
--- ts-stable/weaver.yaml	2025-05-15 15:04:39
+++ ts-experimental/weaver.yaml	2025-05-15 15:06:34
@@ -1,20 +1,28 @@
-# ts-stable/... generates the "semantic-conventions/src/stable_*.ts" files.
+# ts-experimental/... generates the "semantic-conventions/src/experimental_*.ts"
+# files.

+# Notes:
+# - Use `""` and `null` with `exclude_stability` to skip attributes/metrics that
+#   accidentally do not have a stability set
+#   (e.g. https://github.com/open-telemetry/semantic-conventions/issues/1777).
 templates:
   - pattern: attributes.ts.j2
-    file_name: "stable_attributes.ts"
+    file_name: "experimental_attributes.ts"
+    # This "exclude_stability" does *not* exclude "stable" because it needs
+    # to process *stable* enums that might have *unstable* members. (e.g.,
+    # `db.system.name` is stable, but some of its enum values are not.)
     filter: >
       semconv_attributes({
-        "stable_only": true
+        "exclude_stability": ["", null]
       }) | {
         attributes: .
       }
     application_mode: single
   - pattern: metrics.ts.j2
-    file_name: "stable_metrics.ts"
+    file_name: "experimental_metrics.ts"
     filter: >
       semconv_metrics({
-        "stable_only": true
+        "exclude_stability": ["stable", "", null]
       }) | {
         metrics: .
       }

What to do about removing exports from the "stable" entry-point? Options:

1. Just remove them. Release as v1.33.1 and hope it doesn't break anyone. (Honestly I doubt that it will.)
2. Keep the exports in the stable entry-point, but add @experimental and @deprecated jsdoc tags to their comment blocks explaining the issue. This is problematic because currently the .../incubating entry-point exports both the stable and experimental exports... and having, e.g., DB_SYSTEM_NAME_VALUE_SQLITE defined in both stable_attributes.ts and experimental_attributes.ts makes handling that a pain. The only way I can think to handle that would be to have this line in "index-incubating.ts" be expanded to explicitly list all exports except those few accidental ones. There are currently about 130 of them, so not too bad.
3. Do option 2, but just for NETWORK_TRANSPORT_VALUE_QUIC because it has been there for a number of releases.

Update: semconv is going to grandfather in ..._QUIC (open-telemetry/semantic-conventions#2275). Presumably that'll be in a 1.33.1 or 1.34.0 release. So another option:

4. If that ^^ release is v1.34.0, let's do a v1.33.1 release that drops the unstable DB_SYSTEM_NAME_VALUE_* exports (like in Option 1), but keeps the NETWORK_TRANSPORT_VALUE_QUIC. Then we do a v1.34.0 release which will be able to remove the special handling for NETWORK_TRANSPORT_VALUE_QUIC.

1. Just remove them. Release as v1.33.1 and hope it doesn't break anyone. (Honestly I doubt that it will.)

[narrator] Look at this: https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2671/files/53585cb522a3f7b419391fd761fda071b21be2be..88fb85c6b9e5a0fc9ed1260fc763d2c34846c5b3#diff-ce92a05c80ac8c55280922ac396fdea2f64de6902642f6ec4903bb32cb8087ccR20-R21

This (not yet merged) PR was going to DB_SYSTEM_NAME_VALUE_SQLITE from @opentelemetry/semantic-conventions@1.33.0.

Not a breakage, because not merged, but we should decide on this soonish.

For what is worth, regarding db.system.name, the list you provide are not stable, not because of the names itself, but because we didn't have any prototypes or testing for all those cases. We wanted to make sure the metrics/spans/attributes can all be collected for all those databases before marking them stable, so we left to the vendor to do the testing, etc.
We don't foresee any changes coming on the database names itself, so might not be such a big deal having them stable/development for this case.

4. If that ^^ release is v1.34.0,

It will be a v1.34.0 release (planned for next week).

^^ commit cfe1411 makes the changes for Option 4.

@maryliag Thanks. The template handling to avoid this is generic, so a future v1.34.0 release would move them back to the unstable entry-point. I think it is a little clearer to the user if the state in v1.33.0 is considered a bug, and it is fixed in a v1.33.1 point release.

4. If that ^^ release is v1.34.0, let's do a v1.33.1 release that drops the unstable DB_SYSTEM_NAME_VALUE_* exports (like in Option 1), but keeps the NETWORK_TRANSPORT_VALUE_QUIC. Then we do a v1.34.0 release which will be able to remove the special handling for NETWORK_TRANSPORT_VALUE_QUIC.

I think that's the way. 👍