From db2f508f5c449f58823165c0ac4430e5235801ec Mon Sep 17 00:00:00 2001 From: antonfirsov Date: Thu, 5 Dec 2024 16:44:31 +0100 Subject: [PATCH 01/10] Document built-in System.Net activities --- .../built-in-metrics-system-net.md | 28 +++- .../distributed-tracing-builtin-activities.md | 151 ++++++++++++++++++ .../distributed-tracing-concepts.md | 2 + docs/core/diagnostics/distributed-tracing.md | 4 + docs/navigate/tools-diagnostics/toc.yml | 2 + 5 files changed, 179 insertions(+), 8 deletions(-) create mode 100644 docs/core/diagnostics/distributed-tracing-builtin-activities.md diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md index 738520aecb7b2..5591d4b32a89c 100644 --- 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,26 @@ 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, e.g., `System.Threading.Tasks.TaskCanceledException` +- A status code that indicates a client or server error, e.g., `500` +- In case an occurred and with a other than `Unknown`; the enum value in snake case, e.g., `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, e.g. 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 +143,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 | diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md new file mode 100644 index 0000000000000..33d52dfba03c2 --- /dev/null +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -0,0 +1,151 @@ +--- +title: Built-in Activities in .NET +description: Overview of activities emitted by the .NET libraries +ms.date: 12/05/2024 +--- + +# Built-in Activities in .NET + +This is a reference for distributed tracing Activities () emitted natively by .NET-s built-in instances. + +## System.Net Activities + +### HTTP client request + + and report the the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. + +| Availability | name | | | +|---|---|---|---| +| .NET 9+ | `System.Net.Http` | `System.Net.Http.HttpRequestOut` | `{HTTP method}` | + +> [!NOTE] +> The `System.Net.Http.HttpRequestOut` activity is in fact available on earlier versions of .NET, however its' , and attributes (tags) are only populated starting with .NET 9. On earlier versions the [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http/) package is recommended to fill the gaps of the built-in instrumentation. + +#### Attributes (tags) + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD`; `_OTHER` | 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`; `10.1.2.80` | 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` | Always | +| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=*` | Always | +| `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.OperationCanceledException`; `name_resolution_error`; `secure_connection_error` ; `404` | If the request has failed. | +| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `ACL`; `foo` | If `http.request.method` is not a well-known method. | +| `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. | + +**[1] `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, e.g. if the user provides the name `GeT`, it will be mapped to `GET`, and `http.request.method_original` will not be populated. + +**[2] `url.full`:** To avoid leaking secrets the value is redacted: the entire query is replaced with a `*` character and the fragment is missing. See the [URI redaction breaking change docs](../compatibility/networking/9.0/query-redaction-logs.md) for more details and opt-out switches. + +### HTTP client request: wait for connection (experimental) + +This activity is a child of an *HTTP client request* activity. It represents the time interval the corresponding request is waiting for an available connection in the request queue. If a free connection is available in the pool when the request comes in, no *wait for connection* activity will be created. Note that *wait for connection* does not represent the actual connection establishment; that is modeled by the *HTTP connection setup* activity. + +| Availability | name | | | +|---|---|---|---| +| .NET 9+ | `Experimental.System.Net.Http.Connections` | `Experimental.System.Net.Http.Connections.WaitForConnection` | `HTTP wait_for_connection {address}:{port}` | + +> [!TIP] +> The time it takes to get a connection from the pool is also reported by the [`http.client.request.time_in_queue`](built-in-metrics-system-net.md#metric-httpclientrequesttime_in_queue) metric. + +> [!WARNING] +> This activity is experimental. It might be altered or deleted in future versions! + +#### Attributes (tags) + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | The connection failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError) in snake_case, or a full exception type. | `System.OperationCanceledException`; `name_resolution_error`; `secure_connection_error` | If the connection attempt fails. | + +### HTTP connection setup (experimental) + +This activity describes the establishment of an HTTP connection. Typically, this includes the the time it takes to resolve the DNS, establish the socket connection, and perform the TLS handshake. + +| Availability | name | | | +|---|---|---|---| +| .NET 9+ | `Experimental.System.Net.Http.Connections` | `Experimental.System.Net.Http.Connections.ConnectionSetup` | `HTTP connection_setup {address}:{port}` | + +There is no parent-child relationship between the *HTTP client request* and the *HTTP connection setup* activities; the latter will always be a root activity, living in a separate trace. However, if the connection attempt represented by *HTTP connection setup* results in a succesful HTTP connection, and that connection is picked up by a request to serve it, the instrumentation adds an to the *HTTP client request* activity pointing to the *HTTP connection setup* activity. I.e., each request is linked to the connection that served the request. + +> [!NOTE] +> If *HTTP connection setup* fails, it will be not linked to any *HTTP client request*! + +> [!WARNING] +> This activity is experimental. It might be altered or deleted in future versions! + +#### Attributes (tags) + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | Connection failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError) in snake_case, or a full exception type. | `System.Net.Sockets.SocketException`; `name_resolution_error`; `secure_connection_error` | If the connection attempt fails. | +| `network.peer.address` | string | Peer IP address of the socket connection. | `10.5.3.2` | If the connection attempt succeeds. | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the initial 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) the initial HTTP request is sent to. | Always | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Always | + +### DNS lookup (experimental) + +This activity describes DNS lookups performed via calls. It corresponds to the managed call and not the physical DNS lookup(s) done by the underlying OS resolver. When the *DNS lookup* activity is reported along with a *HTTP connection setup* activity, *DNS lookup* becomes a child of *HTTP connection setup*. + +| Availability | name | | | +|---|---|---|---| +| .NET 9+ | `Experimental.System.Net.NameResolution` | `Experimental.System.Net.NameResolution.DnsLookup` | `DNS [reverse] lookup {question}` | + +> [!TIP] +> The DNS lookup duration is also reported by the [`dns.lookup.duration`](built-in-metrics-system-net.md#metric-dnslookupduration) metric. + +> [!WARNING] +> This activity is experimental. It might be altered or deleted in future versions! + +#### Attributes (tags) + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | The error code or exception name. [1] | `host_not_found` | If the lookup fails. | +| `dns.answers` | string[] | List of resolved IP addresses (for DNS lookup) or a single element containing domain name (for reverse lookup). | `["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]` | If the lookup succeeds. | +| `dns.question.name` | string | The domain name or an IP address being queried. | `example.com` | Always | + +**[1]:** The value is either a DNS-related in snake_case (`host_not_found`, `try_again`, `no_recovery`, `address_family_not_supported`), or a full exception name. + +### Socket connect (experimental) + +This activity describes the establishment of a connection via. or . When the *socket connect* activity is reported along with an *HTTP connection setup* activity, *socket connect* becomes a child of *HTTP connection setup*. + +| Availability | name | | | +|---|---|---|---| +| .NET 9+ | `Experimental.System.Net.Sockets` | `Experimental.System.Net.Sockets.Connect` | `socket connect {address}[:{port}]` | + +> [!WARNING] +> This activity is experimental. It might be altered or deleted in future versions! + +#### Attributes (tags) + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | The in snake_case. | `address_already_in_use`; `connection_refused` | If the socket connection attempt fails. | +| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.5.3.2`; `/tmp/my.sock` | IP and UDS sockets. | +| `network.peer.port` | int | Peer port number of the IP connection. | `65123` | IP sockets. | +| `network.transport` | string | [OSI transport layer](https://en.wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). | `tcp`; `udp`; `unix` | IP and UDS sockets. | +| `network.type` | string | [OSI network layer](https://en.wikipedia.org/wiki/Network_layer) or non-OSI equivalent. | `ipv4`; `ipv6` | IP sockets. | + +### TLS handshake (experimental) + +This activity describes the TLS client or server handshake performed via 's authentication methods. When the *TLS handshake* activity is reported for client-side authentication along with the *HTTP connection setup* activity, *TLS handshake* becomes a child of *HTTP connection setup*. + +| Availability | name | | | +|---|---|---|---| +| .NET 9+ | `Experimental.System.Net.Security` | `Experimental.System.Net.Security.TlsHandshake` | `TLS client handshake {host}` -or- `TLS server handshake` | + +> [!WARNING] +> This activity is experimental. It might be altered or deleted in future versions! + +#### Attributes (tags) + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | Describes a class of error the operation ended with. | `System.Net.Security.Authentication.AuthenticationException`; `System.OperationCanceledException` | If the handshake fails. | +| `server.address` | string | he [server name indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) used in the 'Client Hello' message during TLS handshake. | `example.com` | When authenticating as client. | +| `tls.protocol.name` | string | Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `ssl`; `tls` | When the protocol info is available. | +| `tls.protocol.version` | 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`; `1.3` | When the protocol info is available. | + \ No newline at end of file diff --git a/docs/core/diagnostics/distributed-tracing-concepts.md b/docs/core/diagnostics/distributed-tracing-concepts.md index bf92cf958e823..4099ca9938654 100644 --- a/docs/core/diagnostics/distributed-tracing-concepts.md +++ b/docs/core/diagnostics/distributed-tracing-concepts.md @@ -134,3 +134,5 @@ recorded. For example code to get started using distributed tracing in .NET applications, see the [Distributed Tracing Instrumentation](distributed-tracing-instrumentation-walkthroughs.md). + +For a list of activities emitted natively by .NET, see [Built-in Activities in .NET](distributed-tracing-builtin-activities.md). \ No newline at end of file diff --git a/docs/core/diagnostics/distributed-tracing.md b/docs/core/diagnostics/distributed-tracing.md index bea413c7dc64f..22ccfd621408f 100644 --- a/docs/core/diagnostics/distributed-tracing.md +++ b/docs/core/diagnostics/distributed-tracing.md @@ -35,6 +35,10 @@ For more information, see [Understand distributed tracing concepts](distributed- For third-party telemetry collection services, follow the setup instructions provided by the vendor. +## Built-in Activities emitted by .NET + +For a comprehensive list of Activities built into .NET see [Built-in Activities in .NET](distributed-tracing-builtin-activities.md). + ## Getting started for .NET library developers .NET libraries don't need to be concerned with how telemetry is ultimately collected, only diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 7a7ed0db9b00a..de89302f8f596 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -421,6 +421,8 @@ items: href: ../../core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md - name: Collection href: ../../core/diagnostics/distributed-tracing-collection-walkthroughs.md + - name: Built-in Activities + href: ../../core/diagnostics/distributed-tracing-builtin-activities.md - name: Specialized diagnostics items: - name: Overview From 8be1117bddc758af609267bd498d4a40d99d8e03 Mon Sep 17 00:00:00 2001 From: antonfirsov Date: Thu, 5 Dec 2024 17:16:05 +0100 Subject: [PATCH 02/10] %2A --- docs/core/diagnostics/distributed-tracing-builtin-activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index 33d52dfba03c2..cde3a5a8e0499 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -110,7 +110,7 @@ This activity describes DNS lookups performed via calls. I ### Socket connect (experimental) -This activity describes the establishment of a connection via. or . When the *socket connect* activity is reported along with an *HTTP connection setup* activity, *socket connect* becomes a child of *HTTP connection setup*. +This activity describes the establishment of a connection via. or . When the *socket connect* activity is reported along with an *HTTP connection setup* activity, *socket connect* becomes a child of *HTTP connection setup*. | Availability | name | | | |---|---|---|---| From 92b50142507a78123fc7ace74aae3881e56ce522 Mon Sep 17 00:00:00 2001 From: antonfirsov Date: Thu, 5 Dec 2024 17:34:17 +0100 Subject: [PATCH 03/10] lint --- docs/core/diagnostics/built-in-metrics-system-net.md | 3 ++- .../core/diagnostics/distributed-tracing-builtin-activities.md | 3 +-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md index 5591d4b32a89c..a5e0725e4260c 100644 --- a/docs/core/diagnostics/built-in-metrics-system-net.md +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -114,6 +114,7 @@ Available starting in: .NET 8 | `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, e.g., `System.Threading.Tasks.TaskCanceledException` - A status code that indicates a client or server error, e.g., `500` - In case an occurred and with a other than `Unknown`; the enum value in snake case, e.g., `name_resolution_error` @@ -122,7 +123,7 @@ Available starting in: .NET 8 **[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 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. diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index cde3a5a8e0499..cd968ec31c3f0 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -147,5 +147,4 @@ This activity describes the TLS client or server handshake performed via Date: Thu, 5 Dec 2024 17:37:19 +0100 Subject: [PATCH 04/10] lint --- docs/core/diagnostics/distributed-tracing-builtin-activities.md | 2 +- docs/core/diagnostics/distributed-tracing-concepts.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index cd968ec31c3f0..0a07e0dd5f767 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -147,4 +147,4 @@ This activity describes the TLS client or server handshake performed via Date: Thu, 5 Dec 2024 21:52:54 +0100 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../built-in-metrics-system-net.md | 8 ++--- .../distributed-tracing-builtin-activities.md | 33 ++++++++++--------- .../distributed-tracing-concepts.md | 2 +- docs/core/diagnostics/distributed-tracing.md | 4 +-- docs/navigate/tools-diagnostics/toc.yml | 2 +- 5 files changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md index a5e0725e4260c..275386b3ab45b 100644 --- a/docs/core/diagnostics/built-in-metrics-system-net.md +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -115,11 +115,11 @@ Available starting in: .NET 8 **[1] `error.type`:** If the request has failed, the value is set to one of the following: -- An exception name with type, e.g., `System.Threading.Tasks.TaskCanceledException` -- A status code that indicates a client or server error, e.g., `500` -- In case an occurred and with a other than `Unknown`; the enum value in snake case, e.g., `name_resolution_error` +- An exception name with type, for example, . +- A status code that indicates a client or server error, for example, `500`. +- If an occurred with an 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, e.g. if the user provides the name `GeT`, it will be mapped to `GET`. +**[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: diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index 0a07e0dd5f767..42768676f28d8 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -2,24 +2,25 @@ title: Built-in Activities in .NET description: Overview of activities emitted by the .NET libraries ms.date: 12/05/2024 +ms.topic: reference --- -# Built-in Activities in .NET +# Built-in activities in .NET -This is a reference for distributed tracing Activities () emitted natively by .NET-s built-in instances. +This is a reference for distributed tracing [activities](xref:System.Diagnostics.Activity) emitted natively by .NET's built-in instances. -## System.Net Activities +## System.Net activities ### HTTP client request - and report the the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. + and report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. | Availability | name | | | |---|---|---|---| | .NET 9+ | `System.Net.Http` | `System.Net.Http.HttpRequestOut` | `{HTTP method}` | > [!NOTE] -> The `System.Net.Http.HttpRequestOut` activity is in fact available on earlier versions of .NET, however its' , and attributes (tags) are only populated starting with .NET 9. On earlier versions the [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http/) package is recommended to fill the gaps of the built-in instrumentation. +> The `System.Net.Http.HttpRequestOut` activity is in fact available on earlier versions of .NET, however its , , and attributes (tags) are only populated starting with .NET 9. On earlier versions, the [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http/) package is recommended to fill the gaps of the built-in instrumentation. #### Attributes (tags) @@ -34,9 +35,9 @@ This is a reference for distributed tracing Activities ( The time it takes to get a connection from the pool is also reported by the [`http.client.request.time_in_queue`](built-in-metrics-system-net.md#metric-httpclientrequesttime_in_queue) metric. > [!WARNING] -> This activity is experimental. It might be altered or deleted in future versions! +> This activity is experimental. It might be altered or deleted in a future version. #### Attributes (tags) @@ -66,13 +67,13 @@ This activity describes the establishment of an HTTP connection. Typically, this |---|---|---|---| | .NET 9+ | `Experimental.System.Net.Http.Connections` | `Experimental.System.Net.Http.Connections.ConnectionSetup` | `HTTP connection_setup {address}:{port}` | -There is no parent-child relationship between the *HTTP client request* and the *HTTP connection setup* activities; the latter will always be a root activity, living in a separate trace. However, if the connection attempt represented by *HTTP connection setup* results in a succesful HTTP connection, and that connection is picked up by a request to serve it, the instrumentation adds an to the *HTTP client request* activity pointing to the *HTTP connection setup* activity. I.e., each request is linked to the connection that served the request. +There is no parent-child relationship between the *HTTP client request* and the *HTTP connection setup* activities; the latter will always be a root activity, living in a separate trace. However, if the connection attempt represented by *HTTP connection setup* results in a succesful HTTP connection, and that connection is picked up by a request to serve it, the instrumentation adds an to the *HTTP client request* activity pointing to the *HTTP connection setup* activity. That is, each request is linked to the connection that served the request. > [!NOTE] -> If *HTTP connection setup* fails, it will be not linked to any *HTTP client request*! +> If *HTTP connection setup* fails, it won't be linked to any *HTTP client request*. > [!WARNING] -> This activity is experimental. It might be altered or deleted in future versions! +> This activity is experimental. It might be altered or deleted in a future version. #### Attributes (tags) @@ -96,7 +97,7 @@ This activity describes DNS lookups performed via calls. I > The DNS lookup duration is also reported by the [`dns.lookup.duration`](built-in-metrics-system-net.md#metric-dnslookupduration) metric. > [!WARNING] -> This activity is experimental. It might be altered or deleted in future versions! +> This activity is experimental. It might be altered or deleted in a future version. #### Attributes (tags) @@ -110,14 +111,14 @@ This activity describes DNS lookups performed via calls. I ### Socket connect (experimental) -This activity describes the establishment of a connection via. or . When the *socket connect* activity is reported along with an *HTTP connection setup* activity, *socket connect* becomes a child of *HTTP connection setup*. +This activity describes the establishment of a connection via or . When the *socket connect* activity is reported along with an *HTTP connection setup* activity, *socket connect* becomes a child of *HTTP connection setup*. | Availability | name | | | |---|---|---|---| | .NET 9+ | `Experimental.System.Net.Sockets` | `Experimental.System.Net.Sockets.Connect` | `socket connect {address}[:{port}]` | > [!WARNING] -> This activity is experimental. It might be altered or deleted in future versions! +> This activity is experimental. It might be altered or deleted in a future version. #### Attributes (tags) @@ -138,13 +139,13 @@ This activity describes the TLS client or server handshake performed via [!WARNING] -> This activity is experimental. It might be altered or deleted in future versions! +> This activity is experimental. It might be altered or deleted in future versions. #### Attributes (tags) | Attribute | Type | Description | Examples | Presence | |---|---|---|---|---| | `error.type` | string | Describes a class of error the operation ended with. | `System.Net.Security.Authentication.AuthenticationException`; `System.OperationCanceledException` | If the handshake fails. | -| `server.address` | string | he [server name indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) used in the 'Client Hello' message during TLS handshake. | `example.com` | When authenticating as client. | +| `server.address` | string | The [server name indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) used in the 'Client Hello' message during TLS handshake. | `example.com` | When authenticating as client. | | `tls.protocol.name` | string | Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `ssl`; `tls` | When the protocol info is available. | | `tls.protocol.version` | 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`; `1.3` | When the protocol info is available. | diff --git a/docs/core/diagnostics/distributed-tracing-concepts.md b/docs/core/diagnostics/distributed-tracing-concepts.md index 29172b31faed0..08f27cacda5cc 100644 --- a/docs/core/diagnostics/distributed-tracing-concepts.md +++ b/docs/core/diagnostics/distributed-tracing-concepts.md @@ -135,4 +135,4 @@ recorded. For example code to get started using distributed tracing in .NET applications, see the [Distributed Tracing Instrumentation](distributed-tracing-instrumentation-walkthroughs.md). -For a list of activities emitted natively by .NET, see [Built-in Activities in .NET](distributed-tracing-builtin-activities.md). +For a list of activities emitted natively by .NET, see [Built-in activities in .NET](distributed-tracing-builtin-activities.md). diff --git a/docs/core/diagnostics/distributed-tracing.md b/docs/core/diagnostics/distributed-tracing.md index 22ccfd621408f..11c00e751bd21 100644 --- a/docs/core/diagnostics/distributed-tracing.md +++ b/docs/core/diagnostics/distributed-tracing.md @@ -35,9 +35,9 @@ For more information, see [Understand distributed tracing concepts](distributed- For third-party telemetry collection services, follow the setup instructions provided by the vendor. -## Built-in Activities emitted by .NET +## Built-in activities emitted by .NET -For a comprehensive list of Activities built into .NET see [Built-in Activities in .NET](distributed-tracing-builtin-activities.md). +For a comprehensive list of activities built into .NET see [Built-in activities in .NET](distributed-tracing-builtin-activities.md). ## Getting started for .NET library developers diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index de89302f8f596..33f7ed0c9aa30 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -421,7 +421,7 @@ items: href: ../../core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md - name: Collection href: ../../core/diagnostics/distributed-tracing-collection-walkthroughs.md - - name: Built-in Activities + - name: Built-in activities href: ../../core/diagnostics/distributed-tracing-builtin-activities.md - name: Specialized diagnostics items: From ba604f8a4af0c46fb591b6b3f102b55626015324 Mon Sep 17 00:00:00 2001 From: antonfirsov Date: Mon, 9 Dec 2024 17:43:05 +0100 Subject: [PATCH 06/10] code fence OTel type names --- .../distributed-tracing-builtin-activities.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index 42768676f28d8..cf0c2f6bb9348 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -26,14 +26,14 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics | Attribute | Type | Description | Examples | Presence | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD`; `_OTHER` | 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`; `10.1.2.80` | 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` | Always | -| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=*` | Always | -| `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.OperationCanceledException`; `name_resolution_error`; `secure_connection_error` ; `404` | If the request has failed. | -| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `ACL`; `foo` | If `http.request.method` is not a well-known method. | -| `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. | +| `http.request.method` | `string` | HTTP request method. [1] | `GET`; `POST`; `HEAD`; `_OTHER` | 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`; `10.1.2.80` | 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` | Always | +| `url.full` | `string` | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=*` | Always | +| `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.OperationCanceledException`; `name_resolution_error`; `secure_connection_error` ; `404` | If the request has failed. | +| `http.request.method_original` | `string` | Original HTTP method sent by the client in the request line. | `ACL`; `foo` | If `http.request.method` is not a well-known method. | +| `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. | **[1] `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 are mapped to known names in a case-insensitive manner. For example, if the user provides the name `GeT`, it will be mapped to `GET`, and `http.request.method_original` will not be populated. @@ -57,7 +57,7 @@ This activity is a child of an *HTTP client request* activity. It represents the | Attribute | Type | Description | Examples | Presence | |---|---|---|---|---| -| `error.type` | string | The connection failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError) in snake_case, or a full exception type. | `System.OperationCanceledException`; `name_resolution_error`; `secure_connection_error` | If the connection attempt fails. | +| `error.type` | `string` | The connection failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError) in snake_case, or a full exception type. | `System.OperationCanceledException`; `name_resolution_error`; `secure_connection_error` | If the connection attempt fails. | ### HTTP connection setup (experimental) @@ -79,11 +79,11 @@ There is no parent-child relationship between the *HTTP client request* and the | Attribute | Type | Description | Examples | Presence | |---|---|---|---|---| -| `error.type` | string | Connection failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError) in snake_case, or a full exception type. | `System.Net.Sockets.SocketException`; `name_resolution_error`; `secure_connection_error` | If the connection attempt fails. | -| `network.peer.address` | string | Peer IP address of the socket connection. | `10.5.3.2` | If the connection attempt succeeds. | -| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the initial 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) the initial HTTP request is sent to. | Always | -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Always | +| `error.type` | `string` | Connection failure reason: one of the [HTTP request errors](xref:System.Net.Http.HttpRequestError) in snake_case, or a full exception type. | `System.Net.Sockets.SocketException`; `name_resolution_error`; `secure_connection_error` | If the connection attempt fails. | +| `network.peer.address` | `string` | Peer IP address of the socket connection. | `10.5.3.2` | If the connection attempt succeeds. | +| `server.address` | `string` | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) the initial 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) the initial HTTP request is sent to. | Always | +| `url.scheme` | `string` | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Always | ### DNS lookup (experimental) @@ -103,9 +103,9 @@ This activity describes DNS lookups performed via calls. I | Attribute | Type | Description | Examples | Presence | |---|---|---|---|---| -| `error.type` | string | The error code or exception name. [1] | `host_not_found` | If the lookup fails. | -| `dns.answers` | string[] | List of resolved IP addresses (for DNS lookup) or a single element containing domain name (for reverse lookup). | `["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]` | If the lookup succeeds. | -| `dns.question.name` | string | The domain name or an IP address being queried. | `example.com` | Always | +| `error.type` | `string` | The error code or exception name. [1] | `host_not_found` | If the lookup fails. | +| `dns.answers` | `string[]` | List of resolved IP addresses (for DNS lookup) or a single element containing domain name (for reverse lookup). | `["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]` | If the lookup succeeds. | +| `dns.question.name` | `string` | The domain name or an IP address being queried. | `example.com` | Always | **[1]:** The value is either a DNS-related in snake_case (`host_not_found`, `try_again`, `no_recovery`, `address_family_not_supported`), or a full exception name. @@ -124,11 +124,11 @@ This activity describes the establishment of a | Attribute | Type | Description | Examples | Presence | |---|---|---|---|---| -| `error.type` | string | The in snake_case. | `address_already_in_use`; `connection_refused` | If the socket connection attempt fails. | -| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.5.3.2`; `/tmp/my.sock` | IP and UDS sockets. | -| `network.peer.port` | int | Peer port number of the IP connection. | `65123` | IP sockets. | -| `network.transport` | string | [OSI transport layer](https://en.wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). | `tcp`; `udp`; `unix` | IP and UDS sockets. | -| `network.type` | string | [OSI network layer](https://en.wikipedia.org/wiki/Network_layer) or non-OSI equivalent. | `ipv4`; `ipv6` | IP sockets. | +| `error.type` | `string` | The in snake_case. | `address_already_in_use`; `connection_refused` | If the socket connection attempt fails. | +| `network.peer.address` | `string` | Peer address of the network connection - IP address or Unix domain socket name. | `10.5.3.2`; `/tmp/my.sock` | IP and UDS sockets. | +| `network.peer.port` | `int` | Peer port number of the IP connection. | `65123` | IP sockets. | +| `network.transport` | `string` | [OSI transport layer](https://en.wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). | `tcp`; `udp`; `unix` | IP and UDS sockets. | +| `network.type` | `string` | [OSI network layer](https://en.wikipedia.org/wiki/Network_layer) or non-OSI equivalent. | `ipv4`; `ipv6` | IP sockets. | ### TLS handshake (experimental) @@ -145,7 +145,7 @@ This activity describes the TLS client or server handshake performed via Date: Tue, 10 Dec 2024 23:21:19 +0100 Subject: [PATCH 07/10] mention user info redaction Co-authored-by: Miha Zupan --- docs/core/diagnostics/distributed-tracing-builtin-activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index cf0c2f6bb9348..0be411ff6a741 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -37,7 +37,7 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics **[1] `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 are mapped to known names in a case-insensitive manner. For example, if the user provides the name `GeT`, it will be mapped to `GET`, and `http.request.method_original` will not be populated. -**[2] `url.full`:** To avoid leaking secrets the value is redacted: the entire query is replaced with a `*` character and the fragment is missing. For more information and opt-out switches, see the [URI redaction breaking change docs](../compatibility/networking/9.0/query-redaction-logs.md). +**[2] `url.full`:** To avoid leaking secrets the value is redacted by default: the entire query is replaced with a `*` character and the user info & fragment are removed. For more information and opt-out switches, see the [URI redaction breaking change docs](../compatibility/networking/9.0/query-redaction-logs.md). ### HTTP client request: wait for connection (experimental) From a3282d0176546bc19022df32a84d94cf69ff4645 Mon Sep 17 00:00:00 2001 From: antonfirsov Date: Tue, 10 Dec 2024 23:54:23 +0100 Subject: [PATCH 08/10] add notes about retries --- .../diagnostics/distributed-tracing-builtin-activities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index 0be411ff6a741..aac1893940af8 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -13,7 +13,7 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics ### HTTP client request - and report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. + and report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. `SocketsHttpHandler` may retry requests on connection failure. Retries are not reported as separate *HTTP client request* activities. | Availability | name | | | |---|---|---|---| @@ -41,7 +41,7 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics ### HTTP client request: wait for connection (experimental) -This activity is a child of an *HTTP client request* activity. It represents the time interval the corresponding request is waiting for an available connection in the request queue. If a free connection is available in the pool when the request comes in, no *wait for connection* activity will be created. Note that *wait for connection* does not represent the actual connection establishment; that is modeled by the *HTTP connection setup* activity. +This activity is a child of an *HTTP client request* activity. It represents the time interval the corresponding request is waiting for an available connection in the request queue. If a free connection is available in the pool when the request comes in, no *wait for connection* activity will be created. Note that *wait for connection* does not represent the actual connection establishment; that is modeled by the *HTTP connection setup* activity. `SocketsHttpHandler` may retry requests on connection failure. Retries are not reported as separate *HTTP client request* activities; however, each retry will result in a new *wait for connection* activity under the parent request activity. | Availability | name | | | |---|---|---|---| From c50c3b210edf92e8c7f166150c95308b91691d10 Mon Sep 17 00:00:00 2001 From: antonfirsov Date: Wed, 11 Dec 2024 00:03:05 +0100 Subject: [PATCH 09/10] better wording --- .../diagnostics/distributed-tracing-builtin-activities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index aac1893940af8..f71371001aa8e 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -13,7 +13,7 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics ### HTTP client request - and report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. `SocketsHttpHandler` may retry requests on connection failure. Retries are not reported as separate *HTTP client request* activities. + and report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. `SocketsHttpHandler` may retry requests, for example, on connection failures or HTTP version downgrades. Retries are not reported as separate *HTTP client request* activities. | Availability | name | | | |---|---|---|---| @@ -41,7 +41,7 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics ### HTTP client request: wait for connection (experimental) -This activity is a child of an *HTTP client request* activity. It represents the time interval the corresponding request is waiting for an available connection in the request queue. If a free connection is available in the pool when the request comes in, no *wait for connection* activity will be created. Note that *wait for connection* does not represent the actual connection establishment; that is modeled by the *HTTP connection setup* activity. `SocketsHttpHandler` may retry requests on connection failure. Retries are not reported as separate *HTTP client request* activities; however, each retry will result in a new *wait for connection* activity under the parent request activity. +This activity is a child of an *HTTP client request* activity. It represents the time interval the corresponding request is waiting for an available connection in the request queue. If a free connection is available in the pool when the request comes in, no *wait for connection* activity will be created. Note that *wait for connection* does not represent the actual connection establishment; that is modeled by the *HTTP connection setup* activity. `SocketsHttpHandler` may retry requests, for example, on connection failures or HTTP version downgrades. Retries are not reported as separate *HTTP client request* activities; however, each new connection attempt will result in a new *wait for connection* activity under the parent request activity. | Availability | name | | | |---|---|---|---| From e18c7a41a292d138e94e7af8b0b3ef13fd74fdf2 Mon Sep 17 00:00:00 2001 From: antonfirsov Date: Wed, 11 Dec 2024 00:29:50 +0100 Subject: [PATCH 10/10] xref --- .../diagnostics/distributed-tracing-builtin-activities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/distributed-tracing-builtin-activities.md b/docs/core/diagnostics/distributed-tracing-builtin-activities.md index f71371001aa8e..be61a20ca3c3b 100644 --- a/docs/core/diagnostics/distributed-tracing-builtin-activities.md +++ b/docs/core/diagnostics/distributed-tracing-builtin-activities.md @@ -13,7 +13,7 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics ### HTTP client request - and report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. `SocketsHttpHandler` may retry requests, for example, on connection failures or HTTP version downgrades. Retries are not reported as separate *HTTP client request* activities. + and report the HTTP client request activity following the recommendations defined in OpenTelemetry [HTTP Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client). It describes the HTTP request sent by 's send overloads during the time interval the underlying handler completes 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. may retry requests, for example, on connection failures or HTTP version downgrades. Retries are not reported as separate *HTTP client request* activities. | Availability | name | | | |---|---|---|---| @@ -41,7 +41,7 @@ This is a reference for distributed tracing [activities](xref:System.Diagnostics ### HTTP client request: wait for connection (experimental) -This activity is a child of an *HTTP client request* activity. It represents the time interval the corresponding request is waiting for an available connection in the request queue. If a free connection is available in the pool when the request comes in, no *wait for connection* activity will be created. Note that *wait for connection* does not represent the actual connection establishment; that is modeled by the *HTTP connection setup* activity. `SocketsHttpHandler` may retry requests, for example, on connection failures or HTTP version downgrades. Retries are not reported as separate *HTTP client request* activities; however, each new connection attempt will result in a new *wait for connection* activity under the parent request activity. +This activity is a child of an *HTTP client request* activity. It represents the time interval the corresponding request is waiting for an available connection in the request queue. If a free connection is available in the pool when the request comes in, no *wait for connection* activity will be created. Note that *wait for connection* does not represent the actual connection establishment; that is modeled by the *HTTP connection setup* activity. may retry requests, for example, on connection failures or HTTP version downgrades. Retries are not reported as separate *HTTP client request* activities; however, each new connection attempt will result in a new *wait for connection* activity under the parent request activity. | Availability | name | | | |---|---|---|---|