Semantic Conventions for HTTP client and server metrics emitted by .NET

Status: Stable

This article defines semantic conventions for HTTP metrics emitted by .NET components and runtime.

HTTP client

All Http client metrics are reported by the System.Net.Http meter.

Metric: http.client.request.duration

Client request duration measures the time it takes to receive response headers and doesn’t include time to read the response body.

This metric follows the common http.client.request.duration definition.

Notes:

  • Meter name is System.Net.Http
  • Metric added in .NET 8.0
  • When the error.type attribute is reported, it contains one of HTTP Request errors in snake_case, a full exception type, or a string representation of received status code.
  • network.protocol.name is not reported and should always be assumed to match http.
  • server.port is not reported when it matches a default one for provided scheme (443 for https and 80 for http)
  • url.scheme is always reported.

Metric: http.client.open_connections

NameInstrument TypeUnit (UCUM)Description
http.client.open_connectionsUpDownCounter{connection}Number of outbound HTTP connections that are currently active or idle on the client. [1]

[1]: Meter name: System.Net.Http; Added in: .NET 8.0

AttributeTypeDescriptionExamplesRequirement Level
http.connection.statestringState of the HTTP connection in the HTTP connection pool.active; idleRequired
network.peer.addressstringRemote IP address of the socket connection.10.1.2.80Recommended
network.protocol.versionstringHTTP protocol version of the connection in the connection pool. [1]1.1; 2; 3Recommended
server.addressstringHost identifier of the “URI origin” HTTP request is sent to. [2]example.com; 10.1.2.80; /tmp/my.sockRequired
server.portintPort identifier of the “URI origin” HTTP request is sent to. [3]80; 8080; 443Conditionally Required: [4]
url.schemestringThe URI scheme component identifying the used protocol.http; https; ftpRecommended

[1]: HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version 1.1. So, the network.protocol.version value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests.

[2]: If an HTTP client request is explicitly made to an IP address, e.g. http://x.x.x.x:8080, then server.address SHOULD be the IP address x.x.x.x. A DNS lookup SHOULD NOT be used.

[3]: 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.

[4]: If not the default (80 for http scheme, 443 for https).

http.connection.state MUST be one of the following:

ValueDescription
activeactive state.
idleidle state.

Metric: http.client.connection.duration

this metric SHOULD be specified with ExplicitBucketBoundaries of [ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ].

NameInstrument TypeUnit (UCUM)Description
http.client.connection.durationHistogramsThe duration of the successfully established outbound HTTP connections. [1]

[1]: Meter name: System.Net.Http; Added in: .NET 8.0

AttributeTypeDescriptionExamplesRequirement Level
network.peer.addressstringPeer address of the network connection - IP address or Unix domain socket name.10.1.2.80; /tmp/my.sockRecommended
network.protocol.versionstringHTTP protocol version of the connection in the connection pool. [1]1.1; 2; 3Recommended
server.addressstringHost identifier of the “URI origin” HTTP request is sent to. [2]example.com; 10.1.2.80; /tmp/my.sockRequired
server.portintPort identifier of the “URI origin” HTTP request is sent to. [3]80; 8080; 443Conditionally Required: [4]
url.schemestringThe URI scheme component identifying the used protocol.http; https; ftpRecommended

[1]: HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version 1.1. So, the network.protocol.version value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests.

[2]: If an HTTP client request is explicitly made to an IP address, e.g. http://x.x.x.x:8080, then server.address SHOULD be the IP address x.x.x.x. A DNS lookup SHOULD NOT be used.

[3]: 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.

[4]: If not the default (80 for http scheme, 443 for https).

Metric: http.client.request.time_in_queue

this metric SHOULD be specified with ExplicitBucketBoundaries of [ 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 ].

NameInstrument TypeUnit (UCUM)Description
http.client.request.time_in_queueHistogramsThe amount of time requests spent on a queue waiting for an available connection. [1]

[1]: Meter name: System.Net.Http; Added in: .NET 8.0

