Semantic Conventions for Kestrel web server metrics

Status: Stable

This article defines semantic conventions for Kestrel web server.

Kestrel endpoint

Kestrel endpoint is represented with System.Net.EndPoint class, which does not always provide information about server address or port.

Instrumentation supports IPEndPoint, UnixDomainSocketEndPoint, and NamedPipeEndPoint and sets the server.address, server.port (for IP endpoint), network.type, and network.transport attributes from the corresponding endpoint on Kestrel metrics.

In case instrumentation does not recognize EndPoint implementation, it sets the server.address attribute to endpoint.ToString() value and network.transport value to corresponding endpoint.AddressFamily property.

Metric: kestrel.active_connections

NameInstrument TypeUnit (UCUM)DescriptionStability
kestrel.active_connectionsUpDownCounter{connection}Number of connections that are currently active on the server. [1]Stable

[1]: Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
network.transportstringOSI transport layer or inter-process communication method. [1]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [2]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [4]80; 8080; 443RecommendedStable

[1]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[2]: The value SHOULD be normalized to lowercase.

[3]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

[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.

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

Metric: kestrel.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)DescriptionStability
kestrel.connection.durationHistogramsThe duration of connections on the server. [1]Stable

[1]: Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
error.typestringThe full name of exception type. [1]System.OperationCanceledException; Contoso.MyExceptionConditionally Required if and only if an error has occurred.Stable
network.protocol.namestringOSI application layer or non-OSI equivalent. [2]http; web_socketsRecommendedStable
network.protocol.versionstringThe actual version of the protocol used for network communication. [3]1.1; 2RecommendedStable
network.transportstringOSI transport layer or inter-process communication method. [4]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [5]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [7]80; 8080; 443RecommendedStable
tls.protocol.versionstringNumeric part of the version parsed from the original string of the negotiated SSL/TLS protocol version1.2; 3RecommendedExperimental

[1]: Captures the exception type when a connection fails.

[2]: The value SHOULD be normalized to lowercase.

[3]: If protocol version is subject to negotiation (for example using ALPN), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.

[4]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[5]: The value SHOULD be normalized to lowercase.

[6]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

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

error.type 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.

ValueDescriptionStability
_OTHERA fallback error value to be used when the instrumentation doesn’t define a custom value.Stable

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

Metric: kestrel.rejected_connections

NameInstrument TypeUnit (UCUM)DescriptionStability
kestrel.rejected_connectionsCounter{connection}Number of connections rejected by the server. [1]Stable

[1]: Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
network.transportstringOSI transport layer or inter-process communication method. [1]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [2]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [4]80; 8080; 443RecommendedStable

[1]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[2]: The value SHOULD be normalized to lowercase.

[3]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

[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.

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

Metric: kestrel.queued_connections

NameInstrument TypeUnit (UCUM)DescriptionStability
kestrel.queued_connectionsUpDownCounter{connection}Number of connections that are currently queued and are waiting to start. [1]Stable

[1]: Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
network.transportstringOSI transport layer or inter-process communication method. [1]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [2]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [4]80; 8080; 443RecommendedStable

[1]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[2]: The value SHOULD be normalized to lowercase.

[3]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

[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.

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

Metric: kestrel.queued_requests

NameInstrument TypeUnit (UCUM)DescriptionStability
kestrel.queued_requestsUpDownCounter{request}Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. [1]Stable

[1]: Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
network.protocol.namestringOSI application layer or non-OSI equivalent. [1]http; web_socketsRecommendedStable
network.protocol.versionstringThe actual version of the protocol used for network communication. [2]1.1; 2RecommendedStable
network.transportstringOSI transport layer or inter-process communication method. [3]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [4]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [6]80; 8080; 443RecommendedStable

[1]: The value SHOULD be normalized to lowercase.

[2]: If protocol version is subject to negotiation (for example using ALPN), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.

[3]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[4]: The value SHOULD be normalized to lowercase.

[5]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

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

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

Metric: kestrel.upgraded_connections

NameInstrument TypeUnit (UCUM)DescriptionStability
kestrel.upgraded_connectionsUpDownCounter{connection}Number of connections that are currently upgraded (WebSockets). . [1]Stable

[1]: The counter only tracks HTTP/1.1 connections.

Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
network.transportstringOSI transport layer or inter-process communication method. [1]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [2]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [4]80; 8080; 443RecommendedStable

[1]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[2]: The value SHOULD be normalized to lowercase.

[3]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

[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.

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

Metric: kestrel.tls_handshake.duration

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)DescriptionStability
kestrel.tls_handshake.durationHistogramsThe duration of TLS handshakes on the server. [1]Stable

[1]: Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
error.typestringThe full name of exception type. [1]System.OperationCanceledException; Contoso.MyExceptionConditionally Required if and only if an error has occurred.Stable
network.transportstringOSI transport layer or inter-process communication method. [2]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [3]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [5]80; 8080; 443RecommendedStable
tls.protocol.versionstringNumeric part of the version parsed from the original string of the negotiated SSL/TLS protocol version1.2; 3RecommendedExperimental

[1]: Captures the exception type when a TLS handshake fails.

[2]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[3]: The value SHOULD be normalized to lowercase.

[4]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

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

error.type 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.

ValueDescriptionStability
_OTHERA fallback error value to be used when the instrumentation doesn’t define a custom value.Stable

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

Metric: kestrel.active_tls_handshakes

NameInstrument TypeUnit (UCUM)DescriptionStability
kestrel.active_tls_handshakesUpDownCounter{handshake}Number of TLS handshakes that are currently in progress on the server. [1]Stable

[1]: Meter name: Microsoft.AspNetCore.Server.Kestrel; Added in: ASP.NET Core 8.0

AttributeTypeDescriptionExamplesRequirement LevelStability
network.transportstringOSI transport layer or inter-process communication method. [1]tcp; unixRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [2]ipv4; ipv6Recommended if the transport is tcp or udpStable
server.addressstringServer domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3]example.com; 10.1.2.80; /tmp/my.sockRecommendedStable
server.portintServer port number. [4]80; 8080; 443RecommendedStable

[1]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[2]: The value SHOULD be normalized to lowercase.

[3]: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.

[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.

network.transport 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.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type 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.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable