Status: Stable
This article defines semantic conventions for Kestrel web server.
- Kestrel endpoint
- Metric:
kestrel.active_connections - Metric:
kestrel.connection.duration - Metric:
kestrel.rejected_connections - Metric:
kestrel.queued_connections - Metric:
kestrel.queued_requests - Metric:
kestrel.upgraded_connections - Metric:
kestrel.tls_handshake.duration - Metric:
kestrel.active_tls_handshakes
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.
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
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 |
|---|---|---|---|---|
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 |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |
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 |
|---|---|---|---|
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 |
|---|---|---|---|---|
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 | Version of the protocol specified in network.protocol.name. [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]: 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.
| Value | Description |
|---|---|
_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 |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
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 |
|---|---|---|---|---|
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 |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
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 |
|---|---|---|---|---|
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 |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
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 |
|---|---|---|---|---|
network.protocol.name |
string | OSI application layer or non-OSI equivalent. [1] | http; web_sockets |
Recommended |
network.protocol.version |
string | Version of the protocol specified in network.protocol.name. [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]: 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.
| Value | Description |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
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 |
|---|---|---|---|---|
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 |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |
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 |
|---|---|---|---|
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 |
|---|---|---|---|---|
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 |
|---|---|
_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 |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |
| Name | Instrument Type | Unit (UCUM) | Description |
|---|---|---|---|
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 |
|---|---|---|---|---|
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 |
|---|---|
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 |
|---|---|
ipv4 |
IPv4 |
ipv6 |
IPv6 |