Add a reference for new .NET 8 metrics

Part of the work for dotnet#36748

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

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 <xref:System.Net> produced using the
+<xref:System.Diagnostics.Metrics?displayProperty=nameWithType> 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
+<xref:System.Net.Dns.GetHostName> or indirectly wihtin higher level APIs on types such as <xref:System.Net.Http.HttpClient>.
+
+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 |
+
+<xref:System.Net.Http.HttpClient> 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

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
+<xref:System.Diagnostics.Metrics?displayProperty=nameWithType> 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)

docs/core/diagnostics/compare-metric-apis.md

@@ -31,17 +31,17 @@ 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
 - Strongly typed high-performance listener API
 - 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
 

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 <xref:System.Diagnostics.Metrics.Meter?displayProperty=nameWithType> 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 <xref:System.Diagnostics.Metrics.Meter?displayProperty=nameWithType> 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
 

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

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