diff --git a/CHANGELOG.md b/CHANGELOG.md index 4290e2c183..cbbaff78a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -121,6 +121,8 @@ release. - BREAKING: Remove the zero bucket boundary from `http.server.request.duration` and `http.client.request.duration`. ([#318](https://github.com/open-telemetry/semantic-conventions/pull/318)) +- 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)) ## v1.21.0 (2023-07-13) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 3ddfdc58e8..acae50a8a9 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -1,4 +1,4 @@ -# Semantic Conventions for ASP.NET Core metrics +# Semantic Conventions for ASP.NET Core 8.0 metrics **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 4200e459b9..e489dd0c2b 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -1,4 +1,4 @@ -# Semantic Conventions for DNS metrics emitted by .NET +# Semantic Conventions for DNS metrics emitted by .NET 8.0 **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index c69e923861..4ca31fd855 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -1,10 +1,10 @@ -# Semantic Conventions for HTTP-relevant metrics emitted by .NET and ASP.NET Core +# Semantic Conventions for HTTP-relevant metrics emitted by .NET 8.0 **Status**: [Experimental, Feature-freeze][DocumentStatus] This document defines semantic conventions for HTTP metrics emitted by .NET components and runtime. -**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future. +**Disclaimer:** These are initial .NET metric instruments available in .NET 8.0 but more may be added in the future. @@ -104,8 +104,7 @@ When observed from the server side, this SHOULD represent the physical server ad ### Metric: `http.client.request.duration` -Client request duration measures time it takes for the call time to underlying client handler to complete request. -If request was sent with `HttpCompletionOption.ResponseContentRead` option (the default value) then metric records time to last byte, otherwise (if `HttpCompletionOption.ResponseHeadersRead` was set), metric records time it took to receive response headers. +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. The `server.socket.address` attribute is not available at the instrumentation point and is not reported. @@ -119,15 +118,29 @@ The `server.socket.address` attribute is not available at the instrumentation po | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.error.reason` | string | Request failure reason: one of [HTTP Request errors](https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs), or a full exception type. | `System.Threading.Tasks.TaskCanceledException`; `name_resolution_error`; `secure_connection_error` | Conditionally Required: If request has failed. | -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Recommended | +| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`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] | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `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. [4] | `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. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | | [`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. +**[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]:** 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). @@ -142,23 +155,23 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M 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]:** `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 +**[4]:** 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]:** 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`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -`http.error.reason` 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. +`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` | unknown error | +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | `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 74574aebee..80768c2151 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -1,4 +1,4 @@ -# Semantic Conventions for Kestrel web server metrics +# Semantic Conventions for Kestrel web server metrics emitted by .NET 8.0 **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index aaba1d935f..ad94bd7f94 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -1,4 +1,4 @@ -# Semantic Conventions for SignalR metrics emitted by ASP.NET Core +# Semantic Conventions for SignalR metrics emitted by ASP.NET Core 8.0 **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index dfe149eec9..85d85e4127 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -187,7 +187,7 @@ groups: URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: http.request.method - ref: http.response.status_code - - ref: http.error.reason + - ref: error.type - id: metric.dotnet.http.client.request.time_in_queue type: metric