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

@@ -68,7 +68,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

@@ -12,6 +12,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"]` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-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

@@ -5,11 +5,13 @@ path_base_for_github_subdir:
   to: dotnet/README.md
 --->
 
-# 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:
 
@@ -18,5 +20,3 @@ 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

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: experimental
+        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,135 @@
+groups:
+  - 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
+        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.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 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.client
+    type: span
+    span_kind: client
+    stability: experimental
+    brief: >
+      The span describes the establishment of the socket connection.
+    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.client
+    type: span
+    span_kind: client
+    stability: experimental
+    brief: >
+      The span describes DNS lookup.
+    attributes:
+      - ref: dns.question.name
+        brief: The domain name or an IP address being queried.
+      - 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: 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.client
+    type: span
+    span_kind: client
+    stability: experimental
+    brief: >
+      The span describes TLS handshake.
+    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"]