Skip to content

docs: expand troubleshooting guidance #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rogeralsing wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: expand troubleshooting guidance #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,19 +272,27 @@ Object Bytes Count Type

### Prerequisites checklist

- .NET SDK 10.x installed (`dotnet --list-sdks`).
- .NET SDK 10.x preview installed (`dotnet --list-sdks`). The repo pins a preview SDK in `global.json`.
- Global tools installed and on `PATH`: `asynkron-profiler`, `dotnet-trace`, `dotnet-gcdump`.
- Default tool paths: `~/.dotnet/tools` (macOS/Linux) or `%USERPROFILE%\\.dotnet\\tools` (Windows).
- Prefer running the built output (Release) instead of `dotnet run` to avoid build/restore noise.

### Common failures

- `It was not possible to find any compatible framework version`: install the .NET 10 preview runtime/SDK or update your PATH so `dotnet` resolves the preview SDK required by `global.json`.
- `dotnet-trace` not found: install with `dotnet tool install -g dotnet-trace`, then ensure the global tool path is on `PATH`.
- `dotnet-gcdump` not found: install with `dotnet tool install -g dotnet-gcdump`.
- `Failed to create session` or `Diagnostics IPC error`: the target process must allow diagnostics. Ensure it is not started with `DOTNET_EnableDiagnostics=0` or `COMPlus_EnableDiagnostics=0` and run as the same user.
- No data or empty allocation tables: run with `--memory` (GC allocation ticks) or provide a `.nettrace`/`.etlx` that includes GC allocation events.
- Slow or huge traces: reduce workload/iterations or add app-side filters, then re-run.

### References

- CI workflow (SDK/runtime versions): https://github.com/asynkron/Asynkron.Profiler/actions/workflows/ci.yml
- `dotnet-trace` docs: https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace
- `dotnet-gcdump` docs: https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-gcdump
- Diagnostics IPC overview: https://learn.microsoft.com/dotnet/core/diagnostics/diagnostics-client-library

## Examples

```bash
Expand Down