From 1b2c439a40c37fde0f189f82ff9ad5fea35c56e5 Mon Sep 17 00:00:00 2001 From: Noah Falk Date: Thu, 21 Sep 2023 23:42:31 -0700 Subject: [PATCH] Add a reference for new .NET 8 metrics Fixes #36748 --- .../built-in-metrics-aspnetcore.md | 10 ++ .../built-in-metrics-system-net.md | 137 ++++++++++++++++++ docs/core/diagnostics/built-in-metrics.md | 16 ++ docs/core/diagnostics/compare-metric-apis.md | 14 +- docs/core/diagnostics/metrics-collection.md | 4 +- docs/core/diagnostics/metrics.md | 2 +- .../networking/networking-telemetry.md | 2 +- docs/navigate/tools-diagnostics/toc.yml | 8 + 8 files changed, 181 insertions(+), 12 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..7bb5815ac76e9 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics.md @@ -0,0 +1,16 @@ +--- +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). + +- [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/fundamentals/networking/networking-telemetry.md b/docs/fundamentals/networking/networking-telemetry.md index 9dbe8eb8753b0..87a11f7b3fe14 100644 --- a/docs/fundamentals/networking/networking-telemetry.md +++ b/docs/fundamentals/networking/networking-telemetry.md @@ -556,7 +556,7 @@ public sealed class InternalLatencyMonitor : IKestrelTelemetryConsumer, IHttpTel [distributed tracing documentation]: ../../core/diagnostics/distributed-tracing.md [EventCounters]: ../../core/diagnostics/event-counters.md -[well-known counters]: ../../core/diagnostics/available-counters.md +[well-known EventCounters]: ../../core/diagnostics/available-counters.md [dotnet-counter docs]: ../../core/diagnostics/dotnet-counters.md [dotnet-trace docs]: ../../core/diagnostics/dotnet-trace.md [dotnet-trace analysis docs]: ../../core/diagnostics/dotnet-trace.md#view-the-trace-captured-from-dotnet-trace 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