Move DNS lookup metric outside of .NET semconv (#785)

.chloggen/785.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: dns
+note: Introduces common DNS lookup duration metric and attributes.
+issues: [404]

docs/attributes-registry/dns.md

@@ -0,0 +1,14 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# DNS
+
+## DNS Attributes
+
+<!-- semconv registry.dns(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `opentelemetry.io` |
+
+**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively.
+<!-- endsemconv -->

docs/dns/dns-metrics.md

@@ -0,0 +1,55 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: DNS
+--->
+
+# Semantic Conventions for DNS queries
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions to apply when instrumenting DNS queries.
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [Metrics](#metrics)
+  - [Metric: `dns.lookup.duration`](#metric-dnslookupduration)
+
+<!-- tocstop -->
+
+## Metrics
+
+### Metric: `dns.lookup.duration`
+
+**Status**: [Experimental][DocumentStatus]
+
+This metric is optional.
+
+This metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
+
+<!-- semconv metric.dns.lookup.duration(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. |
+<!-- endsemconv -->
+
+<!-- semconv metric.dns.lookup.duration(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`dns.question.name`](../attributes-registry/dns.md) | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required |
+| [`error.type`](../attributes-registry/error.md) | string | Describes the error the DNS lookup failed with. [2] | `host_not_found`; `no_recovery`; `java.net.UnknownHostException` | Conditionally Required: if and only if an error has occurred. |
+
+**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively.
+
+**[2]:** Instrumentations SHOULD use error code such as one of errors reported by `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the runtime or client library. If error code is not available, the full name of exception type SHOULD be used.
+
+`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

docs/dotnet/dotnet-dns-metrics.md

@@ -19,19 +19,17 @@ This article defines semantic conventions for DNS metrics emitted by .NET.
 
 ### Metric: `dns.lookup.duration`
 
-this metric SHOULD be specified with
+This metric SHOULD be specified with
 [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
 
-<!-- semconv metric.dotnet.dns.lookup.duration(metric_table) -->
+<!-- Tables in this document are not auto-generated and are intentionally frozen in time. From the .NET perspective this metric and its attributes are stable till the next major version. They are still experimental in the OpenTelemetry. -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
 | `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. [1] |
 
 **[1]:** Meter name: `System.Net.NameResolution`; Added in: .NET 8.0
-<!-- endsemconv -->
 
-<!-- semconv metric.dotnet.dns.lookup.duration(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required |
@@ -55,6 +53,5 @@ for more details.
 | Value  | Description |
 |---|---|
 | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |
-<!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

model/metrics/dns.yaml

@@ -0,0 +1,23 @@
+groups:
+  - id: metric.dns.lookup.duration
+    type: metric
+    metric_name: dns.lookup.duration
+    stability: experimental
+    brief: Measures the time taken to perform a DNS lookup.
+    instrument: histogram
+    unit: "s"
+    attributes:
+      - ref: dns.question.name
+        requirement_level: required
+        examples: ["www.example.com", "dot.net"]
+      - ref: error.type
+        requirement_level:
+          conditionally_required: if and only if an error has occurred.
+        brief: Describes the error the DNS lookup failed with.
+        note: >
+          Instrumentations SHOULD use error code such as one of errors reported by
+          `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) /
+          [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the
+          runtime or client library.
+          If error code is not available, the full name of exception type SHOULD be used.
+        examples: ["host_not_found", "no_recovery", "java.net.UnknownHostException"]

model/metrics/dotnet/dotnet-http.yaml

@@ -1,42 +1,4 @@
 groups:
-  - id: metric.dotnet.dns.lookup.duration
-    type: metric
-    metric_name: dns.lookup.duration
-    brief: Measures the time taken to perform a DNS lookup.
-    instrument: histogram
-    unit: "s"
-    note: |
-      Meter name: `System.Net.NameResolution`; Added in: .NET 8.0
-    attributes:
-      - id: dns.question.name
-        type: string
-        brief: The name being queried.
-        requirement_level: required
-        examples: ["www.example.com", "dot.net"]
-        note: >
-          The name being queried.
-
-          If the name field contains non-printable
-          characters (below 32 or above 126), those characters should be represented
-          as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped.
-          Tabs, carriage returns, and line feeds should be converted to \t, \r, and
-          \n respectively.
-      - ref: error.type
-        brief: One of the resolution errors or the full name of exception type.
-        requirement_level:
-          conditionally_required: if and only if an error has occurred.
-        note: |
-          The following errors codes are reported:
-
-          - "host_not_found"
-          - "try_again"
-          - "address_family_not_supported"
-          - "no_recovery"
-
-          See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror)
-          for more details.
-        examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"]
-
   - id: dotnet.http.client.common.attributes
     type: attribute_group
     brief: "Common HTTP client attributes"

model/registry/dns.yaml

@@ -0,0 +1,18 @@
+groups:
+  - id: registry.dns
+    type: attribute_group
+    prefix: dns
+    brief: >
+      This document defines the shared attributes used to report a DNS query.
+    attributes:
+      - id: question.name
+        type: string
+        stability: experimental
+        brief: The name being queried.
+        examples: ["www.example.com", "opentelemetry.io"]
+        note: >
+          If the name field contains non-printable
+          characters (below 32 or above 126), those characters should be represented
+          as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped.
+          Tabs, carriage returns, and line feeds should be converted to \t, \r, and
+          \n respectively.