refactor semantic conventions (#1659)

Align with how the spec advises SemConv should be organised, and break unstable
semconvs out into their own directory.
I played around with generating values as enums, but I could only get this to work
if the output was in the same file as the attributes (which would not work well with
composer autoloading), so I've used <attribute>_VALUE_<name>, similar to what we have
now except all in the same file.

* fix linting, broken values containing '.'

* fix incubating namespace

* update semconv readme

* restore ResourceAttributeValues

* adding DNS semconv

* adding db metrics

Author: brettmc

script/semantic-conventions/semconv.sh

@@ -17,10 +17,10 @@ SPEC_DIR="${ROOT_DIR}/var/semantic-conventions"
 CODE_DIR="${ROOT_DIR}/src/SemConv"
 
 # freeze the spec & generator tools versions to make SemanticAttributes generation reproducible
-SEMCONV_VERSION=1.32.0
+SEMCONV_VERSION=1.36.0
 SPEC_VERSION=v$SEMCONV_VERSION
 SCHEMA_URL=https://opentelemetry.io/schemas/$SEMCONV_VERSION
-OTEL_WEAVER_IMG_VERSION=v0.15.2
+OTEL_WEAVER_IMG_VERSION=v0.16.1
 
 rm -rf "${SPEC_DIR}"
 mkdir "${SPEC_DIR}"
@@ -34,7 +34,13 @@ git reset --hard FETCH_HEAD
 cd "${SCRIPT_DIR}"
 
 mkdir -p "${CODE_DIR}"
-find "${CODE_DIR}" -name "*.php" ! -name "Version.php" -exec rm -f {} \;
+find "${CODE_DIR}" -name "*.php" \
+  ! -name "Version.php" \
+  ! -name "ResourceAttributes.php" \
+  ! -name "ResourceAttributeValues.php" \
+  ! -name "TraceAttributes.php" \
+  ! -name "TraceAttributeValues.php" \
+  -exec rm -f {} \;
 
 echo "${SCHEMA_URL}" > ${SCRIPT_DIR}/templates/registry/php/version.txt
 

script/semantic-conventions/templates/registry/php/AttributeValues.php.j2

@@ -1,29 +1,31 @@
+{%- set my_class_name = ctx.root_namespace | pascal_case ~ ("Incubating" if ctx.incubating ) ~ "Metrics" -%}
 <?php
 
 // DO NOT EDIT, this is an Auto-generated file from script/semantic-conventions
 
 declare(strict_types=1);
 
-namespace OpenTelemetry\SemConv\Metrics;
+namespace {{ ctx.namespace }};
 
-interface {{ ctx.root_namespace | pascal_case }}Metrics
+/**
+ * Metrics for {{ ctx.root_namespace }}.
+{% if ctx.incubating %}
+ * May contain @experimental Semantic Conventions which may change or be removed in the future.
+{% endif %}
+ */
+interface {{ my_class_name }}
 {
 {# blank line #}
 {%- for metric in ctx.metrics %}
 {% set const_name = metric.metric_name | screaming_snake_case %}
-    {%- if metric is deprecated %}
-        {%- set deprecated_phpdoc = "@deprecated" -%}
-    {% else %}
-        {% set deprecated_phpdoc = "" %}
-    {%- endif -%}
+    {%- set instrument_phpdoc = "Instrument: " ~ metric.instrument -%}
+    {%- set unit_phpdoc = "Unit: " ~ metric.unit -%}
     {%- if metric is stable -%}
         {%- set stability_phpdoc = "@stable" -%}
     {%- else -%}
         {%- set stability_phpdoc = "@experimental" -%}
     {%- endif -%}
-    {%- set instrument_phpdoc = "Instrument: " ~ metric.instrument -%}
-    {%- set unit_phpdoc = "Unit: " ~ metric.unit -%}
-    {{ [metric.brief, concat_if(metric.note), instrument_phpdoc, unit_phpdoc, deprecated_phpdoc, stability_phpdoc] | comment(indent=4)  | replace(' \n', '\n') }}
+    {{ [metric.brief, concat_if(metric.note), instrument_phpdoc, unit_phpdoc, stability_phpdoc] | comment(indent=4)  | replace(' \n', '\n') }}
     public const {{ const_name }} = '{{ metric.metric_name }}';
 
 {% endfor %}

script/semantic-conventions/templates/registry/php/Attributes.php.j2

@@ -0,0 +1,33 @@
+{% import 'common.j2' as c %}
+{%- set my_class_name = ctx.root_namespace | pascal_case ~ ("Incubating" if ctx.incubating ) ~ "Attributes" -%}
+<?php
+
+// DO NOT EDIT, this is an Auto-generated file from script/semantic-conventions
+
+declare(strict_types=1);
+
+namespace {{ ctx.namespace }};
+
+/**
+ * Semantic attributes and corresponding values for {{ ctx.root_namespace }}.
+ * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/{{ ctx.root_namespace }}/
+{% if ctx.incubating %}
+ * May contain @experimental Semantic Conventions which may change or be removed in the future.
+{% endif %}
+ */
+interface {{ my_class_name }}
+{
+{% for attribute in ctx.attributes | rejectattr("name", "in", ctx.excluded_attributes) if not (attribute is deprecated) %}
+{%- set stability_phpdoc = c.stability(attribute) -%}
+{{ [attribute.brief, concat_if(attribute.note), stability_phpdoc] | comment(indent=4)  | replace(' \n', '\n') }}
+    public const {{ c.attribute_name(attribute) }} = '{{ attribute.name }}';
+
+    {% if attribute is enum %}{% for member in attribute.type.members if not (member is deprecated) %}
+        {%- set stability_phpdoc = c.stability(attribute) -%}
+{{ [member.brief, stability_phpdoc] | comment(indent=4)}}
+    public const {{ c.attribute_value_name(attribute, member) }} = {{ member.value | print_member_value | replace('"', "'") }};
+
+    {% endfor %}{% endif %}
+{% endfor %}
+}
+{# blank line #}

script/semantic-conventions/templates/registry/php/Metrics.php.j2

@@ -27,10 +27,14 @@
     {{to_const_name(attribute.name)}}
 {%- endmacro -%}
 
-{%- macro attribute_value_name(member) -%}
-    {{to_const_name(member.id)}}
+{%- macro attribute_value_name(attribute, member) -%}
+    {{ to_const_name(attribute.name) ~ "_VALUE_" ~ to_const_name(member.id) }}
 {%- endmacro -%}
 
-{%- macro attribute_stability(attribute) -%}
-    {% if attribute.deprecated %}deprecated{% else %}{{attribute.stability}}{%endif%}
+{%- macro stability(member) -%}
+    {%- if member is stable -%}
+        {{ "@stable" }}
+    {%- else -%}
+        {{ "@experimental" }}
+    {%- endif -%}
 {%- endmacro -%}

script/semantic-conventions/templates/registry/php/ResourceAttributeValues.php.j2

@@ -1,13 +1,23 @@
 params:
   # excluded namespaces will not be generated
   # this behavior is fully controlled by jinja templates
-  # TODO exclude more namespaces, eg: ios, aspnetcore, signalr, android, dotnet, jvm, kestrel, browser, device, ...
-  excluded_namespaces: [cloudfoundry, dotnet, hw, nodejs, profile]
-  excluded_metrics_namespaces: [aspnetcore, azure, cicd, container, cpu, cpython, db, dns, dotnet, faas, gen_ai, go, hw, jvm, k8s, kestrel, messaging, nodejs, process, rpc, signalr, system, v8js, vcs]
+  excluded_namespaces: [
+    android, app, artifact, aws, azure, browser, cassandra, device, disk,
+    elasticsearch, enduser, event, faas, feature_flag, file, gen_ai, gcp,
+    geo, go, graphql, heroku, ios, k8s, linux, mainframe, message, network,
+    oci, openai, opentracing, other, pool, rpc, security_rule, source, system, test,
+    tls, useragent, v8js, vcs, webengine, zos, az, session, thread, destination,
+    cicd, cloud, cloudevents, cpu, cpython, deployment, aspnetcore,
+    cloudfoundry, dotnet, hw, jvm, nodejs, profile, signalr
+  ]
+  excluded_metrics_namespaces: [
+    aspnetcore, azure, cicd, container, cpu, cpython, dotnet,
+    faas, gen_ai, go, hw, jvm, k8s, kestrel, messaging, nodejs, process,
+    rpc, signalr, system, v8js, vcs
+  ]
 
-  # excluded attributes will be commented out in the generated code
-  # this behavior is fully controlled by jinja templates
-  excluded_attributes: ["messaging.client_id"]
+  # excluded attributes will be skipped (eg "messaging.client.id" vs "messaging.client_id" breakage)
+  excluded_attributes: []
 
 text_maps:
   php_types:
@@ -18,55 +28,60 @@ text_maps:
     string[]: string[]
     template[string]: string
     template[string[]]: string[]
-
 templates:
-  - template: Attributes.php.j2
+  - pattern: SemanticAttributes.php.j2
     filter: >
       semconv_grouped_attributes({
         "exclude_root_namespace": $excluded_namespaces,
-        "exclude_stability": [],
+        "exclude_stability": [ "experimental", "deprecated" ]
       }) | map({
         root_namespace: .root_namespace,
         attributes: .attributes,
-        excluded_attributes: $excluded_attributes
+        excluded_attributes: $excluded_attributes,
+        namespace: "OpenTelemetry\\SemConv\\Attributes",
+        experimental: false,
       })
-    application_mode: single
-    file_name: "TraceAttributes.php"
-  - template: AttributeValues.php.j2
+    application_mode: each
+    file_name: "Attributes/{{ctx.root_namespace | pascal_case}}Attributes.php"
+  - pattern: SemanticAttributes.php.j2
     filter: >
       semconv_grouped_attributes({
         "exclude_root_namespace": $excluded_namespaces,
-        "exclude_stability": [],
+        "exclude_stability": [ "deprecated" ]
+      }) | map({
+        root_namespace: .root_namespace,
+        attributes: .attributes,
+        excluded_attributes: $excluded_attributes,
+        namespace: "OpenTelemetry\\SemConv\\Incubating\\Attributes",
+        incubating: true,
       })
-    application_mode: single
-    file_name: "TraceAttributeValues.php"
-  - template: ResourceAttributes.php.j2
-    filter: >
-      semconv_signal("resource"; {})
-      | map(.attributes[])
-      | group_by(.name)
-      | map(.[-1])
-    application_mode: single
-    file_name: "ResourceAttributes.php"
-  - template: ResourceAttributeValues.php.j2
-    filter: >
-      semconv_signal("resource"; {})
-      | map(.attributes[])
-      | group_by(.name)
-      | map(.[-1])
-    application_mode: single
-    file_name: "ResourceAttributeValues.php"
+    application_mode: each
+    file_name: "Incubating/Attributes/{{ctx.root_namespace | pascal_case}}IncubatingAttributes.php"
   - template: Metrics.php.j2
     filter: >
       semconv_grouped_metrics({
         "exclude_root_namespace": $excluded_metrics_namespaces,
-        "exclude_stability": [],
+        "exclude_stability": [ "experimental", "deprecated" ]
       }) | map({
         root_namespace: .root_namespace,
         metrics: .metrics,
+        namespace: "OpenTelemetry\\SemConv\\Metrics",
       })
     application_mode: each
     file_name: "Metrics/{{ctx.root_namespace | pascal_case}}Metrics.php"
+  - template: Metrics.php.j2
+    filter: >
+      semconv_grouped_metrics({
+        "exclude_root_namespace": $excluded_metrics_namespaces,
+        "exclude_stability": [ "deprecated" ]
+      }) | map({
+        root_namespace: .root_namespace,
+        metrics: .metrics,
+        namespace: "OpenTelemetry\\SemConv\\Unstable\\Metrics",
+        incubating: true,
+      })
+    application_mode: each
+    file_name: "Incubating/Metrics/{{ctx.root_namespace | pascal_case}}IncubatingMetrics.php"
 whitespace_control:
   trim_blocks: true
   lstrip_blocks: true