Add .NET network + HTTP connection spans

.chloggen/1192.yaml

@@ -0,0 +1,7 @@
+change_type: enhancement
+component: dotnet
+note: >
+  Define .NET-specific network spans for DNS resolution, TLS handshake,
+  and socket connections, along with HTTP-level spans to (optionally) record
+  relationships between HTTP requests and connections.
+issues: [ 1192 ]

.github/CODEOWNERS

@@ -82,7 +82,7 @@
 /model/container/                 @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
 /model/oci/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
 
-# .NET semantic conventions
+# .NET semantic conventions approvers
 /docs/dotnet/                     @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
 /docs/runtime/dotnet-metrics.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver
 /model/aspnetcore/                @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers

docs/attributes-registry/dns.md

@@ -9,6 +9,7 @@ This document defines the shared attributes used to report a DNS query.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
+| <a id="dns-answers" href="#dns-answers">`dns.answers`</a> | string[] | The list of IPv4 or IPv6 addresses resolved during DNS lookup. | `["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]` | ![Development](https://img.shields.io/badge/-development-blue) |
 | <a id="dns-question-name" href="#dns-question-name">`dns.question.name`</a> | string | The name being queried. [1] | `www.example.com`; `opentelemetry.io` | ![Development](https://img.shields.io/badge/-development-blue) |
 
 **[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.

docs/dotnet/README.md

@@ -2,11 +2,13 @@
 linkTitle: .NET
 --->
 
-# Semantic conventions for .NET metrics
+# Semantic conventions for .NET
 
-**Status**: [Stable][DocumentStatus]
+This article documents semantic conventions for metrics and traces emitted by the .NET runtime and individual components in the .NET ecosystem.
 
-This article documents semantic conventions for metrics emitted by the .NET runtime and individual components in the .NET ecosystem.
+The following span are currently supported:
+
+- [HTTP client, DNS, and TLS](dotnet-network-traces.md): Semantic Conventions for HTTP client and connection-related *spans*.
 
 The following metrics are currently supported:
 
@@ -15,5 +17,4 @@ The following metrics are currently supported:
 * [HTTP](dotnet-http-metrics.md): Semantic Conventions for HTTP client and server *metrics*.
 * [Kestrel](dotnet-kestrel-metrics.md): Semantic Conventions for Kestrel web server *metrics*.
 * [SignalR](dotnet-signalr-metrics.md): Semantic Conventions for SignalR server *metrics*.
-
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
+* [Runtime](/docs/runtime/dotnet-metrics.md): Semantic conventions for .NET Runtime *metrics*.

model/dns/registry.yaml

@@ -16,3 +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: dns.answers
+        type: string[]
+        stability: development
+        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"]

model/dotnet/network-spans.yaml

@@ -0,0 +1,204 @@
+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"]