AttributeTypeDescriptionExamplesRequirement Level
http.request.methodstringHTTP request method. [1]GET; POST; HEADRecommended
network.protocol.versionstringHTTP protocol version of the connection in the connection pool. [2]1.1; 2; 3Recommended
server.addressstringHost identifier of the “URI origin” HTTP request is sent to. [3]example.com; 10.1.2.80; /tmp/my.sockRequired
server.portintPort identifier of the “URI origin” HTTP request is sent to. [4]80; 8080; 443Conditionally Required: [5]
url.schemestringThe URI scheme component identifying the used protocol.http; https; ftpRecommended

[1]: HTTP request method value is one of the “known” methods listed in RFC9110 and the PATCH method defined in RFC5789. If the HTTP request method isn’t known, it sets the http.request.method attribute to _OTHER. It’s not possible at the moment to override the list of known HTTP methods.

[2]: HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version 1.1. So, the network.protocol.version value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests.

[3]: If an HTTP client request is explicitly made to an IP address, e.g. http://x.x.x.x:8080, then server.address SHOULD be the IP address x.x.x.x. A DNS lookup SHOULD NOT be used.

[4]: 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.

[5]: If not the default (80 for http scheme, 443 for https).

http.request.method 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.

ValueDescription
CONNECTCONNECT method.
DELETEDELETE method.
GETGET method.
HEADHEAD method.
OPTIONSOPTIONS method.
PATCHPATCH method.
POSTPOST method.
PUTPUT method.
TRACETRACE method.
_OTHERAny HTTP method that the instrumentation has no prior knowledge of.

Metric: http.client.active_requests

NameInstrument TypeUnit (UCUM)Description
http.client.active_requestsUpDownCounter{request}Number of active HTTP requests. [1]

[1]: Meter name: System.Net.Http; Added in: .NET 8.0

AttributeTypeDescriptionExamplesRequirement Level
http.request.methodstringHTTP request method. [1]GET; POST; HEADRecommended
server.addressstringHost identifier of the “URI origin” HTTP request is sent to. [2]example.com; 10.1.2.80; /tmp/my.sockRequired
server.portintPort identifier of the “URI origin” HTTP request is sent to. [3]80; 8080; 443Conditionally Required: [4]
url.schemestringThe URI scheme component identifying the used protocol.http; https; ftpRecommended

[1]: HTTP request method value is one of the “known” methods listed in RFC9110 and the PATCH method defined in RFC5789. If the HTTP request method isn’t known, it sets the http.request.method attribute to _OTHER. It’s not possible at the moment to override the list of known HTTP methods.

[2]: If an HTTP client request is explicitly made to an IP address, e.g. http://x.x.x.x:8080, then server.address SHOULD be the IP address x.x.x.x. A DNS lookup SHOULD NOT be used.

[3]: 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.

[4]: If not the default (80 for http scheme, 443 for https).

http.request.method 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.

ValueDescription
CONNECTCONNECT method.
DELETEDELETE method.
GETGET method.
HEADHEAD method.
OPTIONSOPTIONS method.
PATCHPATCH method.
POSTPOST method.
PUTPUT method.
TRACETRACE method.
_OTHERAny HTTP method that the instrumentation has no prior knowledge of.

HTTP server

All HTTP server metrics are reported by the Microsoft.AspNetCore.Hosting meter.

Metric: http.server.request.duration

Measures time to last byte. This metric follows the common http.server.request.duration definition.

Notes:

  • Meter name is Microsoft.AspNetCore.Hosting

  • Metric added in ASP.NET Core 8.0

  • Opt-in server.address and server.port attributes are not reported

  • Additional attributes:

    • The aspnetcore.request.is_unhandled boolean attribute is reported when the request was not handled by the application pipeline. It’s skipped otherwise.

Metric: http.server.active_requests

Measures the number of HTTP requests that are currently active on the server. This metric follows the common http.server.active_requests definition.

Notes:

  • Meter name is Microsoft.AspNetCore.Hosting
  • Opt-in server.address and server.port attributes are not reported
  • Metric added in ASP.NET Core 8.0