Kestrel Web 服务器指标的语义约定

状态: 稳定

本文档定义了 Kestrel Web 服务器的语义约定。

Kestrel 端点

Kestrel 端点由 System.Net.EndPoint 类表示,该类并不总是提供服务器地址或端口信息。

Instrumentation 支持 IPEndPointUnixDomainSocketEndPointNamedPipeEndPoint,并根据 Kestrel 指标中的相应端点设置 server.addressserver.port(针对 IP 端点)、network.typenetwork.transport 属性。

如果 Instrumentation 无法识别 EndPoint 实现,它会将 server.address 属性设置为 endpoint.ToString() 的值,并将 network.transport 值设置为相应的 endpoint.AddressFamily 属性。

指标:kestrel.active_connections

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.active_connectionsUpDownCounter{connection}服务器上当前活动的连接数。[1]Stable

[1]: Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
network.transportStable推荐字符串OSI 传输层进程间通信方法。[1]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效项。[2]ipv4; ipv6
server.addressStable推荐字符串服务器域名(如果可用且无需反向 DNS 查询);否则,为 IP 地址或 Unix 套接字名称。[3]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[4]80; 8080; 443

[1] network.transport该值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[2] network.type该值应规范化为小写。

[3] server.address从客户端观察时,并且在通过中间设备进行通信时,server.address 应表示中间设备(例如代理)后面的服务器地址,如果可用。

[4] server.port: 从客户端观察时,并且在通过中介进行通信时,server.port 应代表任何中介(例如代理)之后的服务器端口,如果可用。


network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable

指标:kestrel.connection.duration

