From 92d66de1417b6be1d82c3e1654adb2040bb67aea Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 24 Jul 2023 10:24:06 -0700 Subject: [PATCH 01/19] dotnet http metrics --- .github/CODEOWNERS | 5 + CHANGELOG.md | 2 + docs/dotnet/README.md | 22 ++ docs/dotnet/dotnet-aspnetcore-metrics.md | 206 +++++++++++ docs/dotnet/dotnet-dns-metrics.md | 40 +++ docs/dotnet/dotnet-http-metrics.md | 260 ++++++++++++++ docs/dotnet/dotnet-kestrel-metrics.md | 366 ++++++++++++++++++++ docs/dotnet/dotnet-signalr-metrics.md | 80 +++++ model/metrics/dotnet/dotnet-aspnetcore.yaml | 174 ++++++++++ model/metrics/dotnet/dotnet-http.yaml | 174 ++++++++++ model/metrics/dotnet/dotnet-kestrel.yaml | 129 +++++++ model/metrics/dotnet/dotnet-signalr.yaml | 59 ++++ 12 files changed, 1517 insertions(+) create mode 100644 docs/dotnet/README.md create mode 100644 docs/dotnet/dotnet-aspnetcore-metrics.md create mode 100644 docs/dotnet/dotnet-dns-metrics.md create mode 100644 docs/dotnet/dotnet-http-metrics.md create mode 100644 docs/dotnet/dotnet-kestrel-metrics.md create mode 100644 docs/dotnet/dotnet-signalr-metrics.md create mode 100644 model/metrics/dotnet/dotnet-aspnetcore.yaml create mode 100644 model/metrics/dotnet/dotnet-http.yaml create mode 100644 model/metrics/dotnet/dotnet-kestrel.yaml create mode 100644 model/metrics/dotnet/dotnet-signalr.yaml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 72eac076ba..31b5487a93 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -74,3 +74,8 @@ /model/registry/container.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers /model/registry/oci.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +# .NET semantic conventions approvers +/model/metrics/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approvers @open-telemetry/semconv-http-approvers +/docs/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approvers @open-telemetry/semconv-http-approvers + +# TODO - Add semconv area experts diff --git a/CHANGELOG.md b/CHANGELOG.md index deffa3d7c7..1a2b1c5162 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,8 @@ release. ([#503](https://github.com/open-telemetry/semantic-conventions/pull/503)) - Add Semantic conventions for TLS/SSL encrypted communication. ([#21](https://github.com/open-telemetry/semantic-conventions/pull/21)) +- Add .NET 8.0 metrics for HTTP client, ASP.NET Core, SignalR server and Kestrel. + ([#283](https://github.com/open-telemetry/semantic-conventions/pull/283)) ### Fixes diff --git a/docs/dotnet/README.md b/docs/dotnet/README.md new file mode 100644 index 0000000000..9ede79f11f --- /dev/null +++ b/docs/dotnet/README.md @@ -0,0 +1,22 @@ + + +# Semantic Conventions for .NET metrics + +**Status**: [Experimental, Feature-freeze][DocumentStatus] + +This document documents semantic conventions for metrics emitted by .NET runtime and individual components in .NET ecosystem. + +Following metrics are currently supported: + +* [ASP.NET Core](dotnet-aspnetcore-metrics.md): Semantic Conventions for ASP.NET Core routing, exceptions, and rate-limiting *metrics*. +* [DNS](dotnet-dns-metrics.md): Semantic Conventions for client-side DNS lookups associated with *metrics*. +* [HTTP](dotnet-http-metrics.md): Semantic Conventions for HTTP client and server *metrics*. +* [Kestrel](dotnet-kestrel-metrics.md): Semantic Conventions for Kestrel web server *metrics*. +* [SignalR](dotnet-signalr-metrics.md): Semantic Conventions for SignalR server *metrics*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md new file mode 100644 index 0000000000..423ad37fad --- /dev/null +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -0,0 +1,206 @@ +# Semantic Conventions for ASP.NET Core metrics + +**Status**: [Experimental, Feature-freeze][DocumentStatus] + +This document defines semantic conventions for ASP.NET Core metrics. + + + +- [Server](#server) +- [Routing](#routing) + * [Metric: `aspnetcore.routing.match_attempts`](#metric-aspnetcoreroutingmatch_attempts) +- [Exception metrics](#exception-metrics) + * [Metric: `aspnetcore.diagnostics.exceptions`](#metric-aspnetcorediagnosticsexceptions) +- [Rate-limiting](#rate-limiting) + * [Metric: `aspnetcore.rate_limiting.active_request_leases`](#metric-aspnetcorerate_limitingactive_request_leases) + * [Metric: `aspnetcore.rate_limiting.request_lease.duration`](#metric-aspnetcorerate_limitingrequest_leaseduration) + * [Metric: `aspnetcore.rate_limiting.queued_requests`](#metric-aspnetcorerate_limitingqueued_requests) + * [Metric: `aspnetcore.rate_limiting.request.time_in_queue`](#metric-aspnetcorerate_limitingrequesttime_in_queue) + * [Metric: `aspnetcore.rate_limiting.requests`](#metric-aspnetcorerate_limitingrequests) + + + +## Server + +## Routing + +All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter. + +### Metric: `aspnetcore.routing.match_attempts` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.routing.match_attempts` | Counter | `{match_attempt}` | Number of requests that were attempted to be matched to an endpoint. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Routing`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | Required | +| `aspnetcore.routing.is_fallback_route` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | Conditionally Required: if and only if a route was successfully matched. | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. | + +**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +`aspnetcore.routing.match_status` 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 | +|---|---| +| `success` | Match succeeded | +| `failure` | Match failed | + + +## Exception metrics + +Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter. + +### Metric: `aspnetcore.diagnostics.exceptions` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.diagnostics.exceptions` | Counter | `{exception}` | Number of exceptions caught by exception handling middleware. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Diagnostics`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnetcore.diagnostics.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Required | +| `aspnetcore.diagnostics.handler.type` | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | Conditionally Required: [1] | +| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Required | + +**[1]:** if and only if the exception was handled by this handler. + +`aspnetcore.diagnostics.exception.result` MUST be one of the following: + +| Value | Description | +|---|---| +| `handled` | Exception was handled by the exception handling middleware. | +| `unhandled` | Exception was not handled by the exception handling middleware. | +| `skipped` | Exception handling was skipped because the response had started. | +| `aborted` | Exception handling didn't run because the request was aborted. | + + +## Rate-limiting + +All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` meter. + +### Metric: `aspnetcore.rate_limiting.active_request_leases` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.active_request_leases` | UpDownCounter | `{request}` | Number of requests that are currently active on the server that hold a rate limiting lease. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + + +### Metric: `aspnetcore.rate_limiting.request_lease.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.request_lease.duration` | Histogram | `s` | The duration of rate limiting lease held by requests on the server. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + + +### Metric: `aspnetcore.rate_limiting.queued_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.queued_requests` | UpDownCounter | `{request}` | Number of requests that are currently queued, waiting to acquire a rate limiting lease. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + + +### Metric: `aspnetcore.rate_limiting.request.time_in_queue` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.request.time_in_queue` | Histogram | `s` | The time request spent in a queue, waiting to acquire a rate limiting lease. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] | +| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether lease was acquired or contains rejection reason | `acquired`; `request_canceled` | Required | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + +`aspnetcore.rate_limiting.result` 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 | +|---|---| +| `acquired` | Lease was acquired | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | +| `global_limiter` | Lease request was rejected by the global limiter | +| `request_canceled` | Lease request was canceled | + + +### Metric: `aspnetcore.rate_limiting.requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.requests` | Counter | `{request}` | Number of requests that tried to acquire a rate limiting lease. [1] | + +**[1]:** Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. + +Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] | +| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether lease was acquired or contains rejection reason | `acquired`; `request_canceled` | Required | + +**[1]:** if the matched endpoint for the request had a rate-limiting policy. + +`aspnetcore.rate_limiting.result` 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 | +|---|---| +| `acquired` | Lease was acquired | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | +| `global_limiter` | Lease request was rejected by the global limiter | +| `request_canceled` | Lease request was canceled | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md new file mode 100644 index 0000000000..ed8f93a79d --- /dev/null +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -0,0 +1,40 @@ +# Semantic Conventions for DNS metrics emitted by .NET + +**Status**: [Experimental, Feature-freeze][DocumentStatus] + +This document defines semantic conventions for DNS metrics emitted by .NET. + + + +- [DNS metrics](#dns-metrics) + * [Metric: `dns.lookups.duration`](#metric-dnslookupsduration) + + + +## DNS metrics + +### Metric: `dns.lookups.duration` + + +| 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 | + +**[1]:** 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. + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md new file mode 100644 index 0000000000..7ff310a2d4 --- /dev/null +++ b/docs/dotnet/dotnet-http-metrics.md @@ -0,0 +1,260 @@ +# Semantic Conventions for HTTP-relevant metrics emitted by .NET + +**Status**: [Experimental, Feature-freeze][DocumentStatus] + +This document defines semantic conventions for HTTP metrics emitted by .NET components and runtime. + + + +- [HTTP client](#http-client) + * [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) + * [Metric: `http.client.open_connections`](#metric-httpclientopen_connections) + * [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) + * [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue) + * [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) +- [HTTP server](#http-server) + * [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) + * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) + + + +## HTTP client + +All Http client metrics are reported by `System.Net.Http` meter. + +### Metric: `http.client.request.duration` + +Client request duration measures time it takes to receive response headers and does not include time to read response body. + +This metric follows common [http.client.request.duration](../http/http-metrics.md#metric-httpclientrequestduration) definition. + +Notes: + +- Meter name is `System.Net.Http` +- Metric added in .NET 8.0 +- When `error.type` attribute is reported, it contains one of [HTTP Request errors](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs), a full exception type, or a string representation of received status code. +- The [`url.scheme`](../url/url.md) attribute is reported. + +### Metric: `http.client.open_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** Determined by using the first of the following that applies + +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form +- Host identifier of the `Host` header + +**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. + +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). + +**[5]:** When observed from the client side, this SHOULD represent the immediate server peer address. +When observed from the server side, this SHOULD represent the physical server address. + +`http.connection.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | active state. | +| `idle` | idle state. | + + +### Metric: `http.client.connection.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.connection.duration` | Histogram | `s` | The duration of successfully established outbound HTTP connections. [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** Determined by using the first of the following that applies + +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form +- Host identifier of the `Host` header + +**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. + +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). + +**[5]:** When observed from the client side, this SHOULD represent the immediate server peer address. +When observed from the server side, this SHOULD represent the physical server address. + + +### Metric: `http.client.request.time_in_queue` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `1.1`; `2` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. + +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** Determined by using the first of the following that applies + +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form +- Host identifier of the `Host` header + +**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. + +**[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` 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 | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + + +### Metric: `http.client.active_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. [1] | + +**[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `1.1`; `2` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known, it sets the `http.request.method` attribute to `_OTHER`. + +It is not possible at the moment to override the list of known HTTP methods. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** Determined by using the first of the following that applies + +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form +- Host identifier of the `Host` header + +**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. + +**[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` 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 | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + + +## HTTP server + +All HTTP server metrics are reported by `Microsoft.AspNetCore.Hosting` meter. + +### Metric: `http.server.request.duration` + +Measures time to last byte. This metric follows common [http.server.request.duration](../http/http-metrics.md#metric-httpserverrequestduration) definition. + +Notes: + +- Meter name is `Microsoft.AspNetCore.Hosting` +- Metric added in ASP.NET Core 8.0 +- Opt-in `server.address` and `server.port` attributes are not reported +- Additional attributes + + - The `aspnetcore.request.is_unhandled` boolean attribute is reported when the request was **not** handled by the application pipeline. It's skipped otherwise. + - The `exception.type` string attribute is reported if and only if the request ended with an error. It includes full exception type. + +### Metric: `http.server.active_requests` + +Measures the number of HTTP requests that are currently active on the server. This metric follows common [http.server.active_requests](../http/http-metrics.md#metric-httpserveractive_requests) definition. + +Notes: + +- Meter name is `Microsoft.AspNetCore.Hosting` +- Opt-in `server.address` and `server.port` attributes are not reported +- Metric added in ASP.NET Core 8.0 + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md new file mode 100644 index 0000000000..9eec8ccc8c --- /dev/null +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -0,0 +1,366 @@ +# Semantic Conventions for Kestrel web server metrics emitted by .NET + +**Status**: [Experimental, Feature-freeze][DocumentStatus] + +This document defines semantic conventions for Kestrel web server. + + + +- [Kestrel endpoint](#kestrel-endpoint) +- [Metric: `kestrel.active_connections`](#metric-kestrelactive_connections) +- [Metric: `kestrel.connection.duration`](#metric-kestrelconnectionduration) +- [Metric: `kestrel.rejected_connections`](#metric-kestrelrejected_connections) +- [Metric: `kestrel.queued_connections`](#metric-kestrelqueued_connections) +- [Metric: `kestrel.queued_requests`](#metric-kestrelqueued_requests) +- [Metric: `kestrel.upgraded_connections`](#metric-kestrelupgraded_connections) +- [Metric: `kestrel.tls_handshake.duration`](#metric-kestreltls_handshakeduration) +- [Metric: `kestrel.active_tls_handshakes`](#metric-kestrelactive_tls_handshakes) + + + +## Kestrel endpoint + +Kestrel endpoint is represented with [`System.Net.EndPoint`](https://learn.microsoft.com/en-us/dotnet/api/system.net.endpoint) class, +which does not always provide information about server address or port. + +Instrumentation supports `IPEndPoint`, `UnixDomainSocketEndPoint`, and `NamedPipeEndPoint` and sets `server.address`, `server.port` (for IP endpoint), `network.type`, and `network.transport` attributes from corresponding endpoint on Kestrel metrics. + +In case instrumentation does not recognize `EndPoint` implementation, it sets `server.address` attribute to `endpoint.ToString()` value +and `network.transport` value to corresponding `endpoint.AddressFamily` property. + +## Metric: `kestrel.active_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.connection.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `web_sockets` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [2] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [3] | `80`; `8080`; `443` | Recommended | +| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.rejected_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.rejected_connections` | Counter | `{connection}` | Number of connections rejected by the server. [1] | + +**[1]:** Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. +Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.queued_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.queued_connections` | UpDownCounter | `{connection}` | Number of connections that are currently queued and are waiting to start. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.queued_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.queued_requests` | UpDownCounter | `{request}` | Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `web_sockets` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [2] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [3] | `80`; `8080`; `443` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.upgraded_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.upgraded_connections` | UpDownCounter | `{connection}` | Number of connections that are currently upgraded (WebSockets). . [1] | + +**[1]:** The counter only tracks HTTP/1.1 connections. + +Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.tls_handshake.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.tls_handshake.duration` | Histogram | `s` | The duration of TLS handshakes on the server. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | +| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.active_tls_handshakes` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.active_tls_handshakes` | UpDownCounter | `{handshake}` | Number of TLS handshakes that are currently in progress on the server. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md new file mode 100644 index 0000000000..195fedc35d --- /dev/null +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -0,0 +1,80 @@ +# Semantic Conventions for SignalR metrics emitted by ASP.NET Core 8.0 + +**Status**: [Experimental, Feature-freeze][DocumentStatus] + +This document defines semantic conventions for SignalR metrics emitted by .NET components and runtime. + + + +- [Metric: `signalr.server.connection.duration`](#metric-signalrserverconnectionduration) +- [Metric: `signalr.server.active_connections`](#metric-signalrserveractive_connections) + + + +## Metric: `signalr.server.connection.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended | +| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Recommended | + +`signalr.connection.status` MUST be one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`signalr.transport` 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 | +|---|---| +| `server_sent_events` | ServerSentEvents protocol | +| `long_polling` | LongPolling protocol | +| `web_sockets` | WebSockets protocol | + + +## Metric: `signalr.server.active_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. [1] | + +**[1]:** Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended | +| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Recommended | + +`signalr.connection.status` MUST be one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`signalr.transport` 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 | +|---|---| +| `server_sent_events` | ServerSentEvents protocol | +| `long_polling` | LongPolling protocol | +| `web_sockets` | WebSockets protocol | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/model/metrics/dotnet/dotnet-aspnetcore.yaml b/model/metrics/dotnet/dotnet-aspnetcore.yaml new file mode 100644 index 0000000000..dee29b03ad --- /dev/null +++ b/model/metrics/dotnet/dotnet-aspnetcore.yaml @@ -0,0 +1,174 @@ +groups: + - id: aspnetcore + prefix: aspnetcore + type: attribute_group + brief: ASP.NET Core attributes + attributes: + - id: rate_limiting.policy + type: string + brief: Rate limiting policy name. + examples: ["fixed", "sliding", "token"] + requirement_level: + conditionally_required: if the matched endpoint for the request had a rate-limiting policy. + - id: rate_limiting.result + type: + allow_custom_values: true + members: + - id: acquired + value: 'acquired' + brief: "Lease was acquired" + - id: endpoint_limiter + value: 'endpoint_limiter' + brief: "Lease request was rejected by the endpoint limiter" + - id: global_limiter + value: 'global_limiter' + brief: "Lease request was rejected by the global limiter" + - id: request_canceled + value: 'request_canceled' + brief: "Lease request was canceled" + brief: Rate-limiting result, shows whether lease was acquired or contains rejection reason + examples: ["acquired", "request_canceled"] + requirement_level: required + - id: routing.is_fallback_route + type: boolean + brief: A value that indicates whether the matched route is a fallback route. + examples: [true] + requirement_level: + conditionally_required: If and only if a route was successfully matched. + - id: diagnostics.handler.type + type: string + brief: Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) + implementation that handled the exception. + examples: ["Contoso.MyHandler"] + requirement_level: + conditionally_required: if and only if the exception was handled by this handler. + - id: request.is_unhandled + type: boolean + brief: Flag indicating if request was handled by the application pipeline. + examples: [true] + requirement_level: + conditionally_required: if and only if the request was not handled. + + # routing + - id: metric.aspnetcore.routing.match_attempts + type: metric + metric_name: aspnetcore.routing.match_attempts + brief: Number of requests that were attempted to be matched to an endpoint. + instrument: counter + unit: "{match_attempt}" + note: | + Meter name: `Microsoft.AspNetCore.Routing`; Added in: ASP.NET Core 8.0 + attributes: + - ref: http.route + requirement_level: + conditionally_required: if and only if a route was successfully matched. + - ref: aspnetcore.routing.is_fallback_route + requirement_level: + conditionally_required: if and only if a route was successfully matched. + - id: aspnetcore.routing.match_status + type: + allow_custom_values: true + members: + - id: success + value: 'success' + brief: 'Match succeeded' + - id: failure + value: 'failure' + brief: 'Match failed' + requirement_level: required + brief: Match result - success or failure + examples: ["success", "failure"] + + # diagnostics + - id: metric.aspnetcore.diagnostics.exceptions + type: metric + metric_name: aspnetcore.diagnostics.exceptions + brief: Number of exceptions caught by exception handling middleware. + instrument: counter + unit: "{exception}" + note: | + Meter name: `Microsoft.AspNetCore.Diagnostics`; Added in: ASP.NET Core 8.0 + attributes: + - ref: exception.type + brief: The full name of exception type. + examples: ['System.OperationCanceledException', 'Contoso.MyException'] + requirement_level: required + - ref: aspnetcore.diagnostics.handler.type + - id: aspnetcore.diagnostics.exception.result + type: + members: + - id: handled + value: 'handled' + brief: "Exception was handled by the exception handling middleware." + - id: unhandled + value: 'unhandled' + brief: "Exception was not handled by the exception handling middleware." + - id: skipped + value: 'skipped' + brief: "Exception handling was skipped because the response had started." + - id: aborted + value: 'aborted' + brief: "Exception handling didn't run because the request was aborted." + requirement_level: required + brief: ASP.NET Core exception middleware handling result + examples: ["handled", "unhandled"] + + # rate_limiting + - id: metric.aspnetcore.rate_limiting.active_request_leases + type: metric + metric_name: aspnetcore.rate_limiting.active_request_leases + brief: Number of requests that are currently active on the server that hold a rate limiting lease. + instrument: updowncounter + unit: "{request}" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + attributes: + - ref: aspnetcore.rate_limiting.policy + + - id: metric.aspnetcore.rate_limiting.request_lease.duration + type: metric + metric_name: aspnetcore.rate_limiting.request_lease.duration + brief: The duration of rate limiting lease held by requests on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + attributes: + - ref: aspnetcore.rate_limiting.policy + + - id: metric.aspnetcore.rate_limiting.request.time_in_queue + type: metric + metric_name: aspnetcore.rate_limiting.request.time_in_queue + brief: The time request spent in a queue, waiting to acquire a rate limiting lease. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + attributes: + - ref: aspnetcore.rate_limiting.policy + - ref: aspnetcore.rate_limiting.result + + - id: metric.aspnetcore.rate_limiting.queued_requests + type: metric + metric_name: aspnetcore.rate_limiting.queued_requests + brief: Number of requests that are currently queued, waiting to acquire a rate limiting lease. + instrument: updowncounter + unit: "{request}" + note: | + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + attributes: + - ref: aspnetcore.rate_limiting.policy + + - id: metric.aspnetcore.rate_limiting.requests + type: metric + metric_name: aspnetcore.rate_limiting.requests + brief: Number of requests that tried to acquire a rate limiting lease. + instrument: counter + unit: "{request}" + note: | + Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. + + Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 + attributes: + - ref: aspnetcore.rate_limiting.policy + - ref: aspnetcore.rate_limiting.result diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml new file mode 100644 index 0000000000..d3836c9763 --- /dev/null +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -0,0 +1,174 @@ +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. + + - id: metric.dotnet.http.client.open_connections + type: metric + metric_name: http.client.open_connections + brief: "Number of outbound HTTP connections that are currently active or idle on the client" + instrument: updowncounter + unit: "{connection}" + note: | + Meter name: `System.Net.Http`; Added in: .NET 8.0 + attributes: + - id: http.connection.state + type: + members: + - id: active + value: "active" + brief: 'active state.' + - id: idle + value: "idle" + brief: 'idle state.' + brief: State of HTTP connection in the HTTP connection pool. + requirement_level: required + examples: ["active", "idle"] + - ref: url.scheme + examples: ['http', 'https', 'ftp'] + - ref: network.protocol.version + examples: ["1.1", "2"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: | + Determined by using the first of the following that applies + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form + - Host identifier of the `Host` header + - ref: server.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match + URI port identifier, otherwise it MUST match `Host` header port identifier. + - ref: server.socket.address + + - id: metric.dotnet.http.client.connection.duration + type: metric + metric_name: http.client.connection.duration + brief: "The duration of successfully established outbound HTTP connections." + instrument: histogram + unit: "s" + note: | + Meter name: `System.Net.Http`; Added in: .NET 8.0 + attributes: + - ref: url.scheme + examples: ['http', 'https', 'ftp'] + - ref: network.protocol.version + examples: ["1.1", "2"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: | + Determined by using the first of the following that applies + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form + - Host identifier of the `Host` header + - ref: server.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match + URI port identifier, otherwise it MUST match `Host` header port identifier. + - ref: server.socket.address + + - id: metric.dotnet.http.client.active_requests + type: metric + metric_name: http.client.active_requests + brief: "Number of active HTTP requests." + instrument: updowncounter + unit: "{request}" + note: | + Meter name: `System.Net.Http`; Added in: .NET 8.0 + attributes: + - ref: http.request.method + note: | + HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) + and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + + If the HTTP request method is not known, it sets the `http.request.method` attribute to `_OTHER`. + + It is not possible at the moment to override the list of known HTTP methods. + - ref: url.scheme + examples: ['http', 'https', 'ftp'] + - ref: network.protocol.version + examples: ["1.1", "2"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: | + Determined by using the first of the following that applies + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form + - Host identifier of the `Host` header + - ref: server.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match + URI port identifier, otherwise it MUST match `Host` header port identifier. + + - id: metric.dotnet.http.client.request.time_in_queue + type: metric + metric_name: http.client.request.time_in_queue + brief: "The amount of time requests spent on a queue waiting for an available connection." + instrument: histogram + unit: "s" + note: | + Meter name: `System.Net.Http`; Added in: .NET 8.0 + attributes: + - ref: http.request.method + - ref: url.scheme + examples: ['http', 'https', 'ftp'] + - ref: network.protocol.version + examples: ["1.1", "2"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: | + Determined by using the first of the following that applies + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form + - Host identifier of the `Host` header + - ref: server.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match + URI port identifier, otherwise it MUST match `Host` header port identifier. diff --git a/model/metrics/dotnet/dotnet-kestrel.yaml b/model/metrics/dotnet/dotnet-kestrel.yaml new file mode 100644 index 0000000000..3c433ebea8 --- /dev/null +++ b/model/metrics/dotnet/dotnet-kestrel.yaml @@ -0,0 +1,129 @@ +groups: + - id: tls + prefix: tls.protocol + type: attribute_group + brief: TLS attributes + attributes: + - id: version + type: string + brief: TLS protocol version. + examples: ["1.2", "1.3"] + requirement_level: + conditionally_required: if the connection is secured with TLS. + - id: common.kestrel.attributes + type: attribute_group + brief: 'Common kestrel attributes' + attributes: + - ref: server.address + - ref: server.port + - ref: network.type + requirement_level: + recommended: if the transport is `tcp` or `udp` + - ref: network.transport + examples: ['tcp', 'unix'] + + - id: metric.kestrel.active_connections + type: metric + metric_name: kestrel.active_connections + brief: Number of connections that are currently active on the server. + instrument: updowncounter + unit: "{connection}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.connection.duration + type: metric + metric_name: kestrel.connection.duration + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + attributes: + - ref: network.protocol.name + examples: ['http', 'web_sockets'] + - ref: network.protocol.version + examples: ["1.1", "2"] + - ref: tls.protocol.version + - ref: exception.type + brief: The full name of exception type. + requirement_level: + conditionally_required: if and only if an exception was thrown. + examples: ['System.OperationCanceledException', 'Contoso.MyException'] + + - id: metric.kestrel.rejected_connections + type: metric + metric_name: kestrel.rejected_connections + brief: Number of connections rejected by the server. + instrument: counter + unit: "{connection}" + note: | + Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.queued_connections + type: metric + metric_name: kestrel.queued_connections + brief: Number of connections that are currently queued and are waiting to start. + instrument: updowncounter + unit: "{connection}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.queued_requests + type: metric + metric_name: kestrel.queued_requests + brief: Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. + instrument: updowncounter + unit: "{request}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + attributes: + - ref: network.protocol.name + examples: ['http', 'web_sockets'] + - ref: network.protocol.version + examples: ["1.1", "2"] + + - id: metric.kestrel.upgraded_connections + type: metric + metric_name: kestrel.upgraded_connections + brief: Number of connections that are currently upgraded (WebSockets). . + instrument: updowncounter + unit: "{connection}" + note: | + The counter only tracks HTTP/1.1 connections. + + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + + - id: metric.kestrel.tls_handshake.duration + type: metric + metric_name: kestrel.tls_handshake.duration + brief: The duration of TLS handshakes on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes + attributes: + - ref: tls.protocol.version + - ref: exception.type + brief: The full name of exception type. + requirement_level: + conditionally_required: if and only if an exception was thrown. + examples: ['System.OperationCanceledException', 'Contoso.MyException'] + + - id: metric.kestrel.active_tls_handshakes + type: metric + metric_name: kestrel.active_tls_handshakes + brief: Number of TLS handshakes that are currently in progress on the server. + instrument: updowncounter + unit: "{handshake}" + note: | + Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 + extends: common.kestrel.attributes diff --git a/model/metrics/dotnet/dotnet-signalr.yaml b/model/metrics/dotnet/dotnet-signalr.yaml new file mode 100644 index 0000000000..3333669c57 --- /dev/null +++ b/model/metrics/dotnet/dotnet-signalr.yaml @@ -0,0 +1,59 @@ +groups: + - id: signalr.common_attributes + prefix: signalr + type: attribute_group + brief: SignalR attributes + attributes: + - id: connection.status + type: + members: + - id: normal_closure + value: 'normal_closure' + brief: "The connection was closed normally." + - id: timeout + value: 'timeout' + brief: "The connection was closed due to a timeout." + - id: app_shutdown + value: 'app_shutdown' + brief: "The connection was closed because the app is shutting down." + brief: SignalR HTTP connection closure status. + examples: ["app_shutdown", "timeout"] + - id: transport + brief: "[SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md)" + type: + allow_custom_values: true + members: + - id: server_sent_events + value: 'server_sent_events' + brief: "ServerSentEvents protocol" + - id: long_polling + value: 'long_polling' + brief: "LongPolling protocol" + - id: web_sockets + value: 'web_sockets' + brief: "WebSockets protocol" + examples: ["web_sockets", "long_polling"] + + - id: metric.signalr.server.connection.duration + type: metric + metric_name: signalr.server.connection.duration + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + note: | + Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + attributes: + - ref: signalr.connection.status + - ref: signalr.transport + + - id: metric.signalr.server.active_connections + type: metric + metric_name: signalr.server.active_connections + brief: Number of connections that are currently active on the server. + instrument: updowncounter + unit: "{connection}" + note: | + Meter name: `Microsoft.AspNetCore.Http.Connections`; Added in: ASP.NET Core 8.0 + attributes: + - ref: signalr.connection.status + - ref: signalr.transport From fc9d3c297cb0f21e809419fc7e7a2b28b59cf60e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 2 Oct 2023 18:36:51 -0700 Subject: [PATCH 02/19] asp.net core switch to error.type and rebase --- docs/dotnet/dotnet-http-metrics.md | 11 +- docs/dotnet/dotnet-kestrel-metrics.md | 220 +++++++++++++++++------ model/metrics/dotnet/dotnet-kestrel.yaml | 4 +- 3 files changed, 171 insertions(+), 64 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 7ff310a2d4..8de9cc7c46 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -49,7 +49,7 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. | @@ -91,7 +91,7 @@ When observed from the server side, this SHOULD represent the physical server ad | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. | @@ -127,7 +127,7 @@ When observed from the server side, this SHOULD represent the physical server ad | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | @@ -189,7 +189,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | @@ -242,10 +242,9 @@ Notes: - Meter name is `Microsoft.AspNetCore.Hosting` - Metric added in ASP.NET Core 8.0 - Opt-in `server.address` and `server.port` attributes are not reported -- Additional attributes +- Additional attributes: - The `aspnetcore.request.is_unhandled` boolean attribute is reported when the request was **not** handled by the application pipeline. It's skipped otherwise. - - The `exception.type` string attribute is reported if and only if the request ended with an error. It includes full exception type. ### Metric: `http.server.active_requests` diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 9eec8ccc8c..7ff5d58e6b 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -41,15 +41,23 @@ and `network.transport` value to corresponding `endpoint.AddressFamily` property | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. `network.transport` 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. @@ -81,21 +89,51 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `web_sockets` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [2] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [3] | `80`; `8080`; `443` | Recommended | +| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [6] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [7] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[4]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[5]:** The value SHOULD be normalized to lowercase. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`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 does not define a custom value for it. | `network.transport` 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. @@ -128,15 +166,23 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | + +**[1]:** The value SHOULD be normalized to lowercase. -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. `network.transport` 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. @@ -168,15 +214,23 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. `network.transport` 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. @@ -208,19 +262,29 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `web_sockets` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `1.1`; `2` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [2] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [3] | `80`; `8080`; `443` | Recommended | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `http`; `web_sockets` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [6] | `80`; `8080`; `443` | Recommended | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** The value SHOULD be normalized to lowercase. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[4]:** The value SHOULD be normalized to lowercase. + +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. `network.transport` 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. @@ -254,15 +318,23 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. `network.transport` 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. @@ -294,17 +366,45 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | +| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [4] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [5] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[3]:** The value SHOULD be normalized to lowercase. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +`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 does not define a custom value for it. | `network.transport` 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. @@ -336,15 +436,23 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. `network.transport` 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. diff --git a/model/metrics/dotnet/dotnet-kestrel.yaml b/model/metrics/dotnet/dotnet-kestrel.yaml index 3c433ebea8..15e3818b03 100644 --- a/model/metrics/dotnet/dotnet-kestrel.yaml +++ b/model/metrics/dotnet/dotnet-kestrel.yaml @@ -47,7 +47,7 @@ groups: - ref: network.protocol.version examples: ["1.1", "2"] - ref: tls.protocol.version - - ref: exception.type + - ref: error.type brief: The full name of exception type. requirement_level: conditionally_required: if and only if an exception was thrown. @@ -112,7 +112,7 @@ groups: extends: common.kestrel.attributes attributes: - ref: tls.protocol.version - - ref: exception.type + - ref: error.type brief: The full name of exception type. requirement_level: conditionally_required: if and only if an exception was thrown. From 48d2f8a54a2624bf5820bbed0db70c27a9c1b7d3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 12 Oct 2023 16:05:13 -0700 Subject: [PATCH 03/19] update according to .net changes --- docs/dotnet/dotnet-aspnetcore-metrics.md | 26 +++++++++++++++-- docs/dotnet/dotnet-dns-metrics.md | 19 ++++++++++-- docs/dotnet/dotnet-http-metrics.md | 23 ++++++--------- docs/dotnet/dotnet-kestrel-metrics.md | 32 ++++++++++----------- model/metrics/dotnet/dotnet-aspnetcore.yaml | 2 +- model/metrics/dotnet/dotnet-http.yaml | 15 ++++++++-- 6 files changed, 78 insertions(+), 39 deletions(-) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 423ad37fad..c5deeb8ad9 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -39,9 +39,9 @@ All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | Required | | `aspnetcore.routing.is_fallback_route` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | Conditionally Required: if and only if a route was successfully matched. | -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. | +| `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | Required | +| [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. @@ -73,10 +73,24 @@ Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter. |---|---|---|---|---| | `aspnetcore.diagnostics.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Required | | `aspnetcore.diagnostics.handler.type` | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | Conditionally Required: [1] | -| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Required | +| `error.type` | string | The full name of exception type. [2] | `System.OperationCanceledException`; `Contoso.MyException` | Required | **[1]:** if and only if the exception was handled by this handler. +**[2]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. + `aspnetcore.diagnostics.exception.result` MUST be one of the following: | Value | Description | @@ -85,6 +99,12 @@ Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter. | `unhandled` | Exception was not handled by the exception handling middleware. | | `skipped` | Exception handling was skipped because the response had started. | | `aborted` | Exception handling didn't run because the request was aborted. | + +`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 does not define a custom value for it. | ## Rate-limiting diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index ed8f93a79d..3368c19b6a 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -7,13 +7,13 @@ This document defines semantic conventions for DNS metrics emitted by .NET. - [DNS metrics](#dns-metrics) - * [Metric: `dns.lookups.duration`](#metric-dnslookupsduration) + * [Metric: `dns.lookup.duration`](#metric-dnslookupduration) ## DNS metrics -### Metric: `dns.lookups.duration` +### Metric: `dns.lookup.duration` | Name | Instrument Type | Unit (UCUM) | Description | @@ -27,6 +27,7 @@ This document defines semantic conventions for DNS metrics emitted by .NET. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | +| `error.type` | string | One of the resolution errors or the full name of exception type. [2] | `host_not_found`; `no_recovery`; `System.Net.Sockets.SocketException` | Recommended | **[1]:** The name being queried. @@ -35,6 +36,20 @@ 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]:** Following errors code 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) +documentation for more details. + +`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 does not define a custom value for it. | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 8de9cc7c46..0c8b2756e7 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -33,7 +33,6 @@ Notes: - Meter name is `System.Net.Http` - Metric added in .NET 8.0 - When `error.type` attribute is reported, it contains one of [HTTP Request errors](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs), a full exception type, or a string representation of received status code. -- The [`url.scheme`](../url/url.md) attribute is reported. ### Metric: `http.client.open_connections` @@ -49,10 +48,10 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. @@ -67,9 +66,6 @@ Notes: **[4]:** If not default (`80` for `http` scheme, `443` for `https`). -**[5]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - `http.connection.state` MUST be one of the following: | Value | Description | @@ -91,10 +87,10 @@ When observed from the server side, this SHOULD represent the physical server ad | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. @@ -108,9 +104,6 @@ When observed from the server side, this SHOULD represent the physical server ad **[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. **[4]:** If not default (`80` for `http` scheme, `443` for `https`). - -**[5]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. ### Metric: `http.client.request.time_in_queue` @@ -126,9 +119,9 @@ When observed from the server side, this SHOULD represent the physical server ad | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | @@ -188,9 +181,9 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 7ff5d58e6b..5c1fc39738 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -43,8 +43,8 @@ and `network.transport` value to corresponding `endpoint.AddressFamily` property |---|---|---|---|---| | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -94,8 +94,8 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [6] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [7] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [7] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. @@ -168,8 +168,8 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 |---|---|---|---|---| | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -216,8 +216,8 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---|---|---|---| | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -266,8 +266,8 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [6] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -320,8 +320,8 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 |---|---|---|---|---| | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -369,8 +369,8 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [4] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [5] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [5] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. @@ -438,8 +438,8 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---|---|---|---| | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. diff --git a/model/metrics/dotnet/dotnet-aspnetcore.yaml b/model/metrics/dotnet/dotnet-aspnetcore.yaml index dee29b03ad..5b0c9f4fe9 100644 --- a/model/metrics/dotnet/dotnet-aspnetcore.yaml +++ b/model/metrics/dotnet/dotnet-aspnetcore.yaml @@ -89,7 +89,7 @@ groups: note: | Meter name: `Microsoft.AspNetCore.Diagnostics`; Added in: ASP.NET Core 8.0 attributes: - - ref: exception.type + - ref: error.type brief: The full name of exception type. examples: ['System.OperationCanceledException', 'Contoso.MyException'] requirement_level: required diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index d3836c9763..ae7c08323d 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -21,6 +21,17 @@ groups: 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. + note: | + Following errors code 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) + documentation for more details. + examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"] - id: metric.dotnet.http.client.open_connections type: metric @@ -65,7 +76,7 @@ groups: note: > When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - - ref: server.socket.address + - ref: network.peer.address - id: metric.dotnet.http.client.connection.duration type: metric @@ -98,7 +109,7 @@ groups: note: > When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - - ref: server.socket.address + - ref: network.peer.address - id: metric.dotnet.http.client.active_requests type: metric From 64fa6837b5385ddb6bfa610bc8c99281cf3e65ed Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 12 Oct 2023 16:15:59 -0700 Subject: [PATCH 04/19] nits --- docs/dotnet/dotnet-dns-metrics.md | 4 +++- docs/dotnet/dotnet-http-metrics.md | 4 ++-- docs/dotnet/dotnet-kestrel-metrics.md | 4 ++-- model/metrics/dotnet/dotnet-http.yaml | 8 ++++++++ model/metrics/dotnet/dotnet-kestrel.yaml | 4 ++-- 5 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 3368c19b6a..3690ffda85 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -27,7 +27,7 @@ This document defines semantic conventions for DNS metrics emitted by .NET. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | -| `error.type` | string | One of the resolution errors or the full name of exception type. [2] | `host_not_found`; `no_recovery`; `System.Net.Sockets.SocketException` | Recommended | +| `error.type` | string | One of the resolution errors or the full name of exception type. [2] | `host_not_found`; `no_recovery`; `System.Net.Sockets.SocketException` | Conditionally Required: if and only if an error has occurred. | **[1]:** The name being queried. @@ -38,10 +38,12 @@ Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. **[2]:** Following errors code 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) documentation for more details. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 0c8b2756e7..4038ce3b41 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -48,7 +48,7 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.address`](../general/attributes.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | @@ -87,7 +87,7 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.address`](../general/attributes.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 5c1fc39738..67cc44d177 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -89,7 +89,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | +| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended | @@ -366,7 +366,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an exception was thrown. | +| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | | [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index ae7c08323d..f6b9dae9c1 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -23,12 +23,16 @@ groups: \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: | Following errors code 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) documentation for more details. examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"] @@ -77,6 +81,8 @@ groups: When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: network.peer.address + brief: Remote IP address of the socket connection. + examples: ["10.1.2.80"] - id: metric.dotnet.http.client.connection.duration type: metric @@ -110,6 +116,8 @@ groups: When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: network.peer.address + brief: Remote IP address of the socket connection. + examples: ["10.1.2.80"] - id: metric.dotnet.http.client.active_requests type: metric diff --git a/model/metrics/dotnet/dotnet-kestrel.yaml b/model/metrics/dotnet/dotnet-kestrel.yaml index 15e3818b03..1f99501623 100644 --- a/model/metrics/dotnet/dotnet-kestrel.yaml +++ b/model/metrics/dotnet/dotnet-kestrel.yaml @@ -50,7 +50,7 @@ groups: - ref: error.type brief: The full name of exception type. requirement_level: - conditionally_required: if and only if an exception was thrown. + conditionally_required: if and only if an error has occurred. examples: ['System.OperationCanceledException', 'Contoso.MyException'] - id: metric.kestrel.rejected_connections @@ -115,7 +115,7 @@ groups: - ref: error.type brief: The full name of exception type. requirement_level: - conditionally_required: if and only if an exception was thrown. + conditionally_required: if and only if an error has occurred. examples: ['System.OperationCanceledException', 'Contoso.MyException'] - id: metric.kestrel.active_tls_handshakes From e704a37fe20ce93c217e863aa9b22e2d9647411b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 13 Oct 2023 11:58:42 -0700 Subject: [PATCH 05/19] rebase and regen md --- docs/dotnet/dotnet-aspnetcore-metrics.md | 2 +- docs/dotnet/dotnet-kestrel-metrics.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index c5deeb8ad9..350788df80 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -87,7 +87,7 @@ additional filters are applied. If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. -If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 67cc44d177..7acce90f77 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -108,7 +108,7 @@ additional filters are applied. If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. -If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. @@ -383,7 +383,7 @@ additional filters are applied. If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. -If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. From 1981c8a1345269dfe1e4d85737c92c74c78f6403 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 16 Oct 2023 15:52:37 -0700 Subject: [PATCH 06/19] review: part1 --- docs/dotnet/README.md | 4 ++-- docs/dotnet/dotnet-aspnetcore-metrics.md | 19 +++++++++++-------- docs/dotnet/dotnet-dns-metrics.md | 13 ++++--------- docs/dotnet/dotnet-http-metrics.md | 18 +++++++++--------- docs/dotnet/dotnet-kestrel-metrics.md | 10 ++++------ docs/dotnet/dotnet-signalr-metrics.md | 2 +- model/metrics/dotnet/dotnet-aspnetcore.yaml | 9 ++++++--- model/metrics/dotnet/dotnet-http.yaml | 8 ++++---- 8 files changed, 41 insertions(+), 42 deletions(-) diff --git a/docs/dotnet/README.md b/docs/dotnet/README.md index 9ede79f11f..56bd74e97b 100644 --- a/docs/dotnet/README.md +++ b/docs/dotnet/README.md @@ -9,9 +9,9 @@ path_base_for_github_subdir: **Status**: [Experimental, Feature-freeze][DocumentStatus] -This document documents semantic conventions for metrics emitted by .NET runtime and individual components in .NET ecosystem. +This article documents semantic conventions for metrics emitted by the .NET runtime and individual components in the .NET ecosystem. -Following metrics are currently supported: +The following metrics are currently supported: * [ASP.NET Core](dotnet-aspnetcore-metrics.md): Semantic Conventions for ASP.NET Core routing, exceptions, and rate-limiting *metrics*. * [DNS](dotnet-dns-metrics.md): Semantic Conventions for client-side DNS lookups associated with *metrics*. diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 350788df80..7a3f2281b2 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -2,7 +2,7 @@ **Status**: [Experimental, Feature-freeze][DocumentStatus] -This document defines semantic conventions for ASP.NET Core metrics. +This article defines semantic conventions for ASP.NET Core metrics. @@ -24,7 +24,7 @@ This document defines semantic conventions for ASP.NET Core metrics. ## Routing -All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter. +All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter. ### Metric: `aspnetcore.routing.match_attempts` @@ -56,7 +56,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin ## Exception metrics -Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter. +Metrics reported by the `Microsoft.AspNetCore.Diagnostics` meter. ### Metric: `aspnetcore.diagnostics.exceptions` @@ -109,7 +109,7 @@ all errors, regardless of whether they are defined within the domain-specific se ## Rate-limiting -All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` meter. +All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting` meter. ### Metric: `aspnetcore.rate_limiting.active_request_leases` @@ -170,7 +170,7 @@ All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` me | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `aspnetcore.rate_limiting.request.time_in_queue` | Histogram | `s` | The time request spent in a queue, waiting to acquire a rate limiting lease. [1] | +| `aspnetcore.rate_limiting.request.time_in_queue` | Histogram | `s` | The time the request spent in a queue waiting to acquire a rate limiting lease. [1] | **[1]:** Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 @@ -179,7 +179,7 @@ All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` me | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] | -| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether lease was acquired or contains rejection reason | `acquired`; `request_canceled` | Required | +| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | Required | **[1]:** if the matched endpoint for the request had a rate-limiting policy. @@ -200,7 +200,10 @@ All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` me | -------- | --------------- | ----------- | -------------- | | `aspnetcore.rate_limiting.requests` | Counter | `{request}` | Number of requests that tried to acquire a rate limiting lease. [1] | -**[1]:** Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. +**[1]:** Requests could be: + + * rejected by global or endpoint rate limiting policies + * canceled while waiting for the lease. Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 @@ -209,7 +212,7 @@ Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] | -| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether lease was acquired or contains rejection reason | `acquired`; `request_canceled` | Required | +| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | Required | **[1]:** if the matched endpoint for the request had a rate-limiting policy. diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 3690ffda85..4d88e76cbf 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -2,7 +2,7 @@ **Status**: [Experimental, Feature-freeze][DocumentStatus] -This document defines semantic conventions for DNS metrics emitted by .NET. +This article defines semantic conventions for DNS metrics emitted by .NET. @@ -30,14 +30,9 @@ This document defines semantic conventions for DNS metrics emitted by .NET. | `error.type` | string | One of the resolution errors or the full name of exception type. [2] | `host_not_found`; `no_recovery`; `System.Net.Sockets.SocketException` | Conditionally Required: if and only if an error has occurred. | **[1]:** 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. -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]:** Following errors code are reported: +**[2]:** The following errors codes are reported: - "host_not_found" - "try_again" @@ -45,7 +40,7 @@ Tabs, carriage returns, and line feeds should be converted to \t, \r, and - "no_recovery" See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) -documentation for more details. +for more details. `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. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 4038ce3b41..96c5f2de65 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -2,7 +2,7 @@ **Status**: [Experimental, Feature-freeze][DocumentStatus] -This document defines semantic conventions for HTTP metrics emitted by .NET components and runtime. +This article defines semantic conventions for HTTP metrics emitted by .NET components and runtime. @@ -20,19 +20,19 @@ This document defines semantic conventions for HTTP metrics emitted by .NET comp ## HTTP client -All Http client metrics are reported by `System.Net.Http` meter. +All Http client metrics are reported by the `System.Net.Http` meter. ### Metric: `http.client.request.duration` -Client request duration measures time it takes to receive response headers and does not include time to read response body. +Client request duration measures the time it takes to receive response headers and doesn't include time to read the response body. -This metric follows common [http.client.request.duration](../http/http-metrics.md#metric-httpclientrequestduration) definition. +This metric follows the common [http.client.request.duration](../http/http-metrics.md#metric-httpclientrequestduration) definition. Notes: - Meter name is `System.Net.Http` - Metric added in .NET 8.0 -- When `error.type` attribute is reported, it contains one of [HTTP Request errors](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs), a full exception type, or a string representation of received status code. +- When the `error.type` attribute is reported, it contains one of [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror), a full exception type, or a string representation of received status code. ### Metric: `http.client.open_connections` @@ -47,7 +47,7 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | +| `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | | [`network.peer.address`](../general/attributes.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | @@ -224,11 +224,11 @@ It is not possible at the moment to override the list of known HTTP methods. ## HTTP server -All HTTP server metrics are reported by `Microsoft.AspNetCore.Hosting` meter. +All HTTP server metrics are reported by the `Microsoft.AspNetCore.Hosting` meter. ### Metric: `http.server.request.duration` -Measures time to last byte. This metric follows common [http.server.request.duration](../http/http-metrics.md#metric-httpserverrequestduration) definition. +Measures time to last byte. This metric follows the common [http.server.request.duration](../http/http-metrics.md#metric-httpserverrequestduration) definition. Notes: @@ -241,7 +241,7 @@ Notes: ### Metric: `http.server.active_requests` -Measures the number of HTTP requests that are currently active on the server. This metric follows common [http.server.active_requests](../http/http-metrics.md#metric-httpserveractive_requests) definition. +Measures the number of HTTP requests that are currently active on the server. This metric follows the common [http.server.active_requests](../http/http-metrics.md#metric-httpserveractive_requests) definition. Notes: diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 7acce90f77..34decf9186 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -2,7 +2,7 @@ **Status**: [Experimental, Feature-freeze][DocumentStatus] -This document defines semantic conventions for Kestrel web server. +This article defines semantic conventions for Kestrel web server. @@ -20,13 +20,11 @@ This document defines semantic conventions for Kestrel web server. ## Kestrel endpoint -Kestrel endpoint is represented with [`System.Net.EndPoint`](https://learn.microsoft.com/en-us/dotnet/api/system.net.endpoint) class, -which does not always provide information about server address or port. +Kestrel endpoint is represented with [`System.Net.EndPoint`](https://learn.microsoft.com/dotnet/api/system.net.endpoint) class, which does not always provide information about server address or port. -Instrumentation supports `IPEndPoint`, `UnixDomainSocketEndPoint`, and `NamedPipeEndPoint` and sets `server.address`, `server.port` (for IP endpoint), `network.type`, and `network.transport` attributes from corresponding endpoint on Kestrel metrics. +Instrumentation supports `IPEndPoint`, `UnixDomainSocketEndPoint`, and `NamedPipeEndPoint` and sets the `server.address`, `server.port` (for IP endpoint), `network.type`, and `network.transport` attributes from the corresponding endpoint on Kestrel metrics. -In case instrumentation does not recognize `EndPoint` implementation, it sets `server.address` attribute to `endpoint.ToString()` value -and `network.transport` value to corresponding `endpoint.AddressFamily` property. +In case instrumentation does not recognize `EndPoint` implementation, it sets the `server.address` attribute to `endpoint.ToString()` value and `network.transport` value to corresponding `endpoint.AddressFamily` property. ## Metric: `kestrel.active_connections` diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index 195fedc35d..3acce6497a 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -2,7 +2,7 @@ **Status**: [Experimental, Feature-freeze][DocumentStatus] -This document defines semantic conventions for SignalR metrics emitted by .NET components and runtime. +This article defines semantic conventions for SignalR metrics emitted by .NET components and runtime. diff --git a/model/metrics/dotnet/dotnet-aspnetcore.yaml b/model/metrics/dotnet/dotnet-aspnetcore.yaml index 5b0c9f4fe9..9e40a44b11 100644 --- a/model/metrics/dotnet/dotnet-aspnetcore.yaml +++ b/model/metrics/dotnet/dotnet-aspnetcore.yaml @@ -26,7 +26,7 @@ groups: - id: request_canceled value: 'request_canceled' brief: "Lease request was canceled" - brief: Rate-limiting result, shows whether lease was acquired or contains rejection reason + brief: Rate-limiting result, shows whether the lease was acquired or contains a rejection reason examples: ["acquired", "request_canceled"] requirement_level: required - id: routing.is_fallback_route @@ -139,7 +139,7 @@ groups: - id: metric.aspnetcore.rate_limiting.request.time_in_queue type: metric metric_name: aspnetcore.rate_limiting.request.time_in_queue - brief: The time request spent in a queue, waiting to acquire a rate limiting lease. + brief: The time the request spent in a queue waiting to acquire a rate limiting lease. instrument: histogram unit: "s" note: | @@ -166,7 +166,10 @@ groups: instrument: counter unit: "{request}" note: | - Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. + Requests could be: + + * rejected by global or endpoint rate limiting policies + * canceled while waiting for the lease. Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 attributes: diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index f6b9dae9c1..702000f06a 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -13,7 +13,7 @@ groups: brief: The name being queried. requirement_level: required examples: ["www.example.com", "dot.net"] - note: | + note: > The name being queried. If the name field contains non-printable @@ -26,7 +26,7 @@ groups: requirement_level: conditionally_required: if and only if an error has occurred. note: | - Following errors code are reported: + The following errors codes are reported: - "host_not_found" - "try_again" @@ -34,7 +34,7 @@ groups: - "no_recovery" See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) - documentation for more details. + for more details. examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"] - id: metric.dotnet.http.client.open_connections @@ -55,7 +55,7 @@ groups: - id: idle value: "idle" brief: 'idle state.' - brief: State of HTTP connection in the HTTP connection pool. + brief: State of the HTTP connection in the HTTP connection pool. requirement_level: required examples: ["active", "idle"] - ref: url.scheme From b6b0dd30b614f715339edc014148c0bd12f4b3ae Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 16 Oct 2023 16:41:52 -0700 Subject: [PATCH 07/19] review: part2 and unify client attrs --- docs/dotnet/dotnet-http-metrics.md | 80 ++++++-------- model/metrics/dotnet/dotnet-http.yaml | 151 ++++++++------------------ 2 files changed, 79 insertions(+), 152 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 96c5f2de65..aba27d1959 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -32,7 +32,7 @@ Notes: - Meter name is `System.Net.Http` - Metric added in .NET 8.0 -- When the `error.type` attribute is reported, it contains one of [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror), a full exception type, or a string representation of received status code. +- When the `error.type` attribute is reported, it contains one of [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror) in snake_case, a full exception type, or a string representation of received status code. ### Metric: `http.client.open_connections` @@ -50,19 +50,18 @@ Notes: | `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | | [`network.peer.address`](../general/attributes.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[2]:** Determined by using the first of the following that applies +**[2]:** Determined by using the first of the following that applies: -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. +- Host identifier of the `Host` header. -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. **[4]:** If not default (`80` for `http` scheme, `443` for `https`). @@ -89,19 +88,18 @@ Notes: |---|---|---|---|---| | [`network.peer.address`](../general/attributes.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[2]:** Determined by using the first of the following that applies +**[2]:** Determined by using the first of the following that applies: -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. +- Host identifier of the `Host` header. -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. **[4]:** If not default (`80` for `http` scheme, `443` for `https`). @@ -121,34 +119,22 @@ Notes: |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. -By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) -and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. - -If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override -the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named -OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods -(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). - -HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. -Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. -Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. +It's not possible at the moment to override the list of known HTTP methods. **[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Determined by using the first of the following that applies +**[3]:** Determined by using the first of the following that applies: -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. +- Host identifier of the `Host` header. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. **[5]:** If not default (`80` for `http` scheme, `443` for `https`). @@ -183,26 +169,22 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) -and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - -If the HTTP request method is not known, it sets the `http.request.method` attribute to `_OTHER`. - -It is not possible at the moment to override the list of known HTTP methods. +**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. +It's not possible at the moment to override the list of known HTTP methods. **[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Determined by using the first of the following that applies +**[3]:** Determined by using the first of the following that applies: -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. +- Host identifier of the `Host` header. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. **[5]:** If not default (`80` for `http` scheme, `443` for `https`). diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index 702000f06a..112bc6fd16 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -37,14 +37,55 @@ groups: for more details. examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"] + - id: dotnet.http.client.connection.attributes + type: attribute_group + brief: "Common HTTP client attributes" + attributes: + - ref: url.scheme + examples: ['http', 'https', 'ftp'] + - ref: network.protocol.version + examples: ["1.1", "2"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. + note: | + Determined by using the first of the following that applies: + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. + - Host identifier of the `Host` header. + - ref: server.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match + the URI port identifier; otherwise, it MUST match the `Host` header port identifier. + + - id: dotnet.http.client.request.attributes + type: attribute_group + brief: "Common HTTP client attributes" + extends: dotnet.http.client.connection.attributes + attributes: + - ref: http.request.method + note: > + HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) + and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + + If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. + + It's not possible at the moment to override the list of known HTTP methods. + - id: metric.dotnet.http.client.open_connections type: metric metric_name: http.client.open_connections brief: "Number of outbound HTTP connections that are currently active or idle on the client" instrument: updowncounter unit: "{connection}" - note: | + note: > Meter name: `System.Net.Http`; Added in: .NET 8.0 + extends: dotnet.http.client.connection.attributes attributes: - id: http.connection.state type: @@ -58,28 +99,6 @@ groups: brief: State of the HTTP connection in the HTTP connection pool. requirement_level: required examples: ["active", "idle"] - - ref: url.scheme - examples: ['http', 'https', 'ftp'] - - ref: network.protocol.version - examples: ["1.1", "2"] - - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - ref: server.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: network.peer.address brief: Remote IP address of the socket connection. examples: ["10.1.2.80"] @@ -90,31 +109,10 @@ groups: brief: "The duration of successfully established outbound HTTP connections." instrument: histogram unit: "s" - note: | + note: > Meter name: `System.Net.Http`; Added in: .NET 8.0 + extends: dotnet.http.client.connection.attributes attributes: - - ref: url.scheme - examples: ['http', 'https', 'ftp'] - - ref: network.protocol.version - examples: ["1.1", "2"] - - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - ref: server.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: network.peer.address brief: Remote IP address of the socket connection. examples: ["10.1.2.80"] @@ -125,39 +123,9 @@ groups: brief: "Number of active HTTP requests." instrument: updowncounter unit: "{request}" - note: | + note: > Meter name: `System.Net.Http`; Added in: .NET 8.0 - attributes: - - ref: http.request.method - note: | - HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) - and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - - If the HTTP request method is not known, it sets the `http.request.method` attribute to `_OTHER`. - - It is not possible at the moment to override the list of known HTTP methods. - - ref: url.scheme - examples: ['http', 'https', 'ftp'] - - ref: network.protocol.version - examples: ["1.1", "2"] - - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - ref: server.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. + extends: dotnet.http.client.request.attributes - id: metric.dotnet.http.client.request.time_in_queue type: metric @@ -165,29 +133,6 @@ groups: brief: "The amount of time requests spent on a queue waiting for an available connection." instrument: histogram unit: "s" - note: | + note: > Meter name: `System.Net.Http`; Added in: .NET 8.0 - attributes: - - ref: http.request.method - - ref: url.scheme - examples: ['http', 'https', 'ftp'] - - ref: network.protocol.version - examples: ["1.1", "2"] - - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - ref: server.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. + extends: dotnet.http.client.request.attributes From ebb2b48a667d8ff8680f5699a8c09dc14305f191 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 16 Oct 2023 17:02:47 -0700 Subject: [PATCH 08/19] review: part3 --- docs/dotnet/dotnet-http-metrics.md | 10 ++++---- docs/dotnet/dotnet-kestrel-metrics.md | 30 +++--------------------- model/metrics/dotnet/dotnet-http.yaml | 4 ++-- model/metrics/dotnet/dotnet-kestrel.yaml | 4 +++- 4 files changed, 13 insertions(+), 35 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index aba27d1959..e6a09628a7 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -63,7 +63,7 @@ Notes: **[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). `http.connection.state` MUST be one of the following: @@ -78,7 +78,7 @@ Notes: | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.client.connection.duration` | Histogram | `s` | The duration of successfully established outbound HTTP connections. [1] | +| `http.client.connection.duration` | Histogram | `s` | The duration of the successfully established outbound HTTP connections. [1] | **[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 @@ -101,7 +101,7 @@ Notes: **[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). ### Metric: `http.client.request.time_in_queue` @@ -136,7 +136,7 @@ It's not possible at the moment to override the list of known HTTP methods. **[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[5]:** If not the default (`80` for `http` scheme, `443` for `https`). `http.request.method` 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. @@ -186,7 +186,7 @@ It's not possible at the moment to override the list of known HTTP methods. **[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[5]:** If not the default (`80` for `http` scheme, `443` for `https`). `http.request.method` 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. diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 34decf9186..d8d70366b2 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -96,19 +96,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | [`server.port`](../general/attributes.md) | int | Server port number. [7] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | -**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. -Instrumentations SHOULD document the list of errors they report. - -The cardinality of `error.type` within one instrumentation library SHOULD be low, but -telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.type` to have high cardinality at query time, when no -additional filters are applied. - -If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. - -If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), -it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture -all errors, regardless of whether they are defined within the domain-specific set or not. +**[1]:** Captures the exception type when a connection fails. **[2]:** The value SHOULD be normalized to lowercase. @@ -157,7 +145,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | -------- | --------------- | ----------- | -------------- | | `kestrel.rejected_connections` | Counter | `{connection}` | Number of connections rejected by the server. [1] | -**[1]:** Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. +**[1]:** Connections are rejected when the currently active count exceeds the value configured with `MaxConcurrentConnections`. Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 @@ -371,19 +359,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | [`server.port`](../general/attributes.md) | int | Server port number. [5] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | -**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. -Instrumentations SHOULD document the list of errors they report. - -The cardinality of `error.type` within one instrumentation library SHOULD be low, but -telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.type` to have high cardinality at query time, when no -additional filters are applied. - -If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. - -If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), -it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture -all errors, regardless of whether they are defined within the domain-specific set or not. +**[1]:** Captures the exception type when a TLS handshake fails. **[2]:** The value SHOULD be normalized to lowercase. diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index 112bc6fd16..b0b8572f3a 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -56,7 +56,7 @@ groups: - Host identifier of the `Host` header. - ref: server.port requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. note: > @@ -106,7 +106,7 @@ groups: - id: metric.dotnet.http.client.connection.duration type: metric metric_name: http.client.connection.duration - brief: "The duration of successfully established outbound HTTP connections." + brief: "The duration of the successfully established outbound HTTP connections." instrument: histogram unit: "s" note: > diff --git a/model/metrics/dotnet/dotnet-kestrel.yaml b/model/metrics/dotnet/dotnet-kestrel.yaml index 1f99501623..13e5c33f71 100644 --- a/model/metrics/dotnet/dotnet-kestrel.yaml +++ b/model/metrics/dotnet/dotnet-kestrel.yaml @@ -51,6 +51,7 @@ groups: brief: The full name of exception type. 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'] - id: metric.kestrel.rejected_connections @@ -60,7 +61,7 @@ groups: instrument: counter unit: "{connection}" note: | - Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. + Connections are rejected when the currently active count exceeds the value configured with `MaxConcurrentConnections`. Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 extends: common.kestrel.attributes @@ -114,6 +115,7 @@ groups: - ref: tls.protocol.version - ref: error.type brief: The full name of exception type. + note: "Captures the exception type when a TLS handshake fails." requirement_level: conditionally_required: if and only if an error has occurred. examples: ['System.OperationCanceledException', 'Contoso.MyException'] From 29754ab02b1e9a1aaa545960638f22595391be52 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 16 Oct 2023 18:50:08 -0700 Subject: [PATCH 09/19] lint --- docs/dotnet/dotnet-aspnetcore-metrics.md | 4 ++-- model/metrics/dotnet/dotnet-aspnetcore.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 7a3f2281b2..b1a2431c85 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -202,8 +202,8 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting **[1]:** Requests could be: - * rejected by global or endpoint rate limiting policies - * canceled while waiting for the lease. +* Rejected by global or endpoint rate limiting policies +* Canceled while waiting for the lease. Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 diff --git a/model/metrics/dotnet/dotnet-aspnetcore.yaml b/model/metrics/dotnet/dotnet-aspnetcore.yaml index 9e40a44b11..b25bc93808 100644 --- a/model/metrics/dotnet/dotnet-aspnetcore.yaml +++ b/model/metrics/dotnet/dotnet-aspnetcore.yaml @@ -168,8 +168,8 @@ groups: note: | Requests could be: - * rejected by global or endpoint rate limiting policies - * canceled while waiting for the lease. + * Rejected by global or endpoint rate limiting policies + * Canceled while waiting for the lease. Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 attributes: From 30ae552c95002f6bb8f6522b5764a5e07df0c2a3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 19 Oct 2023 17:33:29 -0700 Subject: [PATCH 10/19] Add missing hugo titles and minor updates --- docs/dotnet/dotnet-aspnetcore-metrics.md | 10 +++++++--- docs/dotnet/dotnet-dns-metrics.md | 4 ++++ docs/dotnet/dotnet-http-metrics.md | 6 +++++- docs/dotnet/dotnet-kestrel-metrics.md | 6 +++++- docs/dotnet/dotnet-signalr-metrics.md | 6 +++++- 5 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index b1a2431c85..c77c57db97 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for ASP.NET Core metrics **Status**: [Experimental, Feature-freeze][DocumentStatus] @@ -9,7 +13,7 @@ This article defines semantic conventions for ASP.NET Core metrics. - [Server](#server) - [Routing](#routing) * [Metric: `aspnetcore.routing.match_attempts`](#metric-aspnetcoreroutingmatch_attempts) -- [Exception metrics](#exception-metrics) +- [Exceptions](#exceptions) * [Metric: `aspnetcore.diagnostics.exceptions`](#metric-aspnetcorediagnosticsexceptions) - [Rate-limiting](#rate-limiting) * [Metric: `aspnetcore.rate_limiting.active_request_leases`](#metric-aspnetcorerate_limitingactive_request_leases) @@ -54,9 +58,9 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `failure` | Match failed | -## Exception metrics +## Exceptions -Metrics reported by the `Microsoft.AspNetCore.Diagnostics` meter. +Exceptions Metric is reported by the `Microsoft.AspNetCore.Diagnostics` meter. ### Metric: `aspnetcore.diagnostics.exceptions` diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 4d88e76cbf..85ff431c43 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for DNS metrics emitted by .NET **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index e6a09628a7..eb93e52392 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -1,4 +1,8 @@ -# Semantic Conventions for HTTP-relevant metrics emitted by .NET + + +# Semantic Conventions for HTTP client and server metrics emitted by .NET **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index d8d70366b2..9fb486512c 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -1,4 +1,8 @@ -# Semantic Conventions for Kestrel web server metrics emitted by .NET + + +# Semantic Conventions for Kestrel web server metrics **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index 3acce6497a..6062a54b83 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -1,4 +1,8 @@ -# Semantic Conventions for SignalR metrics emitted by ASP.NET Core 8.0 + + +# Semantic Conventions for SignalR server metrics **Status**: [Experimental, Feature-freeze][DocumentStatus] From 8a47d0339149baf7bf52a743958d0ae1d6940acb Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 19 Oct 2023 17:36:27 -0700 Subject: [PATCH 11/19] regenerate md --- docs/dotnet/dotnet-aspnetcore-metrics.md | 16 +-- docs/dotnet/dotnet-dns-metrics.md | 2 +- docs/dotnet/dotnet-http-metrics.md | 28 ++--- docs/dotnet/dotnet-kestrel-metrics.md | 136 +++++++++++------------ 4 files changed, 88 insertions(+), 94 deletions(-) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index c77c57db97..d59ad80381 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -45,7 +45,7 @@ All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter. |---|---|---|---|---| | `aspnetcore.routing.is_fallback_route` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | Conditionally Required: if and only if a route was successfully matched. | | `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | Required | -| [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. | +| [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. @@ -84,16 +84,18 @@ Exceptions Metric is reported by the `Microsoft.AspNetCore.Diagnostics` meter. **[2]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. -The cardinality of `error.type` within one instrumentation library SHOULD be low, but -telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.type` to have high cardinality at query time, when no +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no additional filters are applied. If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), -it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture -all errors, regardless of whether they are defined within the domain-specific set or not. +it's RECOMMENDED to: + +* Use a domain-specific attribute +* Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. `aspnetcore.diagnostics.exception.result` MUST be one of the following: @@ -108,7 +110,7 @@ all errors, regardless of whether they are defined within the domain-specific se | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ## Rate-limiting diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 85ff431c43..dc00fce2c7 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -50,7 +50,7 @@ for more details. | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_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.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index eb93e52392..fd112c2cc5 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -52,13 +52,13 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | -| [`network.peer.address`](../general/attributes.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[2]:** Determined by using the first of the following that applies: @@ -90,13 +90,13 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.peer.address`](../general/attributes.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[2]:** Determined by using the first of the following that applies: @@ -122,16 +122,16 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[3]:** Determined by using the first of the following that applies: @@ -172,16 +172,16 @@ It's not possible at the moment to override the list of known HTTP methods. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[3]:** Determined by using the first of the following that applies: diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 9fb486512c..5a47d6e985 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -43,23 +43,22 @@ In case instrumentation does not recognize `EndPoint` implementation, it sets th | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `network.transport` 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. @@ -67,7 +66,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. @@ -92,11 +91,11 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [7] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | @@ -104,26 +103,25 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[2]:** The value SHOULD be normalized to lowercase. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[4]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[5]:** The value SHOULD be normalized to lowercase. -**[6]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `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 does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `network.transport` 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. @@ -131,7 +129,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. @@ -156,23 +154,22 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `network.transport` 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. @@ -180,7 +177,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. @@ -204,23 +201,22 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `network.transport` 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. @@ -228,7 +224,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. @@ -252,29 +248,28 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `http`; `web_sockets` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `http`; `web_sockets` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[3]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[4]:** The value SHOULD be normalized to lowercase. -**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `network.transport` 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. @@ -282,7 +277,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. @@ -308,23 +303,22 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `network.transport` 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. @@ -332,7 +326,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. @@ -357,9 +351,9 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [5] | `80`; `8080`; `443` | Recommended | | `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | @@ -368,21 +362,20 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[2]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[3]:** The value SHOULD be normalized to lowercase. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `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 does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `network.transport` 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. @@ -390,7 +383,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. @@ -414,23 +407,22 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | +| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `network.transport` 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. @@ -438,7 +430,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `network.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. From 662efb83b6cfa444f572808e0cadd21afb7bdbd4 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Nov 2023 18:51:23 -0800 Subject: [PATCH 12/19] feedback --- docs/dotnet/dotnet-aspnetcore-metrics.md | 10 ++++- docs/dotnet/dotnet-dns-metrics.md | 6 ++- docs/dotnet/dotnet-http-metrics.md | 38 +++++++++++-------- docs/dotnet/dotnet-kestrel-metrics.md | 48 ++++++++++++++---------- docs/dotnet/dotnet-signalr-metrics.md | 4 ++ model/metrics/dotnet/dotnet-http.yaml | 13 ++++--- model/metrics/dotnet/dotnet-kestrel.yaml | 11 ------ 7 files changed, 76 insertions(+), 54 deletions(-) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index d59ad80381..41808fd7d7 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -77,7 +77,7 @@ Exceptions Metric is reported by the `Microsoft.AspNetCore.Diagnostics` meter. |---|---|---|---|---| | `aspnetcore.diagnostics.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Required | | `aspnetcore.diagnostics.handler.type` | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | Conditionally Required: [1] | -| `error.type` | string | The full name of exception type. [2] | `System.OperationCanceledException`; `Contoso.MyException` | Required | +| [`error.type`](../attributes-registry/error.md) | string | The full name of exception type. [2] | `System.OperationCanceledException`; `Contoso.MyException` | Required | **[1]:** if and only if the exception was handled by this handler. @@ -137,6 +137,10 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting ### Metric: `aspnetcore.rate_limiting.request_lease.duration` +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 | | -------- | --------------- | ----------- | -------------- | @@ -173,6 +177,10 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting ### Metric: `aspnetcore.rate_limiting.request.time_in_queue` +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 | | -------- | --------------- | ----------- | -------------- | diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index dc00fce2c7..a76c3a77bf 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -19,6 +19,10 @@ This article defines semantic conventions for DNS metrics emitted by .NET. ### Metric: `dns.lookup.duration` +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 | | -------- | --------------- | ----------- | -------------- | @@ -31,7 +35,7 @@ This article defines semantic conventions for DNS metrics emitted by .NET. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | -| `error.type` | string | One of the resolution errors or the full name of exception type. [2] | `host_not_found`; `no_recovery`; `System.Net.Sockets.SocketException` | Conditionally Required: if and only if an error has occurred. | +| [`error.type`](../attributes-registry/error.md) | string | One of the resolution errors or the full name of exception type. [2] | `host_not_found`; `no_recovery`; `System.Net.Sockets.SocketException` | Conditionally Required: if and only if an error has occurred. | **[1]:** 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. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index fd112c2cc5..647f435743 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -43,7 +43,7 @@ Notes: | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client [1] | +| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client. [1] | **[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 @@ -54,8 +54,8 @@ Notes: | `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | | [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. @@ -79,6 +79,10 @@ Notes: ### Metric: `http.client.connection.duration` +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.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -90,10 +94,10 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. @@ -110,6 +114,11 @@ Notes: ### Metric: `http.client.request.time_in_queue` +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 | | -------- | --------------- | ----------- | -------------- | @@ -123,8 +132,8 @@ Notes: |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -172,25 +181,22 @@ It's not possible at the moment to override the list of known HTTP methods. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[3]:** Determined by using the first of the following that applies: +**[2]:** Determined by using the first of the following that applies: - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Host identifier of the `Host` header. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. +**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. -**[5]:** If not the default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). `http.request.method` 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. diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 5a47d6e985..8205cda2d5 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -45,8 +45,8 @@ In case instrumentation does not recognize `EndPoint` implementation, it sets th |---|---|---|---|---| | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -79,6 +79,10 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ## Metric: `kestrel.connection.duration` +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.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | @@ -90,14 +94,14 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. | +| [`error.type`](../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. | | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended | | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [7] | `80`; `8080`; `443` | Recommended | -| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | Recommended | +| [`tls.protocol.version`](../attributes-registry/tls.md) | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | Recommended | **[1]:** Captures the exception type when a connection fails. @@ -156,8 +160,8 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 |---|---|---|---|---| | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -203,8 +207,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345. |---|---|---|---|---| | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -252,8 +256,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -305,8 +309,8 @@ Meter name: `Microsoft.AspNetCore.Server.Kestrel`; Added in: ASP.NET Core 8.0 |---|---|---|---|---| | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. @@ -339,6 +343,10 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ## Metric: `kestrel.tls_handshake.duration` +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 | | -------- | --------------- | ----------- | -------------- | @@ -350,12 +358,12 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. | +| [`error.type`](../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. | | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [5] | `80`; `8080`; `443` | Recommended | -| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | Conditionally Required: if the connection is secured with TLS. | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | Recommended | +| [`tls.protocol.version`](../attributes-registry/tls.md) | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | Recommended | **[1]:** Captures the exception type when a TLS handshake fails. @@ -409,8 +417,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345. |---|---|---|---|---| | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `unix` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` | -| [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index 6062a54b83..64ae11681d 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -17,6 +17,10 @@ This article defines semantic conventions for SignalR metrics emitted by .NET co ## Metric: `signalr.server.connection.duration` +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.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index b0b8572f3a..b3a1c9d51d 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -43,8 +43,6 @@ groups: attributes: - ref: url.scheme examples: ['http', 'https', 'ftp'] - - ref: network.protocol.version - examples: ["1.1", "2"] - ref: server.address requirement_level: required brief: > @@ -80,7 +78,7 @@ groups: - id: metric.dotnet.http.client.open_connections type: metric metric_name: http.client.open_connections - brief: "Number of outbound HTTP connections that are currently active or idle on the client" + brief: "Number of outbound HTTP connections that are currently active or idle on the client." instrument: updowncounter unit: "{connection}" note: > @@ -102,6 +100,8 @@ groups: - ref: network.peer.address brief: Remote IP address of the socket connection. examples: ["10.1.2.80"] + - ref: network.protocol.version + examples: ["1.1", "2"] - id: metric.dotnet.http.client.connection.duration type: metric @@ -114,8 +114,8 @@ groups: extends: dotnet.http.client.connection.attributes attributes: - ref: network.peer.address - brief: Remote IP address of the socket connection. - examples: ["10.1.2.80"] + - ref: network.protocol.version + examples: ["1.1", "2"] - id: metric.dotnet.http.client.active_requests type: metric @@ -136,3 +136,6 @@ groups: note: > Meter name: `System.Net.Http`; Added in: .NET 8.0 extends: dotnet.http.client.request.attributes + attributes: + - ref: network.protocol.version + examples: ["1.1", "2"] \ No newline at end of file diff --git a/model/metrics/dotnet/dotnet-kestrel.yaml b/model/metrics/dotnet/dotnet-kestrel.yaml index 13e5c33f71..e04714a9b5 100644 --- a/model/metrics/dotnet/dotnet-kestrel.yaml +++ b/model/metrics/dotnet/dotnet-kestrel.yaml @@ -1,15 +1,4 @@ groups: - - id: tls - prefix: tls.protocol - type: attribute_group - brief: TLS attributes - attributes: - - id: version - type: string - brief: TLS protocol version. - examples: ["1.2", "1.3"] - requirement_level: - conditionally_required: if the connection is secured with TLS. - id: common.kestrel.attributes type: attribute_group brief: 'Common kestrel attributes' From 465bf37eb405ca6679b7d1694e60f47b3f793793 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Nov 2023 19:05:24 -0800 Subject: [PATCH 13/19] clean up attributes --- docs/dotnet/dotnet-http-metrics.md | 46 ++++++++++----------------- model/metrics/dotnet/dotnet-http.yaml | 16 +++------- 2 files changed, 22 insertions(+), 40 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 647f435743..211fbb9604 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -52,20 +52,17 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | -| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[2]:** Determined by using the first of the following that applies: +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. -- Host identifier of the `Host` header. - -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[4]:** If not the default (`80` for `http` scheme, `443` for `https`). @@ -96,18 +93,15 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. |---|---|---|---|---| | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[2]:** Determined by using the first of the following that applies: - -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. -- Host identifier of the `Host` header. +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[4]:** If not the default (`80` for `http` scheme, `443` for `https`). @@ -132,8 +126,8 @@ 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 |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -142,12 +136,9 @@ It's not possible at the moment to override the list of known HTTP methods. **[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Determined by using the first of the following that applies: +**[3]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. -- Host identifier of the `Host` header. - -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[5]:** If not the default (`80` for `http` scheme, `443` for `https`). @@ -181,20 +172,17 @@ It's not possible at the moment to override the list of known HTTP methods. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. -**[2]:** Determined by using the first of the following that applies: - -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. -- Host identifier of the `Host` header. +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match the URI port identifier; otherwise, it MUST match the `Host` header port identifier. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[4]:** If not the default (`80` for `http` scheme, `443` for `https`). diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index b3a1c9d51d..2f206e9e4d 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -46,21 +46,15 @@ groups: - ref: server.address requirement_level: required brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. - note: | - Determined by using the first of the following that applies: - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - - Host identifier of the `Host` header. + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then + `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - ref: server.port requirement_level: conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is an absolute URI, `server.port` MUST match - the URI port identifier; otherwise, it MUST match the `Host` header port identifier. - + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - id: dotnet.http.client.request.attributes type: attribute_group brief: "Common HTTP client attributes" From dd37d3b8b2fe0d226f5371cfd4aa80c45bb9aef2 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Nov 2023 19:39:35 -0800 Subject: [PATCH 14/19] more feedback --- docs/dotnet/dotnet-http-metrics.md | 10 +++++----- model/metrics/dotnet/dotnet-http.yaml | 22 ++++++++++++++++------ 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 211fbb9604..d13fed694c 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -52,13 +52,13 @@ Notes: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | -| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than one reported on request-level metrics or spans for HTTP 1.0 requests. **[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. @@ -92,12 +92,12 @@ 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 | |---|---|---|---|---| | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than one reported on request-level metrics or spans for HTTP 1.0 requests. **[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index 2f206e9e4d..7f964f10d3 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -37,7 +37,7 @@ groups: for more details. examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"] - - id: dotnet.http.client.connection.attributes + - id: dotnet.http.client.common.attributes type: attribute_group brief: "Common HTTP client attributes" attributes: @@ -55,10 +55,24 @@ groups: conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + + - id: dotnet.http.client.connection.attributes + type: attribute_group + brief: "Common HTTP client attributes" + extends: dotnet.http.client.common.attributes + attributes: + - ref: network.protocol.version + brief: HTTP protocol version of the connection in the connection pool. + note: > + HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. + So, the `network.protocol.version` value reported on connection metrics is different than one reported + on request-level metrics or spans for HTTP 1.0 requests. + examples: ["1.1", "2", "3"] + - id: dotnet.http.client.request.attributes type: attribute_group brief: "Common HTTP client attributes" - extends: dotnet.http.client.connection.attributes + extends: dotnet.http.client.common.attributes attributes: - ref: http.request.method note: > @@ -94,8 +108,6 @@ groups: - ref: network.peer.address brief: Remote IP address of the socket connection. examples: ["10.1.2.80"] - - ref: network.protocol.version - examples: ["1.1", "2"] - id: metric.dotnet.http.client.connection.duration type: metric @@ -108,8 +120,6 @@ groups: extends: dotnet.http.client.connection.attributes attributes: - ref: network.peer.address - - ref: network.protocol.version - examples: ["1.1", "2"] - id: metric.dotnet.http.client.active_requests type: metric From bc3ce34d099626321b956ad3ba95bea4e179837d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Nov 2023 20:09:34 -0800 Subject: [PATCH 15/19] more feedback and mark as stable --- docs/dotnet/README.md | 4 ++-- docs/dotnet/dotnet-aspnetcore-metrics.md | 4 ++-- docs/dotnet/dotnet-dns-metrics.md | 4 ++-- docs/dotnet/dotnet-http-metrics.md | 7 +++++-- docs/dotnet/dotnet-kestrel-metrics.md | 4 ++-- docs/dotnet/dotnet-signalr-metrics.md | 4 ++-- model/metrics/dotnet/dotnet-http.yaml | 2 +- 7 files changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/dotnet/README.md b/docs/dotnet/README.md index 56bd74e97b..1bc9673359 100644 --- a/docs/dotnet/README.md +++ b/docs/dotnet/README.md @@ -7,7 +7,7 @@ path_base_for_github_subdir: # Semantic Conventions for .NET metrics -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This article documents semantic conventions for metrics emitted by the .NET runtime and individual components in the .NET ecosystem. @@ -19,4 +19,4 @@ The following metrics are currently supported: * [Kestrel](dotnet-kestrel-metrics.md): Semantic Conventions for Kestrel web server *metrics*. * [SignalR](dotnet-signalr-metrics.md): Semantic Conventions for SignalR server *metrics*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 41808fd7d7..077d973565 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -4,7 +4,7 @@ linkTitle: ASP.NET Core # Semantic Conventions for ASP.NET Core metrics -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This article defines semantic conventions for ASP.NET Core metrics. @@ -240,4 +240,4 @@ Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0 | `request_canceled` | Lease request was canceled | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[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 a76c3a77bf..c0bb6b7aa3 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -4,7 +4,7 @@ linkTitle: DNS # Semantic Conventions for DNS metrics emitted by .NET -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This article defines semantic conventions for DNS metrics emitted by .NET. @@ -57,4 +57,4 @@ for more details. | `_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.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index d13fed694c..ffc32dfcb5 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -4,7 +4,7 @@ linkTitle: HTTP client and server # Semantic Conventions for HTTP client and server metrics emitted by .NET -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This article defines semantic conventions for HTTP metrics emitted by .NET components and runtime. @@ -37,6 +37,9 @@ Notes: - Meter name is `System.Net.Http` - Metric added in .NET 8.0 - When the `error.type` attribute is reported, it contains one of [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror) in snake_case, a full exception type, or a string representation of received status code. +- `network.protocol.name` is not reported and should always be assumed to match `http`. +- `server.port` is not reported when it matches a default one for provided scheme (`443` for `https` and `80` for `http`) +- `url.scheme` is always reported. ### Metric: `http.client.open_connections` @@ -229,4 +232,4 @@ Notes: - Opt-in `server.address` and `server.port` attributes are not reported - Metric added in ASP.NET Core 8.0 -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 8205cda2d5..96f400ab19 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -4,7 +4,7 @@ linkTitle: Kestrel # Semantic Conventions for Kestrel web server metrics -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This article defines semantic conventions for Kestrel web server. @@ -449,4 +449,4 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `ipv6` | IPv6 | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index 64ae11681d..dc2b04ed06 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -4,7 +4,7 @@ linkTitle: SignalR # Semantic Conventions for SignalR server metrics -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This article defines semantic conventions for SignalR metrics emitted by .NET components and runtime. @@ -85,4 +85,4 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. | `web_sockets` | WebSockets protocol | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index 7f964f10d3..d94e94cfd6 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -142,4 +142,4 @@ groups: extends: dotnet.http.client.request.attributes attributes: - ref: network.protocol.version - examples: ["1.1", "2"] \ No newline at end of file + examples: ["1.1", "2"] From 9b0cf6fa8ddd5ed3e5240c35aa5e522a09e98eb4 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Nov 2023 20:12:39 -0800 Subject: [PATCH 16/19] up --- docs/dotnet/dotnet-http-metrics.md | 5 ++--- model/metrics/dotnet/dotnet-http.yaml | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index ffc32dfcb5..4cfd422e88 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -61,7 +61,7 @@ Notes: | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than one reported on request-level metrics or spans for HTTP 1.0 requests. +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. **[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. @@ -100,7 +100,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | -**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than one reported on request-level metrics or spans for HTTP 1.0 requests. +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. **[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. @@ -115,7 +115,6 @@ 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 | | -------- | --------------- | ----------- | -------------- | diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index d94e94cfd6..c2556e3d87 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -65,7 +65,7 @@ groups: brief: HTTP protocol version of the connection in the connection pool. note: > HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. - So, the `network.protocol.version` value reported on connection metrics is different than one reported + So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. examples: ["1.1", "2", "3"] From 704113a62fa4359f5614f5d6f0e8b70299e32198 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 17 Nov 2023 09:54:38 -0800 Subject: [PATCH 17/19] is_fallback_route -> is_fallback --- docs/dotnet/dotnet-aspnetcore-metrics.md | 2 +- model/metrics/dotnet/dotnet-aspnetcore.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 077d973565..e217a1664c 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -43,7 +43,7 @@ All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `aspnetcore.routing.is_fallback_route` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | Conditionally Required: if and only if a route was successfully matched. | +| `aspnetcore.routing.is_fallback` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | Conditionally Required: if and only if a route was successfully matched. | | `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | Required | | [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. | diff --git a/model/metrics/dotnet/dotnet-aspnetcore.yaml b/model/metrics/dotnet/dotnet-aspnetcore.yaml index b25bc93808..8369e068d5 100644 --- a/model/metrics/dotnet/dotnet-aspnetcore.yaml +++ b/model/metrics/dotnet/dotnet-aspnetcore.yaml @@ -29,7 +29,7 @@ groups: brief: Rate-limiting result, shows whether the lease was acquired or contains a rejection reason examples: ["acquired", "request_canceled"] requirement_level: required - - id: routing.is_fallback_route + - id: routing.is_fallback type: boolean brief: A value that indicates whether the matched route is a fallback route. examples: [true] @@ -62,7 +62,7 @@ groups: - ref: http.route requirement_level: conditionally_required: if and only if a route was successfully matched. - - ref: aspnetcore.routing.is_fallback_route + - ref: aspnetcore.routing.is_fallback requirement_level: conditionally_required: if and only if a route was successfully matched. - id: aspnetcore.routing.match_status From 46d72fe08742dabd4e20a8677eeb33c288d63ee4 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 17 Nov 2023 10:02:24 -0800 Subject: [PATCH 18/19] time_in_queue excten connection, not request --- docs/dotnet/dotnet-http-metrics.md | 10 ++++------ model/metrics/dotnet/dotnet-http.yaml | 12 ++++++++---- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 4cfd422e88..ee7cb4d399 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -127,16 +127,15 @@ 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 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [2] | `1.1`; `2`; `3` | Recommended | | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. -It's not possible at the moment to override the list of known HTTP methods. +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[2]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. **[3]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. @@ -179,8 +178,7 @@ It's not possible at the moment to override the list of known HTTP methods. | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | **[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. -It's not possible at the moment to override the list of known HTTP methods. +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. **[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index c2556e3d87..9a326bb5d7 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -80,7 +80,6 @@ groups: and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. - It's not possible at the moment to override the list of known HTTP methods. - id: metric.dotnet.http.client.open_connections @@ -139,7 +138,12 @@ groups: unit: "s" note: > Meter name: `System.Net.Http`; Added in: .NET 8.0 - extends: dotnet.http.client.request.attributes + extends: dotnet.http.client.connection.attributes attributes: - - ref: network.protocol.version - examples: ["1.1", "2"] + - ref: http.request.method + note: > + HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) + and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + + If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. + It's not possible at the moment to override the list of known HTTP methods. From d9ff9905fa11e04177e9541dc10846eeab8f4f45 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 4 Dec 2023 09:20:04 -0800 Subject: [PATCH 19/19] Update CODEOWNERS --- .github/CODEOWNERS | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 31b5487a93..3556a7bbe4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -75,7 +75,7 @@ /model/registry/oci.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers # .NET semantic conventions approvers -/model/metrics/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approvers @open-telemetry/semconv-http-approvers -/docs/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approvers @open-telemetry/semconv-http-approvers +/model/metrics/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers +/docs/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers # TODO - Add semconv area experts