diff --git a/docs/core/diagnostics/available-counters.md b/docs/core/diagnostics/available-counters.md index 89a4282d69b79..c6c0bced7b7e2 100644 --- a/docs/core/diagnostics/available-counters.md +++ b/docs/core/diagnostics/available-counters.md @@ -8,6 +8,7 @@ ms.date: 12/17/2020 # Well-known EventCounters in .NET The .NET runtime and libraries implement and publish several [EventCounters](./event-counters.md) that can be used to identify and diagnose various performance issues. This article is a reference on the providers that can be used to monitor these counters and their descriptions. +See the [well-known metrics reference](built-in-metrics.md) instead if you are working with .NET's newer [System.Diagnostics.Metrics API](metrics.md). ## System.Runtime counters diff --git a/docs/core/diagnostics/built-in-metrics-aspnetcore.md b/docs/core/diagnostics/built-in-metrics-aspnetcore.md new file mode 100644 index 0000000000000..e0b9aa9e81896 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics-aspnetcore.md @@ -0,0 +1,393 @@ +--- +title: ASP.NET Core Metrics +description: Review the metrics available for ASP.NET Core +ms.topic: reference +ms.date: 9/21/2023 +--- + +# ASP.NET Core Metrics + +This article describes the metrics built-in for ASP.NET Core produced using the + API. For a listing of metrics based on the older [EventCounters](event-counters.md) API, +see [here](available-counters.md). + +- [Meter: `Microsoft.AspNetCore.Hosting`](#meter-microsoftaspnetcorehosting) + * [Instrument: `http.server.request.duration`](#instrument-httpserverrequestduration) + * [Instrument: `http.server.active_requests`](#instrument-httpserveractive_requests) +- [Meter: `Microsoft.AspNetCore.Routing`](#meter-microsoftaspnetcorerouting) + * [Instrument: `aspnetcore.routing.match_attempts`](#instrument-aspnetcoreroutingmatch_attempts) +- [Meter: `Microsoft.AspNetCore.Diagnostics`](#meter-microsoftaspnetcorediagnostics) + * [Instrument: `aspnetcore.diagnostics.exceptions`](#instrument-aspnetcorediagnosticsexceptions) +- [Meter: `Microsoft.AspNetCore.RateLimiting`](#meter-microsoftaspnetcoreratelimiting) + * [Instrument: `aspnetcore.rate_limiting.active_request_leases`](#instrument-aspnetcorerate_limitingactive_request_leases) + * [Instrument: `aspnetcore.rate_limiting.request_lease.duration`](#instrument-aspnetcorerate_limitingrequest_leaseduration) + * [Instrument: `aspnetcore.rate_limiting.queued_requests`](#instrument-aspnetcorerate_limitingqueued_requests) + * [Instrument: `aspnetcore.rate_limiting.request.time_in_queue`](#instrument-aspnetcorerate_limitingrequesttime_in_queue) + * [Instrument: `aspnetcore.rate_limiting.requests`](#instrument-aspnetcorerate_limitingrequests) +- [Meter: `Microsoft.AspNetCore.Server.Kestrel`](#meter-microsoftaspnetcoreserverkestrel) + * [Instrument: `kestrel.active_connections`](#instrument-kestrelactive_connections) + * [Instrument: `kestrel.connection.duration`](#instrument-kestrelconnectionduration) + * [Instrument: `kestrel.rejected_connections`](#instrument-kestrelrejected_connections) + * [Instrument: `kestrel.queued_connections`](#instrument-kestrelqueued_connections) + * [Instrument: `kestrel.queued_requests`](#instrument-kestrelqueued_requests) + * [Instrument: `kestrel.upgraded_connections`](#instrument-kestrelupgraded_connections) + * [Instrument: `kestrel.tls_handshake.duration`](#instrument-kestreltls_handshakeduration) + * [Instrument: `kestrel.active_tls_handshakes`](#instrument-kestrelactive_tls_handshakes) +- [Meter: `Microsoft.AspNetCore.Http.Connections`](#meter-microsoftaspnetcorehttpconnections) + * [Instrument: `signalr.server.connection.duration`](#instrument-signalrserverconnectionduration) + * [Instrument: `signalr.server.active_connections`](#instrument-signalrserveractive_connections) + +## Meter: `Microsoft.AspNetCore.Hosting` + +### Instrument: `http.server.request.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.server.request.duration` | Histogram | `s` | Measures the duration of inbound HTTP requests. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.route` | string | The matched route. | `{controller}/{action}/{id?}` | If it's available. | +| `error.type` | string | Describes a class of error the operation ended with. | `timeout`; `name_resolution_error`; `500` | If request has ended with an error. | +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If one was sent. | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. | `amqp`; `http`; `mqtt` | Always | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. | `3.1.1` | Always | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Always | +| `aspnetcore.request.is_unhandled` | boolean | True when the request was not handled by the application pipeline. | `true` | If the request was unhandled. | + +The time used to handle an inbound HTTP request as measured at the hosting layer of ASP.NET Core. The time measurement starts once the underlying web host has +sufficiently parsed the HTTP request headers on the inbound network stream to identify the new request and initialize context data structures such as the . The +time ends when the ASP.NET Core handler pipeline is finished executing, all response data has been sent, and context data structures for the request are being disposed. + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `http.server.active_requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.server.active_requests` | UpDownCounter | `{request}` | Measures the number of concurrent HTTP requests that are currently in-flight. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Always | +| `url.scheme`| string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Always | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Routing` + +### Instrument: `aspnetcore.routing.match_attempts` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.routing.match_attempts` | Counter | `{match_attempt}` | Number of requests that were attempted to be matched to an endpoint. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | Always | +| `aspnetcore.routing.is_fallback_route` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | If a route was successfully matched. | +| `http.route` | string | The matched route | `{controller}/{action}/{id?}` | If a route was successfully matched. | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Diagnostics` + +### Instrument: `aspnetcore.diagnostics.exceptions` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.diagnostics.exceptions` | Counter | `{exception}` | Number of exceptions caught by exception handling middleware. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.diagnostics.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Always | +| `aspnetcore.diagnostics.handler.type` | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | If the exception was handled by this handler. | +| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Always | + +`aspnetcore.diagnostics.exception.result` is one of the following: + +| Value | Description | +|---|---| +| `handled` | Exception was handled by the exception handling middleware. | +| `unhandled` | Exception was not handled by the exception handling middleware. | +| `skipped` | Exception handling was skipped because the response had started. | +| `aborted` | Exception handling didn't run because the request was aborted. | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.RateLimiting` + +### Instrument: `aspnetcore.rate_limiting.active_request_leases` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.active_request_leases` | UpDownCounter | `{request}` | Number of requests that are currently active on the server that hold a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.request_lease.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.request_lease.duration` | Histogram | `s` | The duration of the rate limiting lease held by requests on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.queued_requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.queued_requests` | UpDownCounter | `{request}` | Number of requests that are currently queued, waiting to acquire a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.request.time_in_queue` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.request.time_in_queue` | Histogram | `s` | The time a request spent in a queue, waiting to acquire a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | +| `aspnetcore.rate_limiting.result` | string | The rate limiting result shows whether lease was acquired or contains a rejection reason. | `acquired`; `request_canceled` | Always | + +`aspnetcore.rate_limiting.result` is one of the following: + +| Value | Description | +|---|---| +| `acquired` | Lease was acquired | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | +| `global_limiter` | Lease request was rejected by the global limiter | +| `request_canceled` | Lease request was canceled | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.requests` | Counter | `{request}` | Number of requests that tried to acquire a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | +| `aspnetcore.rate_limiting.result` | string | The rate limiting result shows whether lease was acquired or contains a rejection reason. | `acquired`; `request_canceled` | Always | + +`aspnetcore.rate_limiting.result` is one of the following: + +| Value | Description | +|---|---| +| `acquired` | Lease was acquired | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | +| `global_limiter` | Lease request was rejected by the global limiter | +| `request_canceled` | Lease request was canceled | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Server.Kestrel` + +### Instrument: `kestrel.active_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.type`| string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port`| int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.connection.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.connection.duration` | Histogram | `s` | The duration of connections on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | If an exception was thrown. | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. | `http`; `web_sockets` | Always | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. | `1.1`; `2` | Always | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | +| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | If the connection is secured with TLS. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.rejected_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.rejected_connections` | Counter | `{connection}` | Number of connections rejected by the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport`| string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address`| string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.queued_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.queued_connections` | UpDownCounter | `{connection}` | Number of connections that are currently queued and are waiting to start. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.queued_requests` + +| 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. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. | `http`; `web_sockets` | Always | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. | `1.1`; `2` | Always | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.upgraded_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.upgraded_connections` | UpDownCounter | `{connection}` | Number of connections that are currently upgraded (WebSockets). | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +The counter only tracks HTTP/1.1 connections. + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.tls_handshake.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.tls_handshake.duration` | Histogram | `s` | The duration of TLS handshakes on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | If an exception was thrown. | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | +| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | If the connection is secured with TLS. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.active_tls_handshakes` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.active_tls_handshakes` | UpDownCounter | `{handshake}` | Number of TLS handshakes that are currently in progress on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Http.Connections` + +### Instrument: `signalr.server.connection.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.connection.duration` | Histogram | `s` | The duration of connections on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Always | +| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Always | + +`signalr.connection.status` is one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`signalr.transport` is one of the following: + +| Value | Description | +|---|---| +| `server_sent_events` | ServerSentEvents protocol | +| `long_polling` | LongPolling protocol | +| `web_sockets` | WebSockets protocol | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `signalr.server.active_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Always | +| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Always | + +`signalr.connection.status` is one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`signalr.transport` is one of the following: + +| Value | Description | +|---|---| +| `server_sent_events` | ServerSentEvents protocol | +| `long_polling` | LongPolling protocol | +| `web_sockets` | WebSockets protocol | + +Available staring in: ASP.NET Core 8.0 diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md new file mode 100644 index 0000000000000..d45a2ed1a882a --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -0,0 +1,151 @@ +--- +title: System.Net Metrics +description: Review the metrics available for System.Net +ms.topic: reference +ms.date: 9/21/2023 +--- + +# System.Net Metrics + +This article describes the networking metrics built-in for produced using the + API. For a listing of metrics based on the alternate [EventCounters](event-counters.md) API, +see [here](available-counters.md). + +- [Meter: `System.Net.NameResolution`](#meter-systemnetnameresolution) - Metrics for DNS lookups + * [Instrument: `dns.lookup.duration`](#instrument-dnslookupduration) +- [Meter: `System.Net.Http`](#meter-systemnethttp) - Metrics for outbound networking requests using HttpClient + * [Instrument: `http.client.open_connections`](#instrument-httpclientopen_connections) + * [Instrument: `http.client.connection.duration`](#instrument-httpclientconnectionduration) + * [Instrument: `http.client.request.duration`](#instrument-httpclientrequestduration) + * [Instrument: `http.client.request.time_in_queue`](#instrument-httpclientrequesttime_in_queue) + * [Instrument: `http.client.active_requests`](#instrument-httpclientactive_requests) + +## Meter: `System.Net.NameResolution` + +### Instrument: `dns.lookup.duration` + +| Name | Instrument Type | Unit | Description | +| -------- | --------------- | ----------- | -------------- | +| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `dns.question.name` | string | The name being queried. | `www.example.com`; `dot.net` | Always | +| `error.type` | string | A well-known error string or the full type name of an exception that occured. | `host_not_found`; `System.Net.Sockets.SocketException` | If an error occured | + +This metric measures the time take to make DNS requests. These requests can occur by calling methods on + or indirectly wihtin higher level APIs on types such as . + +Most errors when doing a DNS lookup throw a . To better disambiguate the common error cases, SocketExceptions with specific +are given explicit error names in `error.type`: + +| SocketErrorCode | `error.type` | +| --------------- | ------------ | +| | host_not_found | +| | try_again | +| | address_family_not_supported | +| | no_recovery | + +SocketExceptions with any other SocketError value are reported as `System.Net.Sockets.SocketException`. + +Available starting in: .NET 8 + +## Meter: `System.Net.Http` + +### Instrument: `http.client.open_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Always | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `network.peer.address` | string | Peer IP address of the socket connection. | `10.5.3.2` | Always | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +, when configured to use the default , maintains a cached pool of network connections for sending HTTP messages. This metric counts how many connections are currently +in the pool. Active connections are handling active requests. Active connects could be transmitting data or awaiting the client or server. Idle connections aren't handling any +requests, but are left open so that future requests can be handled more quickly. + +Available starting in: .NET 8 + +### Instrument: `http.client.connection.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.connection.duration` | Histogram | `s` | The duration of successfully established outbound HTTP connections. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `network.peer.address` | string | IP address of the socket connection. | `10.5.3.2` | Always | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +This metric is only captured when is configured to use the default . + +Available starting in: .NET 8 + +### Instrument: `http.client.request.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.duration` | Histogram | `s` | The duration of outbound HTTP requests. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.error.reason` | string | Request failure reason: one of [HTTP Request errors](https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs), or a full exception type, or an HTTP 4xx/5xx status code. | `System.Threading.Tasks.TaskCanceledException`; `name_resolution_error`; `secure_connection_error` ; `404` | If request has failed. | +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If one was received. | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +HTTP client request duration measures the time the underlying client handler takes to complete the request up to reading response headers from the network +stream. It does not include the time spent reading the response body. + +Available starting in: .NET 8 + +### Instrument: `http.client.request.time_in_queue` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +, when configured to use the default , sends HTTP requests using a pool of network connections. +If all connections are already busy handling other requests, new requests are placed in a queue and wait until a network connection is available for use. This instrument +measures the amount of time HTTP requests spend waiting in that queue, prior to anything being sent across the network. + +Available starting in: .NET 8 + +### Instrument: `http.client.active_requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +This metric counts how many requests are considered active. Requests are active for the same time period that is measured by the [http.client.request.duration](#instrument-httpclientrequestduration) instrument. + +Available starting in: .NET 8 diff --git a/docs/core/diagnostics/built-in-metrics.md b/docs/core/diagnostics/built-in-metrics.md new file mode 100644 index 0000000000000..88126da3da619 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics.md @@ -0,0 +1,15 @@ +--- +title: Built-in Metrics in .NET +description: Review the metrics built-in for the .NET runtime and libraries. +ms.topic: reference +ms.date: 9/21/2023 +--- + +# Built-in Metrics in .NET + +This is a reference for [metrics](metrics.md) built-in for .NET, produced using the + API. For metrics produced by [alternative metric APIs](compare-metric-apis.md) +see the [EventCounters reference](available-counters.md) and [Windows Performance Counter reference](../../framework/debug-trace-profile/performance-counters.md). + +- [ASP.NET Core Metrics](built-in-metrics-aspnetcore.md) +- [System.Net Metrics](built-in-metrics-system-net.md) diff --git a/docs/core/diagnostics/compare-metric-apis.md b/docs/core/diagnostics/compare-metric-apis.md index 38443f7d5f14b..50044cfbca558 100644 --- a/docs/core/diagnostics/compare-metric-apis.md +++ b/docs/core/diagnostics/compare-metric-apis.md @@ -29,11 +29,10 @@ Over .NET's 20+ year history, we've iterated a few times on the design for metri ### System.Diagnostics.Metrics [System.Diagnostics.Metrics](metrics-instrumentation.md) APIs are the newest cross-platform APIs, and were designed in close collaboration with the -[OpenTelemetry](https://opentelemetry.io/) project. The OpenTelemetry effort is an industry-wide collaboration across telemetry tooling vendors, -programming languages, and application developers to create a broadly compatible standard for telemetry APIs. To eliminate any friction associated with adding third-party dependencies, .NET embeds the metrics API directly into the base class libraries. -It's available by targeting .NET 6, or in older .NET Core and .NET Framework apps by adding a reference to the .NET -[System.Diagnostics.DiagnosticsSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource) 6.0 NuGet package. In addition to -aiming at broad compatibility, this API adds support for many things that were lacking from EventCounters, such as: +[OpenTelemetry](https://opentelemetry.io/) project. If you don't have a specific reason to use one of the older APIs covered below, [System.Diagnostics.Metrics](metrics-instrumentation.md) is +a good default choice for new work. It's available by targeting .NET 6+, or in older .NET Core and .NET Framework apps by adding a reference to the .NET +[System.Diagnostics.DiagnosticsSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource) 6.0+ NuGet package. In addition to +aiming at broad compatibility, this API adds support for many things that were lacking from earlier APIs, such as: - Histograms and percentiles - Multi-dimensional metrics @@ -41,7 +40,7 @@ aiming at broad compatibility, this API adds support for many things that were l - Multiple simultaneous listeners - Listener access to unaggregated measurements -Although this API was designed to work well with OpenTelemetry and its growing ecosystem of pluggable vendor integration libraries, applications also have the option to use the .NET built-in listener APIs directly. With this option, you can create custom metric tooling without taking any external library dependencies. At the time of writing, the [System.Diagnostics.Metrics](xref:System.Diagnostics.Metrics) support is limited to [dotnet-counters](dotnet-counters.md) and [OpenTelemetry.NET](https://opentelemetry.io/docs/net/). However, we expect support for these APIs will grow given the active nature of the OpenTelemetry project. +Although this API was designed to work well with OpenTelemetry and its growing ecosystem of pluggable vendor integration libraries, applications also have the option to use the .NET built-in listener APIs directly. With this option, you can create custom metric tooling without taking any external library dependencies. ### PerformanceCounter @@ -68,10 +67,8 @@ access to the aggregated values, and has limitations when using more than one li [dotnet-counters](dotnet-counters.md), and [dotnet-monitor](https://devblogs.microsoft.com/dotnet/introducing-dotnet-monitor/). For third-party tool support, check the vendor or project documentation to see if it's available. -At the time of writing, this is the cross-platform .NET runtime API that has the broadest and most stable ecosystem support. However, it will likely be -overtaken soon by growing support for [System.Diagnostics.Metrics](metrics-instrumentation.md). The .NET team doesn't expect to -make substantial new investments on this API going forward, but as with `PerformanceCounters`, the API remains actively supported for all -current and future users. +The .NET team doesn't expect to make substantial new investments on this API going forward, but as with `PerformanceCounters`, the API remains +actively supported for all current and future users. ## Third-party APIs diff --git a/docs/core/diagnostics/metrics-collection.md b/docs/core/diagnostics/metrics-collection.md index 9214ef1aa2cad..36bce770d8fb7 100644 --- a/docs/core/diagnostics/metrics-collection.md +++ b/docs/core/diagnostics/metrics-collection.md @@ -23,7 +23,7 @@ For more information on custom metric instrumentation and options, see [Compare ## Create an example app -Before metrics can be collected, measurements must be produced. This tutorial creates an app that has basic metric instrumentation. The .NET runtime also has [various metrics built-in](available-counters.md). For more information about creating new metrics using the API, see [the instrumentation tutorial](metrics-instrumentation.md). +Before metrics can be collected, measurements must be produced. This tutorial creates an app that has basic metric instrumentation. The .NET runtime also has [various metrics built-in](built-in-metrics.md). For more information about creating new metrics using the API, see [the instrumentation tutorial](metrics-instrumentation.md). ```dotnetcli dotnet new console -o metric-instr @@ -97,7 +97,7 @@ Press p to pause, r to resume, q to quit. Working Set (MB) 30 ``` -For more information, see [dotnet-counters](dotnet-counters.md). To learn more about metrics in .NET, see [built-in metrics](available-counters.md). +For more information, see [dotnet-counters](dotnet-counters.md). To learn more about metrics in .NET, see [built-in metrics](built-in-metrics.md). ## View metrics in Grafana with OpenTelemetry and Prometheus diff --git a/docs/core/diagnostics/metrics.md b/docs/core/diagnostics/metrics.md index 6631195ba2e42..a31648369da02 100644 --- a/docs/core/diagnostics/metrics.md +++ b/docs/core/diagnostics/metrics.md @@ -28,6 +28,6 @@ There are two parts to using metrics in a .NET app: - [Instrumentation tutorial](metrics-instrumentation.md) - How to create new metrics in code - [Collection tutorial](metrics-collection.md) - How to store and view metric data for your app -- [Built-in metrics](available-counters.md) - Discover metrics that are ready for use in .NET runtime libraries +- [Built-in metrics](built-in-metrics.md) - Discover metrics that are ready for use in .NET runtime libraries - [Compare metric APIs](compare-metric-apis.md) - [EventCounters](event-counters.md) - Learn what EventCounters are, how to implement them, and how to consume them diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index a7c10d6fd6551..3afc763061f7e 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -332,6 +332,14 @@ items: href: ../../core/diagnostics/metrics-instrumentation.md - name: Collection href: ../../core/diagnostics/metrics-collection.md + - name: Built-in Metrics + items: + - name: Overview + href: ../../core/diagnostics/built-in-metrics.md + - name: ASP.NET Core Metrics + href: ../../core/diagnostics/built-in-metrics-aspnetcore.md + - name: System.Net Metrics + href: ../../core/diagnostics/built-in-metrics-system-net.md - name: EventCounters items: - name: Overview