此指标应使用 ExplicitBucketBoundaries 指定,值为 [ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.connection.durationHistograms服务器上连接的持续时间。[1]Stable

[1]: Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
error.typeStable如果发生错误,则为条件必需字符串异常类型的完整名称。[1]connection_resetinvalid_handshake
network.protocol.nameStable推荐字符串OSI 应用层或非 OSI 等效层。[2]httpweb_sockets
network.protocol.versionStable推荐字符串用于网络通信的协议的实际版本。[3]1.1; 2
network.transportStable推荐字符串OSI 传输层进程间通信方法。[4]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效。 [5]ipv4; ipv6
server.addressStable推荐字符串服务器域名(如果可用且无需反向 DNS 查询);否则,为 IP 地址或 Unix 套接字名称。[6]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[7]80; 8080; 443
tls.protocol.versionDevelopment推荐字符串从协商的SSL/TLS 协议版本的原始字符串解析出的版本数值部分。1.2; 3

[1] error.type从 .NET 9 开始,当发生相应错误时,Kestrel kestrel.connection.duration 指标会报告以下错误类型。

描述Stability
aborted_by_app当应用程序代码通过 HttpContext.Abort() 中止 HTTP 请求时,HTTP/1.1 连接被中止。
app_shutdown_timeout在应用程序关闭期间连接被中止。关闭期间,服务器停止接受新连接和 HTTP 请求,并给予活动请求完成的时间。如果超过了应用程序关闭超时时间,所有剩余的连接都将被中止。
closed_critical_streamHTTP/3 连接的一个关键控制流已关闭。
connection_reset当连接上有活动的 HTTP/2 或 HTTP/3 流时,连接被重置。
error_after_starting_response在响应已开始后发生错误(例如未处理的应用程序异常或无效的请求正文),导致 HTTP/1.1 连接被中止。
error_reading_headers在 HTTP/2 HEADERS 帧中解码 HPACK 标头时发生错误。
error_writing_headers在 HTTP/2 HEADERS 帧中编码 HPACK 标头时发生错误。
flow_control_queue_size_exceeded连接超出了出站流控制最大队列大小,并以 INTERNAL_ERROR 关闭。这可能由过多的 HTTP/2 流重置引起。有关更多信息,请参阅 Microsoft 安全公告 CVE-2023-44487
flow_control_window_exceeded客户端发送的数据量超过了当前流控制窗口允许的范围。
frame_after_stream_close在已关闭的流上收到了 HTTP/2 帧。
insufficient_tls_version连接不满足 HTTP/2 所需的 TLS 1.2 或更高版本。
invalid_body_reader_state在排水请求正文时发生错误,导致 HTTP/1.1 连接中止。这可能是由于应用程序代码读取请求正文时,在 finally 块中遗漏了对 PipeReader.AdvanceTo 的调用。
invalid_data_paddingHTTP/2 HEADERDATA 帧具有无效的填充量。
invalid_frame_length接收到的 HTTP/2 帧的有效载荷长度无效。该帧可能包含对于类型无效的有效载荷,或者 DATA 帧的有效载荷与帧头中指定的长度不匹配。
invalid_handshake收到了无效的 HTTP/2 握手。
invalid_http_version连接收到了错误的 HTTP 版本请求。例如,浏览器向纯文本 HTTP/2 连接发送 HTTP/1.1 请求。
invalid_request_headersHTTP 请求包含无效的标头。此错误可能在多种情况下发生:标头可能不允许 HTTP 协议,例如 HTTP/2 请求的 HEADERS 帧中的伪标头。标头也可能具有无效值,例如非整数 content-length,或者标头名称或值可能包含无效字符。
invalid_request_lineHTTP/1.1 请求的第一行无效,可能由于内容无效或超出了允许的限制。由 KestrelServerLimits.MaxRequestLineSize 配置。
invalid_settings连接收到了无效设置的 HTTP/2 或 HTTP/3 SETTINGS 帧。
invalid_stream_id收到了具有无效流 ID 的 HTTP/2 流。
invalid_window_update_size服务器收到了增量为零的 HTTP/2 WINDOW_UPDATE 帧,或者增量导致流控制窗口超过最大值。
io_error在读取或写入 HTTP/2 或 HTTP/3 连接数据时发生了 IOException
keep_alive_timeout连接上没有活动,并且超过了由 KestrelServerLimits.KeepAliveTimeout 配置的 keep-alive 超时。
max_concurrent_connections_exceeded连接超出了最大并发连接限制。由 KestrelServerLimits.MaxConcurrentConnections 配置。
max_frame_length_exceeded连接收到了一个超出 Http2Limits.MaxFrameSize 指定大小限制的 HTTP/2 帧。
max_request_body_size_exceededHTTP 请求正文超出了最大请求正文大小限制。由 KestrelServerLimits.MaxRequestBodySize 配置。
max_request_header_count_exceededHTTP 请求标头超出了最大计数限制。由 KestrelServerLimits.MaxRequestHeaderCount 配置。
max_request_headers_total_size_exceededHTTP 请求标头超出了最大总大小限制。由 KestrelServerLimits.MaxRequestHeadersTotalSize 配置。
min_request_body_data_rate读取请求正文因数据到达速度过慢而超时。由 KestrelServerLimits.MinRequestBodyDataRate 配置。
min_response_data_rate响应写入超时,因为客户端未按指定的最低数据速率读取响应。由 KestrelServerLimits.MinResponseDataRate 配置。
missing_stream_end连接收到了没有流结束标志的 HTTP/2 HEADERS 帧(用于尾部)。
output_queue_size_exceeded连接超出了输出队列大小,并以 INTERNAL_ERROR 关闭。这可能由过多的 HTTP/2 流重置引起。有关更多信息,请参阅 Microsoft 安全公告 CVE-2023-44487
request_headers_timeout在请求开始后等待接收标头期间,请求标头超时。由 KestrelServerLimits.RequestHeadersTimeout 配置。
response_content_length_mismatchHTTP 响应正文发送的数据与响应的 content-length 标头不匹配。
server_timeout连接在 IConnectionTimeoutFeature 处超时。
stream_creation_errorHTTP/3 连接收到了它不会接受的流。例如,客户端创建了重复的控制流。
stream_reset_limit_exceeded连接收到了过多的 HTTP/2 流重置,并以 ENHANCE_YOUR_CALM 关闭。有关更多信息,请参阅 Microsoft 安全公告 CVE-2023-44487
stream_self_dependency连接收到了导致帧依赖于自身的 HTTP/2 帧。
tls_handshake_failed在连接的 TLS 握手期间发生错误。仅报告给 HTTP/1.1 和 HTTP/2 连接。HTTP/3 的 TLS 握手是 QUIC 传输的内部过程。Development
tls_not_supported未配置为支持 TLS 的端点接收了 TLS 握手。
unexpected_end_of_request_contentHTTP/1.1 请求正文在接收到 content-length 标头或分块传输编码机制指定的长度的数据之前就结束了。
unexpected_frame收到了意外的 HTTP/2 或 HTTP/3 帧类型。帧类型未知、不受支持或对于当前流状态无效。
unknown_stream在未知流上收到了 HTTP/2 帧。
write_canceled响应正文写入的取消中止了 HTTP/1.1 连接。

在其他情况下,error.type 包含异常的完全限定类型名称。

[2] network.protocol.name 值应规范化为小写。

[3] network.protocol.version 如果协议版本受协商(例如,使用 ALPN),则此属性应设置为协商后的版本。如果实际协议版本未知,则此属性不应设置。

[4] network.transport 值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[5] network.type: 值应标准化为小写。

[6] server.address: 从客户端观察并与中介通信时,server.address 应表示任何中介(例如代理)之后的服务器地址,如果可用。

[7] server.port: 当从客户端观察到并且通过中间件通信时,server.port 应代表任何中间件(例如代理)之后的服务器端口,如果可用。


error.type 具有以下已知值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
_OTHER当检测不到自定义值时使用的回退错误值。Stable

network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable

指标:kestrel.rejected_connections

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.rejected_connectionsCounter{connection}服务器拒绝的连接数。[1]Stable

[1]:当当前活动连接数超过 MaxConcurrentConnections 配置的值时,连接将被拒绝。Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
network.transportStable推荐字符串OSI 传输层进程间通信方法。[1]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效项。[2]ipv4; ipv6
server.addressStable推荐字符串服务器域名(如果可用且无需反向 DNS 查询);否则,为 IP 地址或 Unix 套接字名称。[3]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[4]80; 8080; 443

[1] network.transport该值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[2] network.type该值应规范化为小写。

[3] server.address从客户端观察时,并且在通过中间设备进行通信时,server.address 应表示中间设备(例如代理)后面的服务器地址,如果可用。

[4] server.port: 从客户端观察时,并且在通过中介进行通信时,server.port 应代表任何中介(例如代理)之后的服务器端口,如果可用。


network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable

指标:kestrel.queued_connections

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.queued_connectionsUpDownCounter{connection}当前正在排队等待开始的连接数。[1]Stable

[1]: Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
network.transportStable推荐字符串OSI 传输层进程间通信方法。[1]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效项。[2]ipv4; ipv6
server.addressStable推荐字符串服务器域名(如果可用且无需反向 DNS 查询);否则,为 IP 地址或 Unix 套接字名称。[3]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[4]80; 8080; 443

[1] network.transport该值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[2] network.type该值应规范化为小写。

[3] server.address从客户端观察时,并且在通过中间设备进行通信时,server.address 应表示中间设备(例如代理)后面的服务器地址,如果可用。

[4] server.port: 从客户端观察时,并且在通过中介进行通信时,server.port 应代表任何中介(例如代理)之后的服务器端口,如果可用。


network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable

指标:kestrel.queued_requests

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.queued_requestsUpDownCounter{request}多路复用连接(HTTP/2 和 HTTP/3)上当前正在排队等待开始的 HTTP 请求数。[1]Stable

[1]: Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
network.protocol.nameStable推荐字符串OSI 应用层或非 OSI 等效项。[1]httpweb_sockets
network.protocol.versionStable推荐字符串用于网络通信的实际协议版本。[2]1.1; 2
network.transportStable推荐字符串OSI 传输层进程间通信方法。[3]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效项。[4]ipv4; ipv6
server.addressStable推荐字符串如果服务器域名可用且无需反向 DNS 查找;否则,为 IP 地址或 Unix 域套接字名称。[5]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[6]80; 8080; 443

[1] network.protocol.name该值应规范化为小写。

[2] network.protocol.version如果协议版本需要协商(例如使用ALPN),则此属性应设置为协商后的版本。如果实际协议版本未知,则不应设置此属性。

[3] network.transport该值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[4] network.type该值应规范化为小写。

[5] server.address从客户端观察时,并且在通过中间设备进行通信时,server.address 应表示中间设备(例如代理)后面的服务器地址,如果可用。

[6] server.port 从客户端观察时,并且在通过中介进行通信时,server.port 应表示任何中介(例如代理)后面的服务器端口,如果可用。


network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable

指标:kestrel.upgraded_connections

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.upgraded_connectionsUpDownCounter{connection}当前已升级的连接数(WebSockets)。[1]Stable

[1]:此计数器仅跟踪 HTTP/1.1 连接。

Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
network.transportStable推荐字符串OSI 传输层进程间通信方法。[1]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效项。[2]ipv4; ipv6
server.addressStable推荐字符串服务器域名(如果可用且无需反向 DNS 查询);否则,为 IP 地址或 Unix 套接字名称。[3]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[4]80; 8080; 443

[1] network.transport该值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[2] network.type该值应规范化为小写。

[3] server.address从客户端观察时,并且在通过中间设备进行通信时,server.address 应表示中间设备(例如代理)后面的服务器地址,如果可用。

[4] server.port: 从客户端观察时,并且在通过中介进行通信时,server.port 应代表任何中介(例如代理)之后的服务器端口,如果可用。


network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable

指标:kestrel.tls_handshake.duration

此指标应使用 ExplicitBucketBoundaries [ 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 ] 进行指定。

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.tls_handshake.durationHistograms服务器上 TLS 握手的持续时间。[1]Stable

[1]: Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
error.typeStable如果发生错误,则为条件必需字符串异常类型的完整名称。[1]System.OperationCanceledException; Contoso.MyException
network.transportStable推荐字符串OSI 传输层进程间通信方法。[2]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效项。[3]ipv4; ipv6
server.addressStable推荐字符串服务器域名(如果可用且无需反向 DNS 查询);否则,为 IP 地址或 Unix 套接字名称。[4]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[5]80; 8080; 443
tls.protocol.versionDevelopment推荐字符串从协商的SSL/TLS 协议版本的原始字符串解析出的版本数值部分。1.2; 3

[1] error.type捕获 TLS 握手失败时的异常类型。

[2] network.transport该值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[3] network.type该值应规范化为小写。

[4] server.address: 从客户端观察时,并且在通过中介进行通信时,server.address 应代表任何中介(例如代理)之后的服务器地址,如果可用。

[5] server.port: 从客户端观察并与中介通信时,server.port 应表示任何中介(例如代理)之后的服务器端口,如果可用。


error.type 具有以下已知值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
_OTHER当检测不到自定义值时使用的回退错误值。Stable

network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable

指标:kestrel.active_tls_handshakes

名称Instrument TypeUnit (UCUM)描述Stability实体关联
kestrel.active_tls_handshakesUpDownCounter{handshake}服务器上当前正在进行的 TLS 握手次数。[1]Stable

[1]: Meter 名称:Microsoft.AspNetCore.Server.Kestrel;添加于:ASP.NET Core 8.0

Attributes

Stability需求级别Value Type描述Example Values
network.transportStable推荐字符串OSI 传输层进程间通信方法。[1]tcpunix
network.typeStable如果传输是 tcpudp,则为推荐字符串OSI 网络层或非 OSI 等效项。[2]ipv4; ipv6
server.addressStable推荐字符串服务器域名(如果可用且无需反向 DNS 查询);否则,为 IP 地址或 Unix 套接字名称。[3]example.com10.1.2.80/tmp/my.sock
server.portStable推荐int服务器端口号。[4]80; 8080; 443

[1] network.transport该值应规范化为小写。

在设置端口号时,应始终考虑设置传输协议,因为没有传输协议的端口号是模糊的。例如,不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[2] network.type该值应规范化为小写。

[3] server.address从客户端观察时,并且在通过中间设备进行通信时,server.address 应表示中间设备(例如代理)后面的服务器地址,如果可用。

[4] server.port: 从客户端观察时,并且在通过中介进行通信时,server.port 应代表任何中介(例如代理)之后的服务器端口,如果可用。


network.transport 具有以下已知值列表。如果其中一个适用,则必须使用相应的_值_;否则,可以_使用_自定义值。

描述Stability
pipe命名或匿名管道。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUnix 域套接字Stable

network.type 具有以下预定义值列表。如果其中一个适用,则必须使用相应的值;否则,可以使用自定义值。

描述Stability
ipv4IPv4Stable
ipv6IPv6Stable