Skip to content

Commit 2e7e86c

Browse files
sywhangsywhang
authored
Document more remarks about the diagnostics CLI tools (#22278)
* add note on sharing TMPDIR * add remaining caveats * pr feedback
1 parent 22a8e28 commit 2e7e86c

File tree

4 files changed

+42
-0
lines changed

4 files changed

+42
-0
lines changed

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ There are two ways to download and install `dotnet-counters`:
2929
| macOS | [x64](https://aka.ms/dotnet-counters/osx-x64) |
3030
| Linux | [x64](https://aka.ms/dotnet-counters/linux-x64) \| [arm](https://aka.ms/dotnet-counters/linux-arm) \| [arm64](https://aka.ms/dotnet-counters/linux-arm64) \| [musl-x64](https://aka.ms/dotnet-counters/linux-musl-x64) \| [musl-arm64](https://aka.ms/dotnet-counters/linux-musl-arm64) |
3131

32+
> [!NOTE]
33+
> To use `dotnet-counters` on an x86 app, you need a corresponding x86 version of the tool.
34+
3235
## Synopsis
3336

3437
```console
@@ -108,6 +111,12 @@ dotnet-counters collect [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic-
108111
> [!NOTE]
109112
> Launching a .NET executable via dotnet-counters will make its input/output to be redirected and you won't be able to interact with its stdin/stdout. Exiting the tool via CTRL+C or SIGTERM will safely end both the tool and the child process. If the child process exits before the tool, the tool will exit as well and the trace should be safely viewable. If you need to use stdin/stdout, you can use the `--diagnostic-port` option. See [Using diagnostic port](#using-diagnostic-port) for more information.
110113
114+
> [!NOTE]
115+
> On Linux and macOS, this command expects the target application and `dotnet-counters` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
116+
117+
> [!NOTE]
118+
> To collect metrics using `dotnet-counters`, it needs to be run as the same user as the user running target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
119+
111120
### Examples
112121

113122
- Collect all counters at a refresh interval of 3 seconds and generate a csv as output:
@@ -216,6 +225,12 @@ dotnet-counters monitor [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic-
216225
> [!NOTE]
217226
> Launching a .NET executable via dotnet-counters will make its input/output to be redirected and you won't be able to interact with its stdin/stdout. Exiting the tool via CTRL+C or SIGTERM will safely end both the tool and the child process. If the child process exits before the tool, the tool will exit as well. If you need to use stdin/stdout, you can use the `--diagnostic-port` option. See [Using diagnostic port](#using-diagnostic-port) for more information.
218227
228+
> [!NOTE]
229+
> On Linux and macOS, this command expects the target application and `dotnet-counters` to share the same `TMPDIR` environment variable.
230+
231+
> [!NOTE]
232+
> To monitor metrics using `dotnet-counters`, it needs to be run as the same user as the user running target process or as root.
233+
219234
### Examples
220235

221236
- Monitor all counters from `System.Runtime` at a refresh interval of 3 seconds:

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ There are two ways to download and install `dotnet-dump`:
3232
| macOS | [x64](https://aka.ms/dotnet-dump/osx-x64) |
3333
| Linux | [x64](https://aka.ms/dotnet-dump/linux-x64) \| [arm](https://aka.ms/dotnet-dump/linux-arm) \| [arm64](https://aka.ms/dotnet-dump/linux-arm64) \| [musl-x64](https://aka.ms/dotnet-dump/linux-musl-x64) \| [musl-arm64](https://aka.ms/dotnet-dump/linux-musl-arm64) |
3434

35+
> [!NOTE]
36+
> To use `dotnet-dump` on an x86 app, you need a corresponding x86 version of the tool.
37+
3538
## Synopsis
3639

3740
```console
@@ -108,6 +111,12 @@ dotnet-dump collect [-h|--help] [-p|--process-id] [-n|--name] [--type] [-o|--out
108111

109112
Enables dump collection diagnostic logging.
110113

114+
> [!NOTE]
115+
> On Linux and macOS, this command expects the target application and `dotnet-dump` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
116+
117+
> [!NOTE]
118+
> To collect a dump using `dotnet-dump`, it needs to be run as the same user as the user running target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
119+
111120
## dotnet-dump analyze
112121

113122
Starts an interactive shell to explore a dump. The shell accepts various [SOS commands](#analyze-sos-commands).

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ There are two ways to download and install `dotnet-gcdump`:
2929
| macOS | [x64](https://aka.ms/dotnet-gcdump/osx-x64) |
3030
| Linux | [x64](https://aka.ms/dotnet-gcdump/linux-x64) \| [arm](https://aka.ms/dotnet-gcdump/linux-arm) \| [arm64](https://aka.ms/dotnet-gcdump/linux-arm64) \| [musl-x64](https://aka.ms/dotnet-gcdump/linux-musl-x64) \| [musl-arm64](https://aka.ms/dotnet-gcdump/linux-musl-arm64) |
3131

32+
> [!NOTE]
33+
> To use `dotnet-gcdump` on an x86 app, you need a corresponding x86 version of the tool.
34+
3235
## Synopsis
3336

3437
```console
@@ -98,6 +101,12 @@ dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-f
98101

99102
The name of the process to collect the GC dump from.
100103

104+
> [!NOTE]
105+
> On Linux and macOS, this command expects the target application and `dotnet-gcdump` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
106+
107+
> [!NOTE]
108+
> To collect a GC dump using `dotnet-gcdump`, it needs to be run as the same user as the user running target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
109+
101110
## `dotnet-gcdump ps`
102111

103112
Lists the dotnet processes that GC dumps can be collected for.

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ There are two ways to download and install `dotnet-trace`:
2929
| macOS | [x64](https://aka.ms/dotnet-trace/osx-x64) |
3030
| Linux | [x64](https://aka.ms/dotnet-trace/linux-x64) \| [arm](https://aka.ms/dotnet-trace/linux-arm) \| [arm64](https://aka.ms/dotnet-trace/linux-arm64) \| [musl-x64](https://aka.ms/dotnet-trace/linux-musl-x64) \| [musl-arm64](https://aka.ms/dotnet-trace/linux-musl-arm64) |
3131

32+
> [!NOTE]
33+
> To use `dotnet-trace` on an x86 app, you need a corresponding x86 version of the tool.
34+
3235
## Synopsis
3336

3437
```console
@@ -141,6 +144,12 @@ dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--
141144
> [!NOTE]
142145
> Stopping the trace may take a long time (up to minutes) for large applications. The runtime needs to send over the type cache for all managed code that was captured in the trace.
143146
147+
> [!NOTE]
148+
> On Linux and macOS, this command expects the target application and `dotnet-trace` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
149+
150+
> [!NOTE]
151+
> To collect a trace using `dotnet-trace`, it needs to be run as the same user as the user running target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
152+
144153
## dotnet-trace convert
145154

146155
Converts `nettrace` traces to alternate formats for use with alternate trace analysis tools.

0 commit comments

Comments
 (0)