diff --git a/.chloggen/785.yaml b/.chloggen/785.yaml new file mode 100644 index 000000000..f00ba848e --- /dev/null +++ b/.chloggen/785.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: dns +note: Introduces common DNS lookup duration metric and attributes. +issues: [404] diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md new file mode 100644 index 000000000..eeb6e10d5 --- /dev/null +++ b/docs/attributes-registry/dns.md @@ -0,0 +1,14 @@ + + +# DNS + +## DNS Attributes + + +| 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. + \ No newline at end of file diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md new file mode 100644 index 000000000..46262286c --- /dev/null +++ b/docs/dns/dns-metrics.md @@ -0,0 +1,55 @@ + + +# Semantic Conventions for DNS queries + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions to apply when instrumenting DNS queries. + + + + + +- [Metrics](#metrics) + - [Metric: `dns.lookup.duration`](#metric-dnslookupduration) + + + +## 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 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. | + + + +| 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. | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 4240445dd..6df6fb85d 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/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 ]`. - + | 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 - - | 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. | - [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/metrics/dns.yaml b/model/metrics/dns.yaml new file mode 100644 index 000000000..627213d90 --- /dev/null +++ b/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"] diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index 9a326bb5d..6b3723ddb 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/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" diff --git a/model/registry/dns.yaml b/model/registry/dns.yaml new file mode 100644 index 000000000..d4042c4ad --- /dev/null +++ b/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.