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

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.active_connections	UpDownCounter	{connection}	Number of connections that are currently active on the server. [1]

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

Attribute	Type	Description	Examples	Requirement Level	Stability
network.transport	string	OSI transport layer or inter-process communication method. [1]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [2]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [4]	80; 8080; 443	Recommended

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

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

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

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.connection.duration	Histogram	s	The duration of connections on the server. [1]

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

Attribute	Type	Description	Examples	Requirement Level	Stability
error.type	string	The full name of exception type. [1]	System.OperationCanceledException; Contoso.MyException	Conditionally Required if and only if an error has occurred.
network.protocol.name	string	OSI application layer or non-OSI equivalent. [2]	http; web_sockets	Recommended
network.protocol.version	string	The actual version of the protocol used for network communication. [3]	1.1; 2	Recommended
network.transport	string	OSI transport layer or inter-process communication method. [4]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [5]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [7]	80; 8080; 443	Recommended
tls.protocol.version	string	Numeric part of the version parsed from the original string of the negotiated SSL/TLS protocol version	1.2; 3	Recommended

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

Value	Description	Stability
_OTHER	A fallback error value to be used when the instrumentation doesn’t define a custom value.

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.

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

Metric: kestrel.rejected_connections

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.rejected_connections	Counter	{connection}	Number of connections rejected by the server. [1]

[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

Attribute	Type	Description	Examples	Requirement Level	Stability
network.transport	string	OSI transport layer or inter-process communication method. [1]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [2]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [4]	80; 8080; 443	Recommended

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

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

Metric: kestrel.queued_connections

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.queued_connections	UpDownCounter	{connection}	Number of connections that are currently queued and are waiting to start. [1]

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

Attribute	Type	Description	Examples	Requirement Level	Stability
network.transport	string	OSI transport layer or inter-process communication method. [1]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [2]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [4]	80; 8080; 443	Recommended

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

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

Metric: kestrel.queued_requests

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.queued_requests	UpDownCounter	{request}	Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. [1]

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

Attribute	Type	Description	Examples	Requirement Level	Stability
network.protocol.name	string	OSI application layer or non-OSI equivalent. [1]	http; web_sockets	Recommended
network.protocol.version	string	The actual version of the protocol used for network communication. [2]	1.1; 2	Recommended
network.transport	string	OSI transport layer or inter-process communication method. [3]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [4]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [6]	80; 8080; 443	Recommended

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

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

Metric: kestrel.upgraded_connections

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.upgraded_connections	UpDownCounter	{connection}	Number of connections that are currently upgraded (WebSockets). . [1]

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

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

Attribute	Type	Description	Examples	Requirement Level	Stability
network.transport	string	OSI transport layer or inter-process communication method. [1]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [2]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [4]	80; 8080; 443	Recommended

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

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

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

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.tls_handshake.duration	Histogram	s	The duration of TLS handshakes on the server. [1]

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

Attribute	Type	Description	Examples	Requirement Level	Stability
error.type	string	The full name of exception type. [1]	System.OperationCanceledException; Contoso.MyException	Conditionally Required if and only if an error has occurred.
network.transport	string	OSI transport layer or inter-process communication method. [2]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [3]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [5]	80; 8080; 443	Recommended
tls.protocol.version	string	Numeric part of the version parsed from the original string of the negotiated SSL/TLS protocol version	1.2; 3	Recommended

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

Value	Description	Stability
_OTHER	A fallback error value to be used when the instrumentation doesn’t define a custom value.

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.

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

Metric: kestrel.active_tls_handshakes

Name	Instrument Type	Unit (UCUM)	Description	Stability
kestrel.active_tls_handshakes	UpDownCounter	{handshake}	Number of TLS handshakes that are currently in progress on the server. [1]

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

Attribute	Type	Description	Examples	Requirement Level	Stability
network.transport	string	OSI transport layer or inter-process communication method. [1]	tcp; unix	Recommended
network.type	string	OSI network layer or non-OSI equivalent. [2]	ipv4; ipv6	Recommended if the transport is tcp or udp
server.address	string	Server 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.sock	Recommended
server.port	int	Server port number. [4]	80; 8080; 443	Recommended

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

Value	Description	Stability
tcp	TCP
udp	UDP
pipe	Named or anonymous pipe.
unix	Unix domain socket

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.

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6