Skip to content

Commit fa6c313

Browse files
jander-msftIEvangelistkkeirstead
authored
Add dotnet-monitor .NET tool documentation (#29895)
* Add basic dotnet-monitor docs * Fix links * Apply suggestions from code review Co-authored-by: kkeirstead <[email protected]> Co-authored-by: David Pine <[email protected]> Co-authored-by: kkeirstead <[email protected]>
1 parent 200f59d commit fa6c313

File tree

6 files changed

+224
-2
lines changed

6 files changed

+224
-2
lines changed

‎docs/core/additional-tools/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ The [.NET Uninstall Tool](https://github.com/dotnet/cli-lab/releases) (`dotnet-c
2121

2222
[dotnet-gcdump](../diagnostics/dotnet-gcdump.md) provides a way to collect GC (Garbage Collector) dumps of live .NET processes.
2323

24+
[dotnet-monitor](../diagnostics/dotnet-monitor.md) provides a way to monitor .NET applications in production environments and to collect diagnostic artifacts (for example, dumps, traces, logs, and metrics) on-demand or using automated rules for collecting under specified conditions.
25+
2426
[dotnet-trace](../diagnostics/dotnet-trace.md) collects profiling data from your app that can help in scenarios where you need to find out what causes an app to run slow.
2527

2628
## .NET Install tool for extension authors

‎docs/core/diagnostics/diagnostics-client-library.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ ms.author: tommcdon
1010

1111
**This article applies to: ✔️** .NET Core 3.0 SDK and later versions for target apps, .NET Standard 2.0 to use the library.
1212

13-
Microsoft.Diagnostics.NETCore.Client (also known as the Diagnostics client library) is a managed library that lets you interact with .NET Core runtime (CoreCLR) for various diagnostics related tasks, such as tracing via [EventPipe](eventpipe.md), requesting a dump, or attaching an ICorProfiler. This library is the backing library behind many diagnostics tools such as [`dotnet-counters`](dotnet-counters.md), [`dotnet-trace`](dotnet-trace.md), [`dotnet-gcdump`](dotnet-gcdump.md), and [`dotnet-dump`](dotnet-dump.md). Using this library, you can write your own diagnostics tools customized for your particular scenario.
13+
`Microsoft.Diagnostics.NETCore.Client` (also known as the Diagnostics client library) is a managed library that lets you interact with .NET Core runtime (CoreCLR) for various diagnostics related tasks, such as tracing via [EventPipe](eventpipe.md), requesting a dump, or attaching an `ICorProfiler`. This library is the backing library behind many diagnostics tools such as [dotnet-counters](dotnet-counters.md), [dotnet-trace](dotnet-trace.md), [dotnet-gcdump](dotnet-gcdump.md), [dotnet-dump](dotnet-dump.md), and [dotnet-monitor](dotnet-monitor.md). Using this library, you can write your own diagnostics tools customized for your particular scenario.
1414

1515
You can acquire [Microsoft.Diagnostics.NETCore.Client](https://www.nuget.org/packages/Microsoft.Diagnostics.NETCore.Client/) by adding a `PackageReference` to your project. The package is hosted on `NuGet.org`.
1616

‎docs/core/diagnostics/diagnostics-in-containers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ The same diagnostics tools that are useful for diagnosing .NET Core issues in ot
1212

1313
**These tools apply to: ✔️** .NET Core 3.1 SDK and later versions
1414

15-
The .NET Core global CLI diagnostic tools ([`dotnet-counters`](dotnet-counters.md), [`dotnet-dump`](dotnet-dump.md), [`dotnet-gcdump`](dotnet-gcdump.md), and [`dotnet-trace`](dotnet-trace.md)) are designed to work in a wide variety of environments and should all work directly in Docker containers. Because of this, these tools are the preferred method of collecting diagnostic information for .NET Core scenarios targeting .NET Core 3.1 or later in containers.
15+
The .NET Core global CLI diagnostic tools ([dotnet-counters](dotnet-counters.md), [dotnet-dump](dotnet-dump.md), [dotnet-gcdump](dotnet-gcdump.md), [dotnet-monitor](dotnet-monitor.md), and [dotnet-trace](dotnet-trace.md)) are designed to work in a wide variety of environments and should all work directly in Docker containers. Because of this, these tools are the preferred method of collecting diagnostic information for .NET Core scenarios targeting .NET Core 3.1 or later in containers.
1616

1717
You can also install these tools without the .NET SDK by downloading the single-file variants from the links in the previous paragraph. These installs require a global install of the .NET runtime version 3.1 or later, which you can acquire following any of the prescribed methods in the [.NET installation documentation](../install/index.yml) or by consuming any of the official runtime containers.
1818

‎docs/core/diagnostics/dotnet-monitor.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
title: dotnet-monitor diagnostic tool - .NET
3+
description: Learn how to install and use the dotnet-monitor tool to collect dumps, traces, logs, and metrics from applications in production environments.
4+
ms.date: 06/16/2022
5+
ms.topic: reference
6+
---
7+
# Diagnostic monitoring and collection utility (dotnet-monitor)
8+
9+
**This article applies to:** ✔️ `dotnet-monitor` version 6.0.0 and later versions
10+
11+
## Install
12+
13+
There are two ways to download `dotnet-monitor`:
14+
15+
- **dotnet global tool:**
16+
17+
To install the latest release version of the `dotnet-monitor` [NuGet package](https://www.nuget.org/packages/dotnet-monitor), use the [dotnet tool install](../tools/dotnet-tool-install.md) command:
18+
19+
```dotnetcli
20+
dotnet tool install --global dotnet-monitor
21+
```
22+
23+
- **Docker image:**
24+
25+
Download a Docker image for use in multi-container environments:
26+
27+
```console
28+
docker pull mcr.microsoft.com/dotnet/monitor
29+
```
30+
31+
## Synopsis
32+
33+
```console
34+
dotnet-monitor [-h|--help] [--version] <command>
35+
```
36+
37+
## Description
38+
39+
The `dotnet-monitor` global tool is a way to monitor .NET applications in production environments and to collect diagnostic artifacts (for example, dumps, traces, logs, and metrics) on-demand or using automated rules for collecting under specified conditions.
40+
41+
## Options
42+
43+
- **`--version`**
44+
45+
Displays the version of the dotnet-monitor utility.
46+
47+
- **`-h|--help`**
48+
49+
Shows command-line help.
50+
51+
## Commands
52+
53+
| Command |
54+
| --------------------------------------------------------- |
55+
| [dotnet monitor collect](#dotnet-monitor-collect) |
56+
| [dotnet monitor config show](#dotnet-monitor-config-show) |
57+
| [dotnet monitor generatekey](#dotnet-monitor-generatekey) |
58+
59+
## dotnet-monitor collect
60+
61+
Monitor .NET applications, allow collecting diagnostic artifacts, and send the results to a chosen destination.
62+
63+
### Synopsis
64+
65+
```console
66+
dotnet-monitor collect [-h|--help] [-u|--urls] [-m|--metrics] [--metricUrls] [--diagnostic-port] [--no-auth] [--temp-apikey] [--no-http-egress]
67+
```
68+
69+
### Options
70+
71+
- **`-h|--help`**
72+
73+
Shows command-line help.
74+
75+
- **`-u|--urls <urls>`**
76+
77+
Bindings for the HTTP api. Default is `https://localhost:52323`.
78+
79+
- **`-m|--metrics [true|false]`**
80+
81+
Enable publishing of metrics to `/metrics` route. Default is `true`
82+
83+
- **`--metricUrls <urls>`**
84+
85+
Bindings for the metrics HTTP api. Default is `http://localhost:52325`.
86+
87+
- **`--diagnostic-port <path>`**
88+
89+
The fully qualified path and filename of the diagnostic port to which runtime instances can connect. Specifying this option places `dotnet-monitor` into
90+
'listen' mode. When not specified, `dotnet-monitor` is in 'connect' mode.
91+
92+
On Windows, this must be a valid named pipe name.
93+
On Linux and macOS, this must be a valid Unix Domain Socket path.
94+
95+
- **`--no-auth`**
96+
97+
Disables API key authentication. Default is `false`.
98+
99+
It is strongly recommended that this option is not used in production environments.
100+
101+
- **`--temp-apikey`**
102+
103+
Generates a temporary API key for the `dotnet-monitor` instance.
104+
105+
- **`--no-http-egress`**
106+
107+
Disables egress of diagnostic artifacts via the HTTP response. When specified, artifacts must be egressed using an egress provider.
108+
109+
## dotnet-monitor config show
110+
111+
Shows configuration, as if `dotnet-monitor collect` was executed with these parameters.
112+
113+
### Synopsis
114+
115+
```console
116+
dotnet-monitor config show [-h|--help] [-u|--urls] [-m|--metrics] [--metricUrls] [--diagnostic-port] [--no-auth] [--temp-apikey] [--no-http-egress] [--level] [--show-sources]
117+
```
118+
119+
### Options
120+
121+
- **`-h|--help`**
122+
123+
Shows command-line help.
124+
125+
- **`-u|--urls <urls>`**
126+
127+
Bindings for the HTTP api. Default is `https://localhost:52323`.
128+
129+
This value is mapped into configuration as the `urls` key.
130+
131+
- **`-m|--metrics [true|false]`**
132+
133+
Enable publishing of metrics to `/metrics` route. Default is `true`.
134+
135+
This value is mapped into configuration as the `Metrics:Enabled` key.
136+
137+
- **`--metricUrls <urls>`**
138+
139+
Bindings for the metrics HTTP api. Default is `http://localhost:52325`.
140+
141+
This value is mapped into configuration as the `Metrics:Endpoints` key.
142+
143+
- **`--diagnostic-port <path>`**
144+
145+
The fully qualified path and filename of the diagnostic port to which runtime instances can connect. Specifying this option places `dotnet-monitor` into
146+
'listen' mode. When not specified, `dotnet-monitor` is in 'connect' mode.
147+
148+
On Windows, this must be a valid named pipe name.
149+
On Linux and macOS, this must be a valid Unix Domain Socket path.
150+
151+
This value is mapped into configuraion as the `DiagnosticPort:EndpointName` key.
152+
153+
- **`--no-auth`**
154+
155+
Disables API key authentication. Default is `false`.
156+
157+
It is strongly recommended that this option is not used in production environments.
158+
159+
This value is not mapped into configuration.
160+
161+
- **`--temp-apikey`**
162+
163+
Generates a temporary API key for the `dotnet-monitor` instance.
164+
165+
This value is mapped into configuration as the `Authentication:MonitorApiKey` key.
166+
167+
- **`--no-http-egress`**
168+
169+
Disables egress of diagnostic artifacts via the HTTP response. When specified, artifacts must be egressed using an egress provider.
170+
171+
This value is not mapped into configuration.
172+
173+
- **`--level`**
174+
175+
Configuration level. `Full` configuration can show sensitive information. There are two levels:
176+
177+
- `Full` - The full configuration without any redaction of any values.
178+
- `Redacted` - The full configuration but sensitive information, such as known secrets, is redacted.
179+
180+
- **`--show-sources`**
181+
182+
Identifies from which configuration source each effective configuration value is provided.
183+
184+
## dotnet-monitor generatekey
185+
186+
Generate an API key and hash for HTTP authentication.
187+
188+
### Synopsis
189+
190+
```console
191+
dotnet-monitor generatekey [-h|--help] [-o|--output]
192+
```
193+
194+
### Options
195+
196+
- **`-h|--help`**
197+
198+
Shows command-line help.
199+
200+
- **`-o|--output <Cmd|Json|MachineJson|PowerShell|Shell|Text>`**
201+
202+
The output format in which the API key information is written to standard output.
203+
204+
The allowable values are:
205+
- `Cmd` - Outputs in a format usable in Windows Command Prompt or batch files.
206+
- `Json` - Outputs in a format of a JSON object.
207+
- `MachineJson` - Outputs in a format of a JSON object without comments and explanation. Useful for automation scenarios.
208+
- `PowerShell` - Outputs in a format usable in PowerShell prompts and scripts.
209+
- `Shell` - Outputs in a format usable in Linux shells such as Bash.
210+
- `Text` - Outputs in a format that is plain text.
211+
212+
## See Also
213+
214+
- [dotnet/dotnet-monitor](https://github.com/dotnet/dotnet-monitor/tree/main/documentation)

‎docs/core/diagnostics/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,10 @@ The [dotnet-dump](dotnet-dump.md) tool is a way to collect and analyze Windows a
6161

6262
The [dotnet-gcdump](dotnet-gcdump.md) tool is a way to collect GC (Garbage Collector) dumps of live .NET processes.
6363

64+
### dotnet-monitor
65+
66+
The [dotnet-monitor](dotnet-monitor.md) tool is a way to monitor .NET applications in production environments and to collect diagnostic artifacts (for example, dumps, traces, logs, and metrics) on-demand or using automated rules for collecting under specified conditions.
67+
6468
### dotnet-trace
6569

6670
.NET Core includes what is called the `EventPipe` through which diagnostics data is exposed. The [dotnet-trace](dotnet-trace.md) tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow.

‎docs/fundamentals/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -733,6 +733,8 @@ items:
733733
href: ../core/diagnostics/dotnet-dump.md
734734
- name: dotnet-gcdump
735735
href: ../core/diagnostics/dotnet-gcdump.md
736+
- name: dotnet-monitor
737+
href: ../core/diagnostics/dotnet-monitor.md
736738
- name: dotnet-trace
737739
href: ../core/diagnostics/dotnet-trace.md
738740
- name: dotnet-stack

0 commit comments

Comments
 (0)