205 lines
10 KiB
YAML
205 lines
10 KiB
YAML
groups:
|
|
- id: span.dotnet.http.request.wait_for_connection.internal
|
|
type: span
|
|
stability: development
|
|
span_kind: internal
|
|
brief: The span describes the time it takes for the HTTP request to obtain a connection from the connection pool.
|
|
note: |
|
|
The span is reported only if there was no connection readily available when request has started.
|
|
It's reported as a child of *HTTP client request* span.
|
|
|
|
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*](/docs/dotnet/dotnet-network-traces.md#http-connection-setup) span.
|
|
|
|
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).
|
|
|
|
Corresponding `Activity.OperationName` is `Experimental.System.Net.Http.Connections.WaitForConnection`, `ActivitySource` name - `Experimental.System.Net.Http`.
|
|
Added in .NET 9.
|
|
|
|
**Span name** SHOULD be `HTTP wait_for_connection {server.address}:{server.port}`.
|
|
attributes:
|
|
- ref: error.type
|
|
requirement_level:
|
|
conditionally_required: if and only if an error has occurred.
|
|
brief: >
|
|
One of the [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror) in snake_case, or a full exception type.
|
|
note: ""
|
|
examples: ["version_negotiation_error", "System.OperationCanceledException"]
|
|
|
|
- id: span.dotnet.http.connection_setup.internal
|
|
type: span
|
|
stability: development
|
|
span_kind: internal
|
|
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.
|
|
note: |
|
|
There is no parent-child relationship between the [*HTTP client request*](/docs/dotnet/dotnet-network-traces.md#http-client-request) and the
|
|
[*HTTP connection setup*]/docs/dotnet/dotnet-network-traces.md(/docs/dotnet/dotnet-network-traces.md#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*](/docs/dotnet/dotnet-network-traces.md#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*](/docs/dotnet/dotnet-network-traces.md#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.
|
|
|
|
**Span name** SHOULD be `HTTP connection_setup {server.address}:{server.port}`.
|
|
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 and only for IP sockets.
|
|
- ref: server.address
|
|
- ref: server.port
|
|
- ref: error.type
|
|
brief: >
|
|
One of the [HTTP Request errors](https://learn.microsoft.com/dotnet/api/system.net.http.httprequesterror) in snake_case, or a full exception type.
|
|
note: ""
|
|
requirement_level:
|
|
conditionally_required: if and only if an error has occurred.
|
|
examples: ["name_resolution_error", "System.OperationCanceledException"]
|
|
- ref: url.scheme
|
|
|
|
- id: span.dotnet.socket.connect.internal
|
|
type: span
|
|
stability: development
|
|
span_kind: internal
|
|
brief: >
|
|
The span describes the establishment of the socket connection.
|
|
note: |
|
|
It's different from [*HTTP connection setup*](/docs/dotnet/dotnet-network-traces.md#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.
|
|
|
|
Corresponding `Activity.OperationName` is `Experimental.System.Net.Sockets.Connect`, `ActivitySource` name - `Experimental.System.Net.Sockets`.
|
|
Added in .NET 9.
|
|
|
|
**Span name** SHOULD be `socket connect {network.peer.address}:{network.peer.port}` when socket address family has a
|
|
notion of port and `socket connect {network.peer.address}`
|
|
otherwise.
|
|
attributes:
|
|
- ref: network.peer.port
|
|
requirement_level:
|
|
recommended: If port is supported for the socket address family.
|
|
- ref: network.peer.address
|
|
- ref: network.type
|
|
requirement_level:
|
|
recommended: if `network.peer.address` is an IP address.
|
|
- ref: network.transport
|
|
examples: ['tcp', 'udp', 'unix']
|
|
requirement_level:
|
|
recommended: If value is not `tcp`. When missing, the value is assumed to be `tcp`.
|
|
- ref: error.type
|
|
brief: "Socket error code."
|
|
requirement_level:
|
|
conditionally_required: if and only if an error has occurred.
|
|
note: |
|
|
The following errors codes are reported:
|
|
|
|
- `network_down`
|
|
- `address_already_in_use`
|
|
- `interrupted`
|
|
- `in_progress`
|
|
- `already_in_progress`
|
|
- `address_not_available`
|
|
- `address_family_not_supported`
|
|
- `connection_refused`
|
|
- `fault`
|
|
- `invalid_argument`
|
|
- `is_connected`
|
|
- `network_unreachable`
|
|
- `host_unreachable`
|
|
- `no_buffer_space_available`
|
|
- `timed_out`
|
|
- `access_denied`
|
|
- `protocol_type`
|
|
|
|
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.
|
|
examples: ["connection_refused", "address_not_available"]
|
|
|
|
- id: span.dotnet.dns.lookup.internal
|
|
type: span
|
|
stability: development
|
|
span_kind: internal
|
|
brief: >
|
|
The span describes DNS lookup or reverse lookup performed with one of the methods
|
|
on [System.Net.Dns](https://learn.microsoft.com/dotnet/api/system.net.dns) class.
|
|
note: |
|
|
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 lookup duration is also reported by [`dns.lookup.duration` metric](/docs/dotnet/dotnet-dns-metrics.md#metric-dnslookupduration).
|
|
|
|
Corresponding `Activity.OperationName` is `Experimental.System.Net.NameResolution.DnsLookup`, `ActivitySource` name - `Experimental.System.Net.NameResolution`.
|
|
Added in .NET 9.
|
|
|
|
**Span name** SHOULD be `DNS lookup {dns.question.name}` for DNS lookup (IP addresses from host name)
|
|
and `DNS reverse lookup {dns.question.name}` for reverse lookup (host names from IP address).
|
|
attributes:
|
|
- ref: dns.question.name
|
|
brief: The domain name or an IP address being queried.
|
|
note: ""
|
|
- ref: dns.answers
|
|
brief: List of resolved IP addresses (for DNS lookup) or a single element containing domain name (for reverse lookup).
|
|
requirement_level:
|
|
recommended: if DNS lookup was successful.
|
|
- ref: error.type
|
|
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: |
|
|
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.
|
|
examples: ["host_not_found", "try_again" ]
|
|
|
|
- id: span.dotnet.tls.handshake.internal
|
|
type: span
|
|
span_kind: internal
|
|
stability: development
|
|
brief: >
|
|
The span describes TLS client or server handshake performed with [System.Net.Security.SslStream](https://learn.microsoft.com/dotnet/api/system.net.security.sslstream).
|
|
note: |
|
|
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.
|
|
|
|
**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.
|
|
attributes:
|
|
- ref: tls.protocol.name
|
|
requirement_level:
|
|
recommended: when available
|
|
- ref: tls.protocol.version
|
|
requirement_level:
|
|
recommended: when available
|
|
- ref: server.address
|
|
brief: The [server name indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) used in the 'Client Hello' message during TLS handshake.
|
|
requirement_level:
|
|
recommended: when authenticating the client.
|
|
examples: ["opentelemetry.io", "example.com"]
|
|
- ref: error.type
|
|
requirement_level:
|
|
conditionally_required: if and only if an error has occurred.
|
|
note: ""
|
|
examples: ["System.Net.Security.Authentication.AuthenticationException", "System.OperationCanceledException"]
|