Skip to content

Latest commit

 

History

History
260 lines (185 loc) · 15.7 KB

dotnet-http-metrics.md

File metadata and controls

260 lines (185 loc) · 15.7 KB
Raw

Semantic Conventions for HTTP-relevant metrics emitted by .NET

Status: Experimental, Feature-freeze

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

HTTP client

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

Metric: http.client.request.duration

Client request duration measures time it takes to receive response headers and does not include time to read response body.

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

Notes:

  • Meter name is System.Net.Http
  • Metric added in .NET 8.0
  • When error.type attribute is reported, it contains one of HTTP Request errors, a full exception type, or a string representation of received status code.
  • The url.scheme attribute is reported.

Metric: http.client.open_connections

Name Instrument Type Unit (UCUM) Description
http.client.open_connections UpDownCounter {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

Attribute Type Description Examples Requirement Level
http.connection.state string State of HTTP connection in the HTTP connection pool. active; idle Required
network.protocol.version string Version of the application layer protocol used. See note below. [1] 1.1; 2 Recommended
server.address string Host identifier of the "URI origin" HTTP request is sent to. [2] example.com Required
server.port int Port identifier of the "URI origin" HTTP request is sent to. [3] 80; 8080; 443 Conditionally Required: [4]
server.socket.address string Server address of the socket connection - IP address or Unix domain socket name. [5] 10.5.3.2 Recommended: If different than server.address.
url.scheme string The URI scheme component identifying the used protocol. http; https; ftp Recommended

[1]: network.protocol.version refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of 0.27.2, but sends HTTP version 1.1, this attribute should be set to 1.1.

[2]: Determined by using the first of the following that applies

  • Host identifier of the request target if it's sent in absolute-form
  • Host identifier of the Host header

[3]: When request target is absolute URI, server.port MUST match URI port identifier, otherwise it MUST match Host header port identifier.

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

[5]: When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address.

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

Value Description
active active state.
idle idle state.

Metric: http.client.connection.duration

Name Instrument Type Unit (UCUM) Description
http.client.connection.duration Histogram s The duration of successfully established outbound HTTP connections. [1]

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

Attribute Type Description Examples Requirement Level
network.protocol.version string Version of the application layer protocol used. See note below. [1] 1.1; 2 Recommended
server.address string Host identifier of the "URI origin" HTTP request is sent to. [2] example.com Required
server.port int Port identifier of the "URI origin" HTTP request is sent to. [3] 80; 8080; 443 Conditionally Required: [4]
server.socket.address string Server address of the socket connection - IP address or Unix domain socket name. [5] 10.5.3.2 Recommended: If different than server.address.
url.scheme string The URI scheme component identifying the used protocol. http; https; ftp Recommended

[1]: network.protocol.version refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of 0.27.2, but sends HTTP version 1.1, this attribute should be set to 1.1.

[2]: Determined by using the first of the following that applies

  • Host identifier of the request target if it's sent in absolute-form
  • Host identifier of the Host header

[3]: When request target is absolute URI, server.port MUST match URI port identifier, otherwise it MUST match Host header port identifier.

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

[5]: When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address.

Metric: http.client.request.time_in_queue

Name Instrument Type Unit (UCUM) Description
http.client.request.time_in_queue Histogram s The 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

Attribute Type Description Examples Requirement Level
http.request.method string HTTP request method. [1] GET; POST; HEAD Required
network.protocol.version string Version of the application layer protocol used. See note below. [2] 1.1; 2 Recommended
server.address string Host identifier of the "URI origin" HTTP request is sent to. [3] example.com Required
server.port int Port identifier of the "URI origin" HTTP request is sent to. [4] 80; 8080; 443 Conditionally Required: [5]
url.scheme string The URI scheme component identifying the used protocol. http; https; ftp Recommended

[1]: HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in RFC9110 and the PATCH method defined in RFC5789.

If the HTTP request method is not known to instrumentation, it MUST set the http.request.method attribute to _OTHER.

If the HTTP instrumentation could end up converting valid HTTP request methods to _OTHER, then it MUST provide a way to override the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods (this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).

HTTP method names are case-sensitive and http.request.method attribute value MUST match a known HTTP method name exactly. Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set http.request.method_original to the original value.

[2]: network.protocol.version refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of 0.27.2, but sends HTTP version 1.1, this attribute should be set to 1.1.

[3]: Determined by using the first of the following that applies

  • Host identifier of the request target if it's sent in absolute-form
  • Host identifier of the Host header

[4]: When request target is absolute URI, server.port MUST match URI port identifier, otherwise it MUST match Host header port identifier.

[5]: If not 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.

Value Description
CONNECT CONNECT method.
DELETE DELETE method.
GET GET method.
HEAD HEAD method.
OPTIONS OPTIONS method.
PATCH PATCH method.
POST POST method.
PUT PUT method.
TRACE TRACE method.
_OTHER Any HTTP method that the instrumentation has no prior knowledge of.

Metric: http.client.active_requests

Name Instrument Type Unit (UCUM) Description
http.client.active_requests UpDownCounter {request} Number of active HTTP requests. [1]

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

Attribute Type Description Examples Requirement Level
http.request.method string HTTP request method. [1] GET; POST; HEAD Required
network.protocol.version string Version of the application layer protocol used. See note below. [2] 1.1; 2 Recommended
server.address string Host identifier of the "URI origin" HTTP request is sent to. [3] example.com Required
server.port int Port identifier of the "URI origin" HTTP request is sent to. [4] 80; 8080; 443 Conditionally Required: [5]
url.scheme string The URI scheme component identifying the used protocol. http; https; ftp Recommended

[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 is not known, it sets the http.request.method attribute to _OTHER.

It is not possible at the moment to override the list of known HTTP methods.

[2]: network.protocol.version refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of 0.27.2, but sends HTTP version 1.1, this attribute should be set to 1.1.

[3]: Determined by using the first of the following that applies

  • Host identifier of the request target if it's sent in absolute-form
  • Host identifier of the Host header

[4]: When request target is absolute URI, server.port MUST match URI port identifier, otherwise it MUST match Host header port identifier.

[5]: If not 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.

Value Description
CONNECT CONNECT method.
DELETE DELETE method.
GET GET method.
HEAD HEAD method.
OPTIONS OPTIONS method.
PATCH PATCH method.
POST POST method.
PUT PUT method.
TRACE TRACE method.
_OTHER Any HTTP method that the instrumentation has no prior knowledge of.

HTTP server

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

Metric: http.server.request.duration

Measures time to last byte. This metric follows 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.
    • The exception.type string attribute is reported if and only if the request ended with an error. It includes full exception type.

Metric: http.server.active_requests

Measures the number of HTTP requests that are currently active on the server. This metric follows 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