dotnet-diagnostics-cli 0.34.0

dotnet-diagnostics-cli

A standalone command-line tool for on-demand performance diagnostics on running .NET 10 applications — no target code changes or prior instrumentation, no MCP client, no HTTP server, no bearer token, no daemon.

It runs the same Core diagnostics engine as the dotnet-diagnostics-mcp MCP server, but as a tool a human (or a script / CI job) drives directly. Attach to a live process, collect a window of events, walk the heap, or write a dump — then exit. A stateful session REPL keeps collected artifacts queryable across commands so you can drill in without re-collecting. The CLI does not expose the MCP server's privileged dynamic-profiler method-parameter capture.

Two packages, one engine. Install this package (dotnet-diagnostics-cli) for interactive / scripted human use. Install dotnet-diagnostics-mcp instead when you want an MCP server that exposes diagnostics as tools to an LLM over HTTP or stdio.

Install

dotnet tool install -g dotnet-diagnostics-cli   # requires the .NET 10 SDK

Self-contained, per-OS binaries (no SDK required) are attached to every GitHub Release as dotnet-diagnostics-cli-<version>-<rid>. The downloaded archive keeps that name; the extracted executable inside it is dotnet-diagnostics-cli (dotnet-diagnostics-cli.exe on Windows). The diagnostics sidecar container image also ships the CLI on PATH, so kubectl exec … -- dotnet-diagnostics-cli … works inside the pod.

Quickstart

If something does not work, run dotnet-diagnostics-cli doctor first — it prints actionable fix: / affects: remediation for common environment and permission problems.

dotnet tool install -g dotnet-diagnostics-cli
dotnet-diagnostics-cli doctor
dotnet-diagnostics-cli processes
dotnet-diagnostics-cli collect --kind counters --pid 1234 --duration 5
dotnet-diagnostics-cli session

One-shot usage

# Discover attachable .NET processes
dotnet-diagnostics-cli processes

# Probe a target's capability matrix (CoreCLR vs NativeAOT, what's usable)
dotnet-diagnostics-cli capabilities --pid 1234

# Collect a 5s EventCounters window
dotnet-diagnostics-cli collect --kind counters --pid 1234 --duration 5

# Concurrent GC suspension and ActivitySource spans, with a useful inline overlay
dotnet-diagnostics-cli collect --kind gc-activities --pid 1234 --source 'MyApp.*' --duration 10 --json

# Walk the managed heap (top retained types)
dotnet-diagnostics-cli inspect-heap --pid 1234 --top-types 30 --acknowledge-risk high

# Write a heap dump to disk
dotnet-diagnostics-cli dump --pid 1234 --dump-type WithHeap --out ./dumps \
  --confirm --acknowledge-risk critical

--pid is optional — it is auto-resolved when exactly one .NET process is visible. Pass --json on any command to emit the raw DiagnosticResult envelope for scripting. Run dotnet-diagnostics-cli --help or <command> --help for the full flag reference.

Commands

For the full command catalog, flags, and examples, see docs/cli-reference.md.

Machine streaming

dotnet-diagnostics-cli stream --protocol jsonl exposes the Core-only versioned JSONL protocol used by local clients. Its hello response advertises versioned optional capabilities. Clients require both heapGrowth.version 1 and heapGrowth.available:true; the capability also reports the effective storeCapacity and minimumStoreCapacity:2, so a one-entry store does not claim that two handles can coexist. Growth queries use a current heap handle plus an earlier baselineHandle; the CLI reuses Core HeapGrowthDiff and does not expose a separate diff view. Both same-process, same-provenance artifacts remain ordinary bounded in-memory handle-store entries in the shared configured MemoryDiagnosticHandleStore, preserving existing client behavior. It is not an unbounded history or a dedicated two-slot/pinned pair: there is no release protocol, persistence, or automatic recollection, and either handle can expire or be capacity-evicted. Streaming does not run proactive dead-process eviction; live/gcdump growth queries validate target liveness and the current process lifetime at query time, while dump-origin comparisons remain offline. See the machine streaming protocol for the exact request, response, validation, and quality contract.

The session REPL

One-shot commands build the diagnostic host, run, and exit — so a drill-down query has nothing to query. session keeps the host (and every collected handle) alive across commands:

dotnet-diagnostics-cli session
diag> target 1234                       # bind a target pid once
diag(pid 1234)> collect --kind gc --duration 10
  → handle 1TA2BA7KT9PYT60WTWE0 — query --handle 1TA2BA7KT9PYT60WTWE0 --view <pauseHistogram|...>
diag(pid 1234)> query --handle 1TA2BA7KT9PYT60WTWE0 --view pauseHistogram
diag(pid 1234)> exit

• target <pid> binds a default pid so live-target commands (capabilities, collect, dump, inspect-heap --source live, get-bytes --kind module) no longer need --pid. target shows the current binding; target clear unbinds. An explicit --pid always overrides the binding.
• Handles published by collect / inspect-heap stay queryable until they expire or the target exits, so query --handle <id> --view <view> drills in without re-collecting.
• Ctrl-C cancels the running command and keeps the session alive; press it again to force-quit. An idle Ctrl-C leaves the session.

Documentation

• Full CLI reference: docs/cli-reference.md
• Project README & MCP server: github.com/pedrosakuma/dotnet-diagnostics

Linux note (live heap inspection)

inspect-heap --source live attaches via ptrace(2). On Debian/Ubuntu/WSL the default kernel.yama.ptrace_scope=1 blocks same-UID peer attach. Prefer --launch -- <app> [args] for a CLI-launched child, offline dump analysis, or EventPipe-based collection. If a container needs live attach, grant CAP_SYS_PTRACE only to the diagnostics container.

The fallback echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope relaxes a host-wide security boundary for every same-UID process. Use it only on an isolated personal-development machine, never a shared or production host. See the canonical Linux ptrace safety note.

The dump command writes through diagnostic IPC and does not need Linux CAP_SYS_PTRACE. EventPipe-based commands (collect, counters, GC, exceptions) are also unaffected.

License

MIT © pedrosakuma