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] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[3] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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] error.type: Starting from .NET 9, Kestrel kestrel.connection.duration metric reports the following errors types when a corresponding error occurs:

Value	Description	Stability
aborted_by_app	The HTTP/1.1 connection was aborted when app code aborted an HTTP request with HttpContext.Abort().
app_shutdown_timeout	The connection was aborted during app shutdown. During shutdown, the server stops accepting new connections and HTTP requests, and it is given time for active requests to complete. If the app shutdown timeout is exceeded, all remaining connections are aborted.
closed_critical_stream	A critical control stream for an HTTP/3 connection was closed.
connection_reset	The connection was reset while there were active HTTP/2 or HTTP/3 streams on the connection.
error_after_starting_response	An error such as an unhandled application exception or invalid request body occurred after the response was started, causing an abort of the HTTP/1.1 connection.
error_reading_headers	An error occurred when decoding HPACK headers in an HTTP/2 HEADERS frame.
error_writing_headers	An error occurred when encoding HPACK headers in an HTTP/2 HEADERS frame.
flow_control_queue_size_exceeded	The connection exceeded the outgoing flow control maximum queue size and was closed with INTERNAL_ERROR. This can be caused by an excessive number of HTTP/2 stream resets. For more information, see Microsoft Security Advisory CVE-2023-44487.
flow_control_window_exceeded	The client sent more data than allowed by the current flow-control window.
frame_after_stream_close	An HTTP/2 frame was received on a closed stream.
insufficient_tls_version	The connection doesn’t have TLS 1.2 or greater, as required by HTTP/2.
invalid_body_reader_state	An error occurred when draining the request body, aborting the HTTP/1.1 connection. This could be caused by app code reading the request body and missing a call to PipeReader.AdvanceTo in a finally block.
invalid_data_padding	An HTTP/2 HEADER or DATA frame has an invalid amount of padding.
invalid_frame_length	An HTTP/2 frame was received with an invalid frame payload length. The frame could contain a payload that is not valid for the type, or a DATA frame payload does not match the length specified in the frame header.
invalid_handshake	An invalid HTTP/2 handshake was received.
invalid_http_version	The connection received an HTTP request with the wrong version. For example, a browser sends an HTTP/1.1 request to a plain-text HTTP/2 connection.
invalid_request_headers	The HTTP request contains invalid headers. This error can occur in a number of scenarios: a header might not be allowed by the HTTP protocol, such as a pseudo-header in the HEADERS frame of an HTTP/2 request. A header could also have an invalid value, such as a non-integer content-length, or a header name or value might contain invalid characters.
invalid_request_line	The first line of an HTTP/1.1 request was invalid, potentially due to invalid content or exceeding the allowed limit. Configured by KestrelServerLimits.MaxRequestLineSize.
invalid_settings	The connection received an HTTP/2 or HTTP/3 SETTINGS frame with invalid settings.
invalid_stream_id	An HTTP/2 stream with an invalid stream ID was received.
invalid_window_update_size	The server received an HTTP/2 WINDOW_UPDATE frame with a zero increment, or an increment that caused a flow-control window to exceed the maximum size.
io_error	An IOException occurred while reading or writing HTTP/2 or HTTP/3 connection data.
keep_alive_timeout	There was no activity on the connection, and the keep-alive timeout configured by KestrelServerLimits.KeepAliveTimeout was exceeded.
max_concurrent_connections_exceeded	The connection exceeded the maximum concurrent connection limit. Configured by KestrelServerLimits.MaxConcurrentConnections.
max_frame_length_exceeded	The connection received an HTTP/2 frame that exceeded the size limit specified by Http2Limits.MaxFrameSize.
max_request_body_size_exceeded	The HTTP request body exceeded the maximum request body size limit. Configured by KestrelServerLimits.MaxRequestBodySize.
max_request_header_count_exceeded	The HTTP request headers exceeded the maximum count limit. Configured by KestrelServerLimits.MaxRequestHeaderCount.
max_request_headers_total_size_exceeded	The HTTP request headers exceeded the maximum total size limit. Configured by KestrelServerLimits.MaxRequestHeadersTotalSize.
min_request_body_data_rate	Reading the request body timed out due to data arriving too slowly. Configured by KestrelServerLimits.MinRequestBodyDataRate.
min_response_data_rate	Writing the response timed out because the client did not read it at the specified minimum data rate. Configured by KestrelServerLimits.MinResponseDataRate.
missing_stream_end	The connection received an HTTP/2 HEADERS frame for trailers without a stream end flag.
output_queue_size_exceeded	The connection exceeded the output queue size and was closed with INTERNAL_ERROR. This can be caused by an excessive number of HTTP/2 stream resets. For more information, see Microsoft Security Advisory CVE-2023-44487.
request_headers_timeout	Request headers timed out while waiting for headers to be received after the request started. Configured by KestrelServerLimits.RequestHeadersTimeout.
response_content_length_mismatch	The HTTP response body sent data that didn’t match the response’s content-length header.
server_timeout	The connection timed out with the IConnectionTimeoutFeature.
stream_creation_error	The HTTP/3 connection received a stream that it wouldn’t accept. For example, the client created duplicate control streams.
stream_reset_limit_exceeded	The connection received an excessive number of HTTP/2 stream resets and was closed with ENHANCE_YOUR_CALM. For more information, see Microsoft Security Advisory CVE-2023-44487.
stream_self_dependency	The connection received an HTTP/2 frame that caused a frame to depend on itself.
tls_handshake_failed	An error occurred during the TLS handshake for a connection. Only reported for HTTP/1.1 and HTTP/2 connections. The TLS handshake for HTTP/3 is internal to QUIC transport.
tls_not_supported	A TLS handshake was received by an endpoint that isn’t configured to support TLS.
unexpected_end_of_request_content	The HTTP/1.1 request body ended before the data specified by the content-length header or chunked transfer encoding mechanism was received.
unexpected_frame	An unexpected HTTP/2 or HTTP/3 frame type was received. The frame type is either unknown, unsupported, or invalid for the current stream state.
unknown_stream	An HTTP/2 frame was received on an unknown stream.
write_canceled	The cancellation of a response body write aborted the HTTP/1.1 connection.

In other cases, error.type contains the fully qualified type name of the exception.

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

[3] network.protocol.version: 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] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[6] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[3] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[3] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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] network.protocol.name: The value SHOULD be normalized to lowercase.

[2] network.protocol.version: 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] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[5] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[3] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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] error.type: Captures the exception type when a TLS handshake fails.

[2] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[4] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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] network.transport: 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] network.type: The value SHOULD be normalized to lowercase.

[3] server.address: 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] server.port: 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
pipe	Named or anonymous pipe.
quic	QUIC
tcp	TCP
udp	UDP
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