diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md index d80746f891..b7673d45f5 100644 --- a/docs/attributes-registry/dns.md +++ b/docs/attributes-registry/dns.md @@ -10,15 +10,9 @@ This document defines the shared attributes used to report a DNS query. -<<<<<<< HEAD | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `dns.answers` | string[] | The list of IPv4 or IPv6 addresses resolved during DNS lookup. | `["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `opentelemetry.io` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -======= -| Attribute | Type | Description | Examples | Stability | -| ------------------- | -------- | -------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------- | -| `dns.answers` | string[] | The list of resolved IPv4 or IPv6 addresses. | `["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `opentelemetry.io` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ->>>>>>> 98544399 (Add .NET HTTP connection spans) **[1] `dns.question.name`:** 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-network-traces.md b/docs/dotnet/dotnet-network-traces.md index b58cebe439..8e1de40fb7 100644 --- a/docs/dotnet/dotnet-network-traces.md +++ b/docs/dotnet/dotnet-network-traces.md @@ -14,7 +14,7 @@ This article defines semantic conventions for HTTP client, DNS and TLS spans emi - [HTTP client request: wait for connection](#http-client-request-wait-for-connection) - [HTTP connection setup](#http-connection-setup) - [Socket connect](#socket-connect) -- [DNS resolution](#dns-resolution) +- [DNS lookup](#dns-lookup) - [TLS handshake](#tls-handshake) - [Examples](#examples) - [HTTP request was performed on a connection that was immediately available](#http-request-was-performed-on-a-connection-that-was-immediately-available) @@ -43,10 +43,12 @@ Using connection-level instrumentation in production environments should be done .NET `HttpClient` reports client request spans according to [HTTP Client Semantic Conventions](/docs/http/http-spans.md#http-client) with the following specific details: -- `network.protocol.name`, `network.peer.port`, and `http.request.resend_count` are not reported +- `network.protocol.name`, `network.peer.port`, and `http.request.resend_count` attributes are not reported - `url.full` is redacted by default - query parameter values are replaced with `*`. Redaction can be disabled by setting `AppContext` switch `System.Net.Http.DisableQueryRedaction` to `true`. -- 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. -- all attributes are reported after `Activity` is started, none are provided at creation time. +- 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 name, or a string representation of received status code. +- All attributes are reported after `Activity` is started, none are provided at creation time. +- In case redirects occur, each redirected request is reported as a separate span. +- `SocketsHttpHandler` may retry requests on connection failure. Such retries are not reported as separate spans. Corresponding `Activity.OperationName` is `System.Net.Http.HttpRequestOut`, `ActivitySource` name - `System.Net.Http`. Span with HTTP semantics was added in .NET 9. @@ -61,17 +63,17 @@ The span is reported only if there is no connection that's readily available. It The span ends when the connection is obtained - it could happen when an existing connection becomes available or once a new connection is established, so the duration of *Wait For Connection* span is different from duration of the [*HTTP connection setup*](#http-connection-setup) span. -Span name SHOULD be `wait_for_connection {server.address}:{server.port}`. +Span name SHOULD be `HTTP wait_for_connection {server.address}:{server.port}`. Span kind SHOULD be `INTERNAL` -Corresponding `Activity.OperationName` is `Experimental.System.Net.Http.ConnectionLink.WaitForConnection`, `ActivitySource` name - `Experimental.System.Net.Http`. +Corresponding `Activity.OperationName` is `Experimental.System.Net.Http.Connections.WaitForConnection`, `ActivitySource` name - `Experimental.System.Net.Http`. Span added in .NET 9. The time it takes to get a connection from the pool is also reported by the [`http.client.request.time_in_queue` metric](/docs/dotnet/dotnet-http-metrics.md#metric-httpclientrequesttime_in_queue). - + @@ -82,14 +84,14 @@ The time it takes to get a connection from the pool is also reported by the |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | One of the [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror) in snake_case, or a full exception type. | `version_negotiation_error`; `System.OperationCanceledException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + `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 | Stability | |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - - @@ -102,19 +104,16 @@ The time it takes to get a connection from the pool is also reported by the The span describes the establishment of the HTTP connection. It includes the time it takes to resolve the DNS, establish the socket connection, and perform the TLS handshake. -Span name SHOULD be `HTTP connection_setup {address}:{server.port}`. -The `{address}` SHOULD be `server.address` when it's available and `network.peer.address` otherwise. +Span name SHOULD be `HTTP connection_setup {server.address}:{server.port}`. Span kind SHOULD be `INTERNAL`. -If the [*HTTP connection setup*](#http-connection-setup) is reported, the instrumentation adds the -link to the *HTTP client request* span pointing to the *HTTP connection setup* span. I.e. each client request span -is linked to the connection that served this request (if the connection was ever associated with this request). +There is no parent-child relationship between the [*HTTP client request*](#http-client-request) and the [*HTTP connection setup*](#http-connection-setup) spans; the latter will always be a root span, defining a separate trace. However, if the connection attempt represented by the [*HTTP connection setup*](#http-connection-setup) span results in a successful HTTP connection, and that connection is picked up by a request to serve it, the instrumentation adds a link to the [*HTTP client request*](#http-client-request) span pointing to the *HTTP connection setup* span. I.e., each request is linked to the connection that served this request. Corresponding `Activity.OperationName` is `Experimental.System.Net.Http.Connections.ConnectionSetup`, `ActivitySource` name - `Experimental.System.Net.Http.Connections`. Added in .NET 9. - + @@ -124,16 +123,18 @@ Added in .NET 9. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | One of the [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror) in snake_case, or a full exception type. | `name_resolution_error`; `System.OperationCanceledException` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.peer.address`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer IP address of the socket connection. [1] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [3] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** 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. +**[1] `network.peer.address`:** The `network.peer.address` attribute is available only if the connection was successfully established. -**[2]:** 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. +**[2] `server.address`:** 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. +**[3] `server.port`:** 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. @@ -141,7 +142,65 @@ Added in .NET 9. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + +## DNS lookup + +**Status**: [Experimental][DocumentStatus] + +The span describes DNS lookups performed with one of the methods on [System.Net.Dns](https://learn.microsoft.com/dotnet/api/system.net.dns) class. +DNS lookup duration is also reported by [`dns.lookup.duration` metric](/docs/dotnet/dotnet-dns-metrics.md#metric-dnslookupduration). + +DNS spans track logical operations rather than physical DNS calls and the actual behavior depends on the resolver implementation which could be changed in the future versions of .NET. +.NET 9 uses OS DNS resolver which may do zero or more physical lookups for one API call. + +When the *DNS lookup* span is reported along with *HTTP connection setup* and *socket connect* span, the *DNS lookup* span span becomes a child of *HTTP connection setup* +and a sibling of *socket connect*. + +DNS spans are reported for both lookups and reverse lookups. + +Lookup (IP addresses from host name) span name SHOULD be `DNS lookup {dns.question.name}`. +Reverse lookup (host names from IP address) span name SHOULD be `DNS reverse lookup {dns.question.name}`. +Span kind SHOULD be `INTERNAL`. + +Corresponding `Activity.OperationName` is `Experimental.System.Net.NameResolution.DnsLookup`, `ActivitySource` name - `Experimental.System.Net.NameResolution`. +Added in .NET 9 + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`error.type`](/docs/attributes-registry/error.md) | string | The error code or exception name returned by [System.Net.Dns](https://learn.microsoft.com/dotnet/api/system.net.dns). [1] | `host_not_found`; `try_again` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`dns.answers`](/docs/attributes-registry/dns.md) | 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"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`dns.question.name`](/docs/attributes-registry/dns.md) | string | The domain name or an IP address being queried. [2] | `www.example.com`; `opentelemetry.io` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `error.type`:** The following errors are reported: +- `host_not_found` +- `try_again` +- `no_recovery` +- `address_family_not_supported` +- the full exception type name + +See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) for more details. + +**[2] `dns.question.name`:** 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. + +--- + +`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 | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -155,15 +214,15 @@ Added in .NET 9. The span describes the establishment of the socket connection. It's different from [*HTTP connection setup*](#http-connection-setup) span, which also covers the DNS lookup and TLS handshake. -When *Socket connect* span is reported along with *HTTP connection setup* span, the socket span becomes a child of HTTP connection setup. +When *socket connect* span is reported along with *HTTP connection setup* span, the socket span becomes a child of HTTP connection setup. -Span name SHOULD be `socket connect {network.peer.address}:{network.peer.port}`. +Span name SHOULD be `socket connect {network.peer.address}:{network.peer.port}`, where port is only available for IP sockets. Span kind SHOULD be `INTERNAL`. Corresponding `Activity.OperationName` is `Experimental.System.Net.Sockets.Connect`, `ActivitySource` name - `Experimental.System.Net.Sockets`. Added in .NET 9. - + @@ -175,10 +234,10 @@ Added in .NET 9. | [`error.type`](/docs/attributes-registry/error.md) | string | Socket error code. [1] | `connection_refused`; `address_not_available` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.address`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.transport`](/docs/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`; `udp`; `unix` | `Recommended` [4] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | `Recommended` if `network.peer.address` is an IP address. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp`; `unix` | `Recommended` [4] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.type`](/docs/attributes-registry/network.md) | string | [OSI network layer](https://wikipedia.org/wiki/Network_layer) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | `Recommended` if `network.peer.address` is an IP address. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1]:** The following errors codes are reported: +**[1] `error.type`:** The following errors codes are reported: - `network_down` - `address_already_in_use` @@ -201,19 +260,19 @@ Added in .NET 9. See socket errors on [Windows](https://learn.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect#return-value) and [Linux](https://man7.org/linux/man-pages/man2/connect.2.html) for more details. -**[2]:** If port is supported for the socket address family. +**[2] `network.peer.port`:** If port is supported for the socket address family. -**[3]:** The value SHOULD be normalized to lowercase. +**[3] `network.transport`:** 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]:** If value is not `tcp`. When missing, the value is assumed to be `tcp`. - -**[5]:** The value SHOULD be normalized to lowercase. +**[4] `network.transport`:** If value is not `tcp`. When missing, the value is assumed to be `tcp`. +**[5] `network.type`:** The value SHOULD be normalized to lowercase. +--- `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. @@ -221,16 +280,19 @@ different processes could be listening on TCP port 12345 and UDP port 12345. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- `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 | Stability | |---|---|---| | `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `quic` | QUIC | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- `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. @@ -239,70 +301,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `ipv4` | IPv4 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `ipv6` | IPv6 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - - - - - - - -## DNS resolution - -**Status**: [Experimental][DocumentStatus] - -The span describes DNS lookups performed with one of the methods on [System.Net.Dns](https://learn.microsoft.com/dotnet/api/system.net.dns) class. -DNS lookup duration is also reported by [`dns.lookup.duration` metric](/docs/dotnet/dotnet-dns-metrics.md#metric-dnslookupduration). - -DNS spans track logical operations rather than physical DNS calls and the actual behavior depends on the resolver implementation which could be changed in the future versions of .NET. -.NET 9 uses OS DNS resolver which may do zero or more physical lookups for one API call. - -When *DNS* span is reported along with *HTTP connection setup* and *Socket connect* span, the *DNS* span becomes a child of *HTTP connection setup* -and a sibling of *Socket connect*. - -DNS spans are reported for both lookups and reverse lookups. - -Lookup (IP addresses from host name) span name SHOULD be `DNS lookup {dns.question.name}`. -Reverse lookup (host names from IP address) span name SHOULD be `DNS reverse lookup {dns.question.name}`. -Span kind SHOULD be `INTERNAL`. - -Corresponding `Activity.OperationName` is `Experimental.System.Net.NameResolution.DnsLookup`, `ActivitySource` name - `Experimental.System.Net.NameResolution`. -Added in .NET 9 - - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | Error code returned by the DNS resolver. [1] | `host_not_found`; `try_again` | `Conditionally Required` if and only if an error has occurred. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`dns.answers`](/docs/attributes-registry/dns.md) | 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"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`dns.question.name`](/docs/attributes-registry/dns.md) | string | The domain name or an IP address being queried. [2] | `www.example.com`; `opentelemetry.io` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** The following errors are reported: - -- `host_not_found` -- `try_again` -- `no_recovery` -- `address_family_not_supported` -- the full exception type name - -See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) for more details. - -**[2]:** 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. - - - -`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 | Stability | -|---|---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - - - @@ -317,12 +315,12 @@ The span describes TLS client or server handshake performed with [System.Net.Sec Span name SHOULD be `TLS client handshake {server.address}` when authenticating on the client side and `TLS server handshake` when authenticating the server. Span kind SHOULD be `INTERNAL` in both cases. -When *TLS* span is reported for client-side authentication along with *HTTP connection setup* and *Socket connect* span, the *TLS* span becomes a child of *HTTP connection setup*. +When *TLS* span is reported for client-side authentication along with *HTTP connection setup* and *socket connect* span, the *TLS* span becomes a child of *HTTP connection setup*. Corresponding `Activity.OperationName` is `Experimental.System.Net.Security.TlsHandshake`, `ActivitySource` name - `Experimental.System.Net.Security`. Added in .NET 9. - + @@ -336,9 +334,9 @@ Added in .NET 9. | [`tls.protocol.name`](/docs/attributes-registry/tls.md) | 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` | `Recommended` when available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`tls.protocol.version`](/docs/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` when available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** 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. - +**[1] `server.address`:** 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. +--- `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. @@ -346,6 +344,7 @@ Added in .NET 9. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- `tls.protocol.name` 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. @@ -354,8 +353,6 @@ Added in .NET 9. | `ssl` | ssl | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tls` | tls | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - @@ -379,7 +376,7 @@ connection was created. There was no cached DNS record for the host. ``` <----------------------- GET / (trace=t1, span=s1, link_to=t2,s3) --------------------------------> -<--------- wait_for_connection (trace=t1, span=s2) ----------> +<--------- HTTP wait_for_connection (trace=t1, span=s2) ----------> <--------- HTTP connection_setup (trace=t2, span=s3) --------> @@ -396,7 +393,7 @@ served other requests in the queue before it became available for this request. ``` <--------------------- GET / (trace=t1, span=s1) ------------------------------> - <---- wait_for_connection (trace=t1, span=s2, link_to=t2,s3) ----> + <---- HTTP wait_for_connection (trace=t1, span=s2, link_to=t2,s3) ----> <--- HTTP connection_setup - (trace=t2, span=s3) ---> diff --git a/model/dns/registry.yaml b/model/dns/registry.yaml index 0d12ac7016..ed673e8aef 100644 --- a/model/dns/registry.yaml +++ b/model/dns/registry.yaml @@ -16,8 +16,9 @@ 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. - - id: answers + - id: dns.answers type: string[] stability: experimental - brief: The list of resolved IPv4 or IPv6 addresses. - examples: ["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"] + brief: The list of IPv4 or IPv6 addresses resolved during DNS lookup. + examples: + - ["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"] diff --git a/model/trace/dotnet/dotnet-network.yaml b/model/dotnet/network-spans.yaml similarity index 87% rename from model/trace/dotnet/dotnet-network.yaml rename to model/dotnet/network-spans.yaml index 3c41367662..3a64f1f69b 100644 --- a/model/trace/dotnet/dotnet-network.yaml +++ b/model/dotnet/network-spans.yaml @@ -1,7 +1,8 @@ groups: - - id: dotnet.http.request.wait_for_connection + - id: span.dotnet.http.request.wait_for_connection.internal type: span span_kind: internal + stability: experimental brief: 'The span describes the time it takes for HTTP request to obtain a connection to run on.' attributes: - ref: error.type @@ -12,14 +13,18 @@ groups: note: "" examples: ["version_negotiation_error", "System.OperationCanceledException"] - - id: dotnet.http.connection_setup + - id: span.dotnet.http.connection_setup.client type: span span_kind: client + stability: experimental brief: > The span describes the establishment of the HTTP connection. It includes the time it takes to resolve the DNS, establish the socket connection, and perform the TLS handshake. attributes: - ref: network.peer.address + brief: Peer IP address of the socket connection. + note: > + The `network.peer.address` attribute is available only if the connection was successfully established. - ref: server.address - ref: server.port - ref: error.type @@ -31,9 +36,10 @@ groups: examples: ["name_resolution_error", "System.OperationCanceledException"] - ref: url.scheme - - id: dotnet.socket.connect + - id: span.dotnet.socket.connect.client type: span span_kind: client + stability: experimental brief: > The span describes the establishment of the socket connection. attributes: @@ -77,9 +83,10 @@ groups: [Linux](https://man7.org/linux/man-pages/man2/connect.2.html) for more details. examples: ["connection_refused", "address_not_available"] - - id: dotnet.dns.lookup + - id: span.dotnet.dns.lookup.client type: span span_kind: client + stability: experimental brief: > The span describes DNS lookup. attributes: @@ -88,7 +95,7 @@ groups: - ref: dns.answers brief: List of resolved IP addresses (for DNS lookup) or a single element containing domain name (for reverse lookup). - ref: error.type - brief: Error code returned by the DNS resolver. + brief: The error code or exception name returned by [System.Net.Dns](https://learn.microsoft.com/dotnet/api/system.net.dns). requirement_level: conditionally_required: if and only if an error has occurred. note: | @@ -103,9 +110,10 @@ groups: See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) for more details. examples: ["host_not_found", "try_again" ] - - id: dotnet.tls.handshake + - id: span.dotnet.tls.handshake.client type: span span_kind: client + stability: experimental brief: > The span describes TLS handshake. attributes: