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

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

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

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.

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

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

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

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

[3]: 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 has a version of 0.27.2, but sends HTTP version 1.1, this attribute should be set to 1.1.

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

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.

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.

Metric: kestrel.rejected_connections

[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

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

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.

Metric: kestrel.queued_connections

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

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

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.

Metric: kestrel.queued_requests

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

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

[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 has a version of 0.27.2, but sends HTTP version 1.1, this attribute should be set to 1.1.

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

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.

Metric: kestrel.upgraded_connections

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

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

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

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.

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

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

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

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.

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.

Metric: kestrel.active_tls_handshakes

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

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

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.