Document built-in System.Net activities (#43872)

.NET 9 introduced additions to `System.Net` distributed tracing which define a contract following OTel recommendations: - dotnet/runtime#104251 adjusted the HTTP client request activity so it natively complies with OTel recommendations. This included adding standard tags. - dotnet/runtime#103922 introduced activities breaking down the HTTP connection setup. This PR documents the activities together with their attributes in a manner similar to the metrics docs added by #37213. The matching semconv PR is open-telemetry/semantic-conventions#1192. Conceptual docs are being introduced in #42830. Moreover, the PR also adjusts certain parts of the metrics doc in order to make it more accurate, synchronize it with the activities doc and incorporate the changes from #42810. --------- Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: Miha Zupan <[email protected]>
dotnet · Dec 10, 2024 · 238a11d · 238a11d
1 parent 6f8be79
commit 238a11d
Show file tree

Hide file tree

Showing 5 changed files with 180 additions and 8 deletions.
diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md
@@ -67,7 +67,7 @@ The `System.Net.Http` metrics report HTTP request and connection information fro
 | Attribute  | Type | Description  | Examples  | Presence |
 |---|---|---|---|---|
 | `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Always |
-| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
+| `network.protocol.version` | string | Version of the HTTP protocol used. | `1.1`; `2` | Always |
 | `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always |
 | `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) |
 | `network.peer.address` | string | Peer IP address of the socket connection. | `10.5.3.2` | Always |
@@ -85,7 +85,7 @@ Available starting in: .NET 8
 
 | Attribute  | Type | Description  | Examples  | Presence |
 |---|---|---|---|---|
-| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
+| `network.protocol.version` | string | Version of the HTTP protocol used. | `1.1`; `2` | Always |
 | `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always |
 | `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) |
 | `network.peer.address` | string | IP address of the socket connection. | `10.5.3.2` | Always |
@@ -105,14 +105,27 @@ Available starting in: .NET 8
 
 | Attribute  | Type | Description  | Examples  | Presence |
 |---|---|---|---|---|
-| `error.type` | string | Request failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError), or a full exception type, or an HTTP 4xx/5xx status code. | `System.Threading.Tasks.TaskCanceledException`; `name_resolution_error`; `secure_connection_error` ; `404` | If request has failed. |
-| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always |
-| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If one was received. |
-| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | If response was received. |
+| `error.type` | string | Request failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError) in snake_case, or a full exception type, or an HTTP 4xx/5xx status code. | `System.Threading.Tasks.TaskCanceledException`; `name_resolution_error`; `secure_connection_error` ; `404` | If request has failed. |
+| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD`; `_OTHER` [2] | Always |
+| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If response was received. |
+| `network.protocol.version` | string | Version of the HTTP protocol used. | `1.1`; `2` | If response was received. |
 | `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always |
-| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) |
+| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | Depends on .NET version. [3] |
 | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always |
 
+**[1] `error.type`:** If the request has failed, the value is set to one of the following:
+
+- An exception name with type, for example, <xref:System.Threading.Tasks.TaskCanceledException>.
+- A status code that indicates a client or server error, for example, `500`.
+- If an <xref:System.Net.Http.HttpRequestException> occurred with an <xref:System.Net.Http.HttpRequestError> other than `Unknown`, the enum value in snake case, for example, `name_resolution_error`.
+
+**[2] `http.request.method`:** `http.request.method`:** The value contains the method name, if the method is one of the well-known methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods); otherwise the value is `_OTHER`. The user-provided method names will be mapped to known names in a case-insensitive manner. For example, if the user provides the name `GeT`, it will be mapped to `GET`.
+
+**[3] `server.port`:** The Presence of the value is version-dependent:
+
+- *.NET 8*: Present if not default (`80` for `http` scheme, `443` for `https`)
+- *.NET 9+*: Always present
+
 HTTP client request duration measures the time the underlying client handler takes to complete the request. Completing the request includes the time up to reading response headers from the network stream. It doesn't include the time spent reading the response body.
 
 When using OpenTelemetry, the default buckets for this metric are set to [ 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 ].
@@ -131,7 +144,7 @@ Available starting in: .NET 8
 | Attribute  | Type | Description  | Examples  | Presence |
 |---|---|---|---|---|
 | `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always |
-| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
+| `network.protocol.version` | string | Version of the HTTP protocol used. | `1.1`; `2` | Always |
 | `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always |
 | `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) |
 | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always |