review

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)
 

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]
 

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]
 

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.
 
 <!-- toc -->
 
@@ -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
 <!-- semconv metric.dotnet.http.client.request.duration(full) -->
 | 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.
 

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]
 

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]
 

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