From febc02f8e1ac196992088c25794cd6c559fc24d6 Mon Sep 17 00:00:00 2001 From: Noah Falk Date: Thu, 21 Sep 2023 23:42:31 -0700 Subject: [PATCH 1/6] Add a reference for new .NET 8 metrics Part of the work for #36748 --- .../built-in-metrics-aspnetcore.md | 10 ++ .../built-in-metrics-system-net.md | 137 ++++++++++++++++++ docs/core/diagnostics/built-in-metrics.md | 15 ++ docs/core/diagnostics/compare-metric-apis.md | 14 +- docs/core/diagnostics/metrics-collection.md | 4 +- docs/core/diagnostics/metrics.md | 2 +- docs/navigate/tools-diagnostics/toc.yml | 8 + 7 files changed, 179 insertions(+), 11 deletions(-) create mode 100644 docs/core/diagnostics/built-in-metrics-aspnetcore.md create mode 100644 docs/core/diagnostics/built-in-metrics-system-net.md create mode 100644 docs/core/diagnostics/built-in-metrics.md 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..07fabce1cca47 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics-aspnetcore.md @@ -0,0 +1,10 @@ +--- +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 + +TODO 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..3a0ef33c3a955 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -0,0 +1,137 @@ +--- +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.lookups.duration`](#instrument-dnslookupsduration) +- [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.lookups.duration` + +| Name | Instrument Type | Unit | Description | +| -------- | --------------- | ----------- | -------------- | +| `dns.lookups.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 | + +This metric measures the time take to make DNS requests. These requests can occur by calling + or indirectly wihtin higher level APIs on types such as . + +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`) | +| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. | `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 | + + uses a cached pool of network connections when sending HTTP messages. This metric counts how many connections are currently +in the pool. Active connections are currently transmitting data or awaiting replies on already sent messages. Idle connections aren't currently 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`) | +| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. | `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 | + +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 | + +Client request duration measures time it takes for the call time to underlying client handler to complete request. +If request was sent with `HttpCompletionOption.ResponseContentRead` option (the default value) then metric records +time to last byte, otherwise (if `HttpCompletionOption.ResponseHeadersRead` was set), metric records time it took to receive response headers. + +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 | + +HttpClient 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 | + +Requests are considered 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..04283e65e1c9f 100644 --- a/docs/core/diagnostics/compare-metric-apis.md +++ b/docs/core/diagnostics/compare-metric-apis.md @@ -31,9 +31,9 @@ Over .NET's 20+ year history, we've iterated a few times on the design for metri [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: +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 +41,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 +68,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 b13bdac83fe38..c57c2c6aeb841 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -330,6 +330,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 From d75a584b7ab9bb195a59443dd957bbbe6cc69346 Mon Sep 17 00:00:00 2001 From: Noah Falk Date: Mon, 9 Oct 2023 00:17:21 -0700 Subject: [PATCH 2/6] Address PR feedback and add ASP.NET Core metrics --- docs/core/diagnostics/available-counters.md | 1 + .../built-in-metrics-aspnetcore.md | 385 +++++++++++++++++- .../built-in-metrics-system-net.md | 26 +- docs/core/diagnostics/compare-metric-apis.md | 5 +- 4 files changed, 401 insertions(+), 16 deletions(-) diff --git a/docs/core/diagnostics/available-counters.md b/docs/core/diagnostics/available-counters.md index 5dc58cdcd0bf1..57f74171c9fb0 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 index 07fabce1cca47..75a43c95ce8af 100644 --- a/docs/core/diagnostics/built-in-metrics-aspnetcore.md +++ b/docs/core/diagnostics/built-in-metrics-aspnetcore.md @@ -7,4 +7,387 @@ ms.date: 9/21/2023 # ASP.NET Core Metrics -TODO +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. | 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 index 3a0ef33c3a955..e6427abdb34f7 100644 --- a/docs/core/diagnostics/built-in-metrics-system-net.md +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -12,7 +12,7 @@ This article describes the networking metrics built-in for pro see [here](available-counters.md). - [Meter: `System.Net.NameResolution`](#meter-systemnetnameresolution) - Metrics for DNS lookups - * [Instrument: `dns.lookups.duration`](#instrument-dnslookupsduration) + * [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) @@ -22,11 +22,11 @@ see [here](available-counters.md). ## Meter: `System.Net.NameResolution` -### Instrument: `dns.lookups.duration` +### Instrument: `dns.lookup.duration` | Name | Instrument Type | Unit | Description | | -------- | --------------- | ----------- | -------------- | -| `dns.lookups.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. | +| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. | | Attribute | Type | Description | Examples | Presence | |---|---|---|---|---| @@ -54,8 +54,8 @@ Available starting in: .NET 8 | `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. | `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 | - uses a cached pool of network connections when sending HTTP messages. This metric counts how many connections are currently -in the pool. Active connections are currently transmitting data or awaiting replies on already sent messages. Idle connections aren't currently handling any +, 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 @@ -74,6 +74,8 @@ Available starting in: .NET 8 | `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. | `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` @@ -92,9 +94,9 @@ Available starting in: .NET 8 | `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 | -Client request duration measures time it takes for the call time to underlying client handler to complete request. -If request was sent with `HttpCompletionOption.ResponseContentRead` option (the default value) then metric records -time to last byte, otherwise (if `HttpCompletionOption.ResponseHeadersRead` was set), metric records time it took to receive response headers. +HTTP client request duration measures the time the underlying client handler takes to complete the request. +If the request was sent with `HttpCompletionOption.ResponseContentRead` option (the default value) then this metric records +time to last byte, otherwise if `HttpCompletionOption.ResponseHeadersRead` was set, this metric records time it took to receive response headers. Available starting in: .NET 8 @@ -112,9 +114,9 @@ Available starting in: .NET 8 | `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 | -HttpClient 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. +, 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 @@ -132,6 +134,6 @@ Available starting in: .NET 8 | `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 | -Requests are considered active for the same time period that is measured by the [http.client.request.duration](#instrument-httpclientrequestduration) instrument. +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/compare-metric-apis.md b/docs/core/diagnostics/compare-metric-apis.md index 04283e65e1c9f..50044cfbca558 100644 --- a/docs/core/diagnostics/compare-metric-apis.md +++ b/docs/core/diagnostics/compare-metric-apis.md @@ -29,9 +29,8 @@ 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 +[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: From 20a5bee6994e426cf73dbe07c06509fe7b2b30d7 Mon Sep 17 00:00:00 2001 From: Noah Falk Date: Mon, 9 Oct 2023 00:36:37 -0700 Subject: [PATCH 3/6] Fix missing is_unhandled metric column value --- docs/core/diagnostics/built-in-metrics-aspnetcore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/built-in-metrics-aspnetcore.md b/docs/core/diagnostics/built-in-metrics-aspnetcore.md index 75a43c95ce8af..e0b9aa9e81896 100644 --- a/docs/core/diagnostics/built-in-metrics-aspnetcore.md +++ b/docs/core/diagnostics/built-in-metrics-aspnetcore.md @@ -54,7 +54,7 @@ see [here](available-counters.md). | `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. | If the request was unhandled. | +| `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 From 846eeb101a74e17d681e672d341f4606de65de6c Mon Sep 17 00:00:00 2001 From: Noah Falk Date: Tue, 10 Oct 2023 02:41:52 -0700 Subject: [PATCH 4/6] Update docs/core/diagnostics/built-in-metrics-system-net.md Co-authored-by: Anton Firszov --- docs/core/diagnostics/built-in-metrics-system-net.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md index e6427abdb34f7..b0638781adde3 100644 --- a/docs/core/diagnostics/built-in-metrics-system-net.md +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -32,8 +32,8 @@ see [here](available-counters.md). |---|---|---|---|---| | `dns.question.name` | string | The name being queried. | `www.example.com`; `dot.net` | Always | -This metric measures the time take to make DNS requests. These requests can occur by calling - or indirectly wihtin higher level APIs on types such as . +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 . Available starting in: .NET 8 From 88f5735e849124ce6a48df3d9d67aa41906b4805 Mon Sep 17 00:00:00 2001 From: Noah Falk Date: Tue, 10 Oct 2023 02:48:13 -0700 Subject: [PATCH 5/6] Fix http.client.request.duration description --- docs/core/diagnostics/built-in-metrics-system-net.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md index b0638781adde3..1af48cf36eeed 100644 --- a/docs/core/diagnostics/built-in-metrics-system-net.md +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -94,9 +94,8 @@ Available starting in: .NET 8 | `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. -If the request was sent with `HttpCompletionOption.ResponseContentRead` option (the default value) then this metric records -time to last byte, otherwise if `HttpCompletionOption.ResponseHeadersRead` was set, this metric records time it took to receive response headers. +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 From c6a07477546a4d1ccc4199d19894b410d1d9add8 Mon Sep 17 00:00:00 2001 From: Noah Falk Date: Mon, 16 Oct 2023 16:31:16 -0700 Subject: [PATCH 6/6] Updates for recent implementation changes --- .../diagnostics/built-in-metrics-system-net.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md index 1af48cf36eeed..d45a2ed1a882a 100644 --- a/docs/core/diagnostics/built-in-metrics-system-net.md +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -31,10 +31,23 @@ see [here](available-counters.md). | 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` @@ -51,7 +64,7 @@ Available starting in: .NET 8 | `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`) | -| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. | `10.5.3.2` | Always | +| `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 @@ -71,7 +84,7 @@ Available starting in: .NET 8 | `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`) | -| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. | `10.5.3.2` | Always | +| `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 .