From 78836c4f3ba0a846958b4c93d700b15858930d9c Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 10 Apr 2025 17:52:13 -0700 Subject: [PATCH 1/3] Update weaver and support collision resolution --- dependencies.Dockerfile | 2 +- docs/dotnet/dotnet-kestrel-metrics.md | 2 +- model/kestrel/metrics.yaml | 7 ++---- .../deprecated/registry-deprecated.yaml | 3 +++ policies/attribute_name_collisions.rego | 22 +++++++++---------- .../attribute_name_collisions_test.rego | 9 ++++++++ 6 files changed, 27 insertions(+), 18 deletions(-) diff --git a/dependencies.Dockerfile b/dependencies.Dockerfile index ff414dad6c..8c09ea13ed 100644 --- a/dependencies.Dockerfile +++ b/dependencies.Dockerfile @@ -3,7 +3,7 @@ # Dependabot can keep this file up to date with latest containers. # Weaver is used to generate markdown docs, and enforce policies on the model. -FROM otel/weaver:v0.13.2 AS weaver +FROM otel/weaver:v0.14.0 AS weaver # OPA is used to test policies enforced by weaver. FROM openpolicyagent/opa:1.3.0 AS opa diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 9af3da8898..8a84c69870 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -111,7 +111,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Captures the error type when a connection fails. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [2] | `http`; `web_sockets` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/kestrel/metrics.yaml b/model/kestrel/metrics.yaml index 35f44bd469..9965df87f1 100644 --- a/model/kestrel/metrics.yaml +++ b/model/kestrel/metrics.yaml @@ -38,14 +38,11 @@ groups: - ref: network.protocol.version examples: ["1.1", "2"] - ref: tls.protocol.version + # yamllint disable rule:line-length - ref: error.type - brief: The full name of exception type. + brief: Captures the error type when a connection fails. requirement_level: conditionally_required: if and only if an error has occurred. - note: "Captures the exception type when a connection fails." - examples: ['System.OperationCanceledException', 'Contoso.MyException'] - # yamllint disable rule:line-length - - ref: error.type # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported note: | Starting from .NET 9, Kestrel `kestrel.connection.duration` metric reports diff --git a/model/messaging/deprecated/registry-deprecated.yaml b/model/messaging/deprecated/registry-deprecated.yaml index 0832491905..ad0414d02c 100644 --- a/model/messaging/deprecated/registry-deprecated.yaml +++ b/model/messaging/deprecated/registry-deprecated.yaml @@ -26,6 +26,9 @@ groups: Deprecated, use `messaging.client.id` instead. examples: ['client-5', 'myhost@8742@s8083jm'] deprecated: "Replaced by `messaging.client.id`." + annotations: + code_generation: + exclude: true - id: messaging.kafka.consumer.group type: string brief: > diff --git a/policies/attribute_name_collisions.rego b/policies/attribute_name_collisions.rego index 0aa7bb506e..374be5ca07 100644 --- a/policies/attribute_name_collisions.rego +++ b/policies/attribute_name_collisions.rego @@ -6,7 +6,7 @@ import rego.v1 attribute_names := { obj | group := input.groups[_]; attr := group.attributes[_]; - obj := { "name": attr.name, "const_name": to_const_name(attr.name), "namespace_prefix": to_namespace_prefix(attr.name), "deprecated": is_property_set(attr, "deprecated") } + obj := { "name": attr.name, "const_name": to_const_name(attr.name), "namespace_prefix": to_namespace_prefix(attr.name), "deprecated": is_property_set(attr, "deprecated"), "annotations": property_or_null(attr, "annotations") } } # check that attribute constant names do not collide @@ -14,14 +14,19 @@ deny contains attr_registry_collision(description, name) if { some i name := attribute_names[i].name const_name := attribute_names[i].const_name - not excluded_const_collisions[name] + annotations := attribute_names[i].annotations + + not annotations["code_generation"]["exclude"] + collisions := [other.name | other := attribute_names[_] other.name != name other.const_name == const_name - not excluded_const_collisions[other.name] + + not other.annotations["code_generation"]["exclude"] ] count(collisions) > 0 + # TODO (https://github.com/open-telemetry/weaver/issues/279): provide other violation properties once weaver supports it. description := sprintf("Attribute '%s' has the same constant name '%s' as '%s'.", [name, const_name, collisions]) } @@ -82,11 +87,6 @@ is_property_set(obj, property) = true if { obj[property] != null } else = false -# This list contains exceptions for existing collisions that were introduced unintentionally. -# We'll have a way to specify how collision resolution happens in the schema - -# see phase 2 in https://github.com/open-telemetry/semantic-conventions/issues/1118#issuecomment-2173803006 -# For now we'll exclude existing collisions from the checks. -# ADDING NEW EXCEPTIONS IS NOT ALLOWED. - -# DO NOT ADD ATTRIBUTES TO THIS LIST -excluded_const_collisions := {"messaging.client_id"} +property_or_null(obj, property) := obj[property] if { + obj[property] +} else = null diff --git a/policies_test/attribute_name_collisions_test.rego b/policies_test/attribute_name_collisions_test.rego index 2d09beb7c4..2d08d0faf9 100644 --- a/policies_test/attribute_name_collisions_test.rego +++ b/policies_test/attribute_name_collisions_test.rego @@ -29,3 +29,12 @@ test_does_not_fail_on_deprecated_namespace_collision if { count(deny) == 0 with input as collision } +test_does_not_fail_on_excluded_name_collision if { + collision := {"groups": [ + {"id": "test1", "attributes": [{"name": "test1.namespace.id"}, {"name": "test1.namespace_id", "annotations": {"code_generation": {"exclude": true}}}]}, + + {"id": "test2", "attributes": [{"name": "test2.namespace_id"}, {"name": "test2.namespace.id", "annotations": {"code_generation": {"exclude": true}}}]}, + ]} + count(deny) == 0 with input as collision +} + From 4805a425aa29f1ac929b8c92c25f6e7628fbbe74 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 10 Apr 2025 17:54:53 -0700 Subject: [PATCH 2/3] clean up --- docs/dotnet/dotnet-kestrel-metrics.md | 2 +- model/kestrel/metrics.yaml | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 8a84c69870..9af3da8898 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -111,7 +111,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | Captures the error type when a connection fails. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [2] | `http`; `web_sockets` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/kestrel/metrics.yaml b/model/kestrel/metrics.yaml index 9965df87f1..e84787bbf8 100644 --- a/model/kestrel/metrics.yaml +++ b/model/kestrel/metrics.yaml @@ -40,9 +40,10 @@ groups: - ref: tls.protocol.version # yamllint disable rule:line-length - ref: error.type - brief: Captures the error type when a connection fails. + brief: The full name of exception type. requirement_level: conditionally_required: if and only if an error has occurred. + examples: ['System.OperationCanceledException', 'Contoso.MyException'] # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported note: | Starting from .NET 9, Kestrel `kestrel.connection.duration` metric reports From 29d5b8b59149ce2490cba64d4ba763deaddc67a1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 11 Apr 2025 09:28:02 -0700 Subject: [PATCH 3/3] feedback --- docs/dotnet/dotnet-kestrel-metrics.md | 2 +- model/kestrel/metrics.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 9af3da8898..a2baf7e247 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -111,7 +111,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | The full name of exception type. [1] | `connection_reset`; `invalid_handshake` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [2] | `http`; `web_sockets` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/kestrel/metrics.yaml b/model/kestrel/metrics.yaml index e84787bbf8..d8759712f6 100644 --- a/model/kestrel/metrics.yaml +++ b/model/kestrel/metrics.yaml @@ -43,7 +43,7 @@ groups: brief: The full name of exception type. requirement_level: conditionally_required: if and only if an error has occurred. - examples: ['System.OperationCanceledException', 'Contoso.MyException'] + examples: ['connection_reset', 'invalid_handshake'] # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported note: | Starting from .NET 9, Kestrel `kestrel.connection.duration` metric reports