Skip to content

Commit e91f03b

Browse files
noahfalkantonfirsov
noahfalk
and
antonfirsov
authored
Add a reference for new .NET 8 metrics (#37213)
* Add a reference for new .NET 8 metrics Part of the work for #36748 --------- Co-authored-by: Anton Firszov <[email protected]>
1 parent fe7431f commit e91f03b

File tree

8 files changed

+578
-13
lines changed

8 files changed

+578
-13
lines changed

‎docs/core/diagnostics/available-counters.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ ms.date: 12/17/2020
88
# Well-known EventCounters in .NET
99

1010
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.
11+
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).
1112

1213
## System.Runtime counters
1314

‎docs/core/diagnostics/built-in-metrics-aspnetcore.md‎

Lines changed: 393 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/core/diagnostics/built-in-metrics-system-net.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: System.Net Metrics
3+
description: Review the metrics available for System.Net
4+
ms.topic: reference
5+
ms.date: 9/21/2023
6+
---
7+
8+
# System.Net Metrics
9+
10+
This article describes the networking metrics built-in for <xref:System.Net> produced using the
11+
<xref:System.Diagnostics.Metrics?displayProperty=nameWithType> API. For a listing of metrics based on the alternate [EventCounters](event-counters.md) API,
12+
see [here](available-counters.md).
13+
14+
- [Meter: `System.Net.NameResolution`](#meter-systemnetnameresolution) - Metrics for DNS lookups
15+
* [Instrument: `dns.lookup.duration`](#instrument-dnslookupduration)
16+
- [Meter: `System.Net.Http`](#meter-systemnethttp) - Metrics for outbound networking requests using HttpClient
17+
* [Instrument: `http.client.open_connections`](#instrument-httpclientopen_connections)
18+
* [Instrument: `http.client.connection.duration`](#instrument-httpclientconnectionduration)
19+
* [Instrument: `http.client.request.duration`](#instrument-httpclientrequestduration)
20+
* [Instrument: `http.client.request.time_in_queue`](#instrument-httpclientrequesttime_in_queue)
21+
* [Instrument: `http.client.active_requests`](#instrument-httpclientactive_requests)
22+
23+
## Meter: `System.Net.NameResolution`
24+
25+
### Instrument: `dns.lookup.duration`
26+
27+
| Name | Instrument Type | Unit | Description |
28+
| -------- | --------------- | ----------- | -------------- |
29+
| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. |
30+
31+
| Attribute | Type | Description | Examples | Presence |
32+
|---|---|---|---|---|
33+
| `dns.question.name` | string | The name being queried. | `www.example.com`; `dot.net` | Always |
34+
| `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 |
35+
36+
This metric measures the time take to make DNS requests. These requests can occur by calling methods on
37+
<xref:System.Net.Dns> or indirectly wihtin higher level APIs on types such as <xref:System.Net.Http.HttpClient>.
38+
39+
Most errors when doing a DNS lookup throw a <xref:System.Net.Sockets.SocketException>. To better disambiguate the common error cases, SocketExceptions with specific <xref:System.Net.Sockets.SocketException.SocketErrorCode>
40+
are given explicit error names in `error.type`:
41+
42+
| SocketErrorCode | `error.type` |
43+
| --------------- | ------------ |
44+
| <xref:System.Net.Sockets.SocketError.HostNotFound> | host_not_found |
45+
| <xref:System.Net.Sockets.SocketError.TryAgain> | try_again |
46+
| <xref:System.Net.Sockets.SocketError.AddressFamilyNotSupported> | address_family_not_supported |
47+
| <xref:System.Net.Sockets.SocketError.NoRecovery> | no_recovery |
48+
49+
SocketExceptions with any other SocketError value are reported as `System.Net.Sockets.SocketException`.
50+
51+
Available starting in: .NET 8
52+
53+
## Meter: `System.Net.Http`
54+
55+
### Instrument: `http.client.open_connections`
56+
57+
| Name | Instrument Type | Unit (UCUM) | Description |
58+
| -------- | --------------- | ----------- | -------------- |
59+
| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client |
60+
61+
| Attribute | Type | Description | Examples | Presence |
62+
|---|---|---|---|---|
63+
| `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Always |
64+
| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
65+
| `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 |
66+
| `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`) |
67+
| `network.peer.address` | string | Peer IP address of the socket connection. | `10.5.3.2` | Always |
68+
| `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 |
69+
70+
<xref:System.Net.Http.HttpClient>, when configured to use the default <xref:System.Net.Http.SocketsHttpHandler>, maintains a cached pool of network connections for sending HTTP messages. This metric counts how many connections are currently
71+
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
72+
requests, but are left open so that future requests can be handled more quickly.
73+
74+
Available starting in: .NET 8
75+
76+
### Instrument: `http.client.connection.duration`
77+
78+
| Name | Instrument Type | Unit (UCUM) | Description |
79+
| -------- | --------------- | ----------- | -------------- |
80+
| `http.client.connection.duration` | Histogram | `s` | The duration of successfully established outbound HTTP connections. |
81+
82+
| Attribute | Type | Description | Examples | Presence |
83+
|---|---|---|---|---|
84+
| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
85+
| `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 |
86+
| `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`) |
87+
| `network.peer.address` | string | IP address of the socket connection. | `10.5.3.2` | Always |
88+
| `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 |
89+
90+
This metric is only captured when <xref:System.Net.Http.HttpClient> is configured to use the default <xref:System.Net.Http.SocketsHttpHandler>.
91+
92+
Available starting in: .NET 8
93+
94+
### Instrument: `http.client.request.duration`
95+
96+
| Name | Instrument Type | Unit (UCUM) | Description |
97+
| -------- | --------------- | ----------- | -------------- |
98+
| `http.client.request.duration` | Histogram | `s` | The duration of outbound HTTP requests. |
99+
100+
| Attribute | Type | Description | Examples | Presence |
101+
|---|---|---|---|---|
102+
| `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. |
103+
| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always |
104+
| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If one was received. |
105+
| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
106+
| `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 |
107+
| `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`) |
108+
| `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 |
109+
110+
HTTP client request duration measures the time the underlying client handler takes to complete the request up to reading response headers from the network
111+
stream. It does not include the time spent reading the response body.
112+
113+
Available starting in: .NET 8
114+
115+
### Instrument: `http.client.request.time_in_queue`
116+
117+
| Name | Instrument Type | Unit (UCUM) | Description |
118+
| -------- | --------------- | ----------- | -------------- |
119+
| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. |
120+
121+
| Attribute | Type | Description | Examples | Presence |
122+
|---|---|---|---|---|
123+
| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always |
124+
| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
125+
| `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 |
126+
| `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`) |
127+
| `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 |
128+
129+
<xref:System.Net.Http.HttpClient>, when configured to use the default <xref:System.Net.Http.SocketsHttpHandler>, sends HTTP requests using a pool of network connections.
130+
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
131+
measures the amount of time HTTP requests spend waiting in that queue, prior to anything being sent across the network.
132+
133+
Available starting in: .NET 8
134+
135+
### Instrument: `http.client.active_requests`
136+
137+
| Name | Instrument Type | Unit (UCUM) | Description |
138+
| -------- | --------------- | ----------- | -------------- |
139+
| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. |
140+
141+
| Attribute | Type | Description | Examples | Presence |
142+
|---|---|---|---|---|
143+
| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always |
144+
| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always |
145+
| `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 |
146+
| `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`) |
147+
| `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 |
148+
149+
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.
150+
151+
Available starting in: .NET 8

‎docs/core/diagnostics/built-in-metrics.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Built-in Metrics in .NET
3+
description: Review the metrics built-in for the .NET runtime and libraries.
4+
ms.topic: reference
5+
ms.date: 9/21/2023
6+
---
7+
8+
# Built-in Metrics in .NET
9+
10+
This is a reference for [metrics](metrics.md) built-in for .NET, produced using the
11+
<xref:System.Diagnostics.Metrics?displayProperty=nameWithType> API. For metrics produced by [alternative metric APIs](compare-metric-apis.md)
12+
see the [EventCounters reference](available-counters.md) and [Windows Performance Counter reference](../../framework/debug-trace-profile/performance-counters.md).
13+
14+
- [ASP.NET Core Metrics](built-in-metrics-aspnetcore.md)
15+
- [System.Net Metrics](built-in-metrics-system-net.md)

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

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -29,19 +29,18 @@ Over .NET's 20+ year history, we've iterated a few times on the design for metri
2929
### System.Diagnostics.Metrics
3030

3131
[System.Diagnostics.Metrics](metrics-instrumentation.md) APIs are the newest cross-platform APIs, and were designed in close collaboration with the
32-
[OpenTelemetry](https://opentelemetry.io/) project. The OpenTelemetry effort is an industry-wide collaboration across telemetry tooling vendors,
33-
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.
34-
It's available by targeting .NET 6, or in older .NET Core and .NET Framework apps by adding a reference to the .NET
35-
[System.Diagnostics.DiagnosticsSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource) 6.0 NuGet package. In addition to
36-
aiming at broad compatibility, this API adds support for many things that were lacking from EventCounters, such as:
32+
[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
33+
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
34+
[System.Diagnostics.DiagnosticsSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource) 6.0+ NuGet package. In addition to
35+
aiming at broad compatibility, this API adds support for many things that were lacking from earlier APIs, such as:
3736

3837
- Histograms and percentiles
3938
- Multi-dimensional metrics
4039
- Strongly typed high-performance listener API
4140
- Multiple simultaneous listeners
4241
- Listener access to unaggregated measurements
4342

44-
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.
43+
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.
4544

4645
### PerformanceCounter
4746

@@ -68,10 +67,8 @@ access to the aggregated values, and has limitations when using more than one li
6867
[dotnet-counters](dotnet-counters.md), and [dotnet-monitor](https://devblogs.microsoft.com/dotnet/introducing-dotnet-monitor/). For third-party
6968
tool support, check the vendor or project documentation to see if it's available.
7069

71-
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
72-
overtaken soon by growing support for [System.Diagnostics.Metrics](metrics-instrumentation.md). The .NET team doesn't expect to
73-
make substantial new investments on this API going forward, but as with `PerformanceCounters`, the API remains actively supported for all
74-
current and future users.
70+
The .NET team doesn't expect to make substantial new investments on this API going forward, but as with `PerformanceCounters`, the API remains
71+
actively supported for all current and future users.
7572

7673
## Third-party APIs
7774

‎docs/core/diagnostics/metrics-collection.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ For more information on custom metric instrumentation and options, see [Compare
2323

2424
## Create an example app
2525

26-
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).
26+
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).
2727

2828
```dotnetcli
2929
dotnet new console -o metric-instr
@@ -97,7 +97,7 @@ Press p to pause, r to resume, q to quit.
9797
Working Set (MB) 30
9898
```
9999

100-
For more information, see [dotnet-counters](dotnet-counters.md). To learn more about metrics in .NET, see [built-in metrics](available-counters.md).
100+
For more information, see [dotnet-counters](dotnet-counters.md). To learn more about metrics in .NET, see [built-in metrics](built-in-metrics.md).
101101

102102
## View metrics in Grafana with OpenTelemetry and Prometheus
103103

‎docs/core/diagnostics/metrics.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,6 @@ There are two parts to using metrics in a .NET app:
2828

2929
- [Instrumentation tutorial](metrics-instrumentation.md) - How to create new metrics in code
3030
- [Collection tutorial](metrics-collection.md) - How to store and view metric data for your app
31-
- [Built-in metrics](available-counters.md) - Discover metrics that are ready for use in .NET runtime libraries
31+
- [Built-in metrics](built-in-metrics.md) - Discover metrics that are ready for use in .NET runtime libraries
3232
- [Compare metric APIs](compare-metric-apis.md)
3333
- [EventCounters](event-counters.md) - Learn what EventCounters are, how to implement them, and how to consume them

‎docs/navigate/tools-diagnostics/toc.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,14 @@ items:
332332
href: ../../core/diagnostics/metrics-instrumentation.md
333333
- name: Collection
334334
href: ../../core/diagnostics/metrics-collection.md
335+
- name: Built-in Metrics
336+
items:
337+
- name: Overview
338+
href: ../../core/diagnostics/built-in-metrics.md
339+
- name: ASP.NET Core Metrics
340+
href: ../../core/diagnostics/built-in-metrics-aspnetcore.md
341+
- name: System.Net Metrics
342+
href: ../../core/diagnostics/built-in-metrics-system-net.md
335343
- name: EventCounters
336344
items:
337345
- name: Overview

0 commit comments

Comments
 (0)