open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
semantic-conventions/docs/dotnet/dotnet-kestrel-metrics.md

39 KiB
Raw Blame History

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

[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 Stable
network.type string OSI network layer or non-OSI equivalent. [2] ipv4; ipv6 Recommended if the transport is tcp or udp Stable
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 Stable
server.port int Server port number. [4] 80; 8080; 443 Recommended Stable

[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 Stable
udp UDP Stable
pipe Named or anonymous pipe. Stable
unix Unix domain socket Stable

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 Stable
ipv6 IPv6 Stable

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

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

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

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

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 Stable
ipv6 IPv6 Stable

Metric: kestrel.rejected_connections

Name Instrument Type Unit (UCUM) Description Stability
kestrel.rejected_connections Counter {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

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

[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 Stable
udp UDP Stable
pipe Named or anonymous pipe. Stable
unix Unix domain socket Stable

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 Stable
ipv6 IPv6 Stable

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

[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 Stable
network.type string OSI network layer or non-OSI equivalent. [2] ipv4; ipv6 Recommended if the transport is tcp or udp Stable
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 Stable
server.port int Server port number. [4] 80; 8080; 443 Recommended Stable

[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 Stable
udp UDP Stable
pipe Named or anonymous pipe. Stable
unix Unix domain socket Stable

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 Stable
ipv6 IPv6 Stable

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

[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 Stable
network.protocol.version string The actual version of the protocol used for network communication. [2] 1.1; 2 Recommended Stable
network.transport string OSI transport layer or inter-process communication method. [3] tcp; unix Recommended Stable
network.type string OSI network layer or non-OSI equivalent. [4] ipv4; ipv6 Recommended if the transport is tcp or udp Stable
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 Stable
server.port int Server port number. [6] 80; 8080; 443 Recommended Stable

[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 Stable
udp UDP Stable
pipe Named or anonymous pipe. Stable
unix Unix domain socket Stable

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 Stable
ipv6 IPv6 Stable

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

[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 Stable
network.type string OSI network layer or non-OSI equivalent. [2] ipv4; ipv6 Recommended if the transport is tcp or udp Stable
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 Stable
server.port int Server port number. [4] 80; 8080; 443 Recommended Stable

[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 Stable
udp UDP Stable
pipe Named or anonymous pipe. Stable
unix Unix domain socket Stable

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 Stable
ipv6 IPv6 Stable

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

[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. Stable
network.transport string OSI transport layer or inter-process communication method. [2] tcp; unix Recommended Stable
network.type string OSI network layer or non-OSI equivalent. [3] ipv4; ipv6 Recommended if the transport is tcp or udp Stable
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 Stable
server.port int Server port number. [5] 80; 8080; 443 Recommended Stable
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 Experimental

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

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

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 Stable
ipv6 IPv6 Stable

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

[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 Stable
network.type string OSI network layer or non-OSI equivalent. [2] ipv4; ipv6 Recommended if the transport is tcp or udp Stable
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 Stable
server.port int Server port number. [4] 80; 8080; 443 Recommended Stable

[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 Stable
udp UDP Stable
pipe Named or anonymous pipe. Stable
unix Unix domain socket Stable

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 Stable
ipv6 IPv6 Stable