# Asynkron.Profiler Commands

## Baseline Verification

```bash
asynkron-profiler --help
dotnet-trace --version
dotnet-gcdump --version
```

## Capture New Profiles

Build first:

```bash
dotnet build -c Release
```

CPU profile the compiled app:

```bash
asynkron-profiler --cpu -- ./bin/Release/<tfm>/MyApp
```

Profile a framework-dependent app:

```bash
asynkron-profiler --cpu -- dotnet ./bin/Release/<tfm>/MyApp.dll
```

Profile a project or solution directly:

```bash
asynkron-profiler --cpu -- ./MyApp.csproj
asynkron-profiler --cpu -- ./MySolution.sln
```

Only use `dotnet run` when you accept build and host noise:

```bash
asynkron-profiler --cpu -- dotnet run -c Release ./MyApp.csproj
```

## Mode Commands

CPU hotspots:

```bash
asynkron-profiler --cpu -- ./bin/Release/<tfm>/MyApp
```

Allocation profiling:

```bash
asynkron-profiler --memory -- ./bin/Release/<tfm>/MyApp
```

Thrown exceptions:

```bash
asynkron-profiler --exception -- ./bin/Release/<tfm>/MyApp
```

Lock contention:

```bash
asynkron-profiler --contention -- ./bin/Release/<tfm>/MyApp
```

Heap snapshot:

```bash
asynkron-profiler --heap -- ./bin/Release/<tfm>/MyApp
```

## Replay Existing Artifacts

Auto-select from file extension:

```bash
asynkron-profiler --input /path/to/trace.nettrace
```

Force CPU rendering for a Speedscope file:

```bash
asynkron-profiler --input /path/to/trace.speedscope.json --cpu
```

Render memory from `.etlx`:

```bash
asynkron-profiler --input /path/to/trace.etlx --memory
```

Render contention from `.etlx`:

```bash
asynkron-profiler --input /path/to/trace.etlx --contention
```

Render exceptions from `.etlx`:

```bash
asynkron-profiler --input /path/to/trace.etlx --exception
```

Render a heap dump:

```bash
asynkron-profiler --input /path/to/heap.gcdump --heap
```

## Tuning Output

Anchor the tree to one subsystem:

```bash
asynkron-profiler --memory --root "MyNamespace" -- ./bin/Release/<tfm>/MyApp
```

Reduce call tree noise:

```bash
asynkron-profiler --cpu --calltree-depth 8 --calltree-width 6 -- ./bin/Release/<tfm>/MyApp
```

Inspect self time:

```bash
asynkron-profiler --cpu --calltree-self -- ./bin/Release/<tfm>/MyApp
```

Focus exception analysis:

```bash
asynkron-profiler --exception --exception-type "InvalidOperationException" -- ./bin/Release/<tfm>/MyApp
```

Filter function tables:

```bash
asynkron-profiler --contention --filter "MyApp.Services" -- ./bin/Release/<tfm>/MyApp
```

Target a specific framework from a project:

```bash
asynkron-profiler --cpu --tfm net10.0 -- ./MyApp.csproj
```

## Manual Official-Tool Collection Plus Replay

Collect first with `dotnet-trace`, then render:

```bash
dotnet-trace collect --output ./profile-output/app.nettrace -- dotnet run MyProject.sln
asynkron-profiler --input ./profile-output/app.nettrace --cpu
```

This pattern is useful when:

- the trace is collected in CI or another machine
- you want to archive raw traces separately from the rendered report
- a later task needs multiple render passes over the same artifact

# Asynkron.Profiler Examples

## CPU

Use `--cpu` for sampled hotspots and top-function tables.

```bash
dotnet build -c Release examples/cpu/CpuDemo.csproj
asynkron-profiler --cpu -- ./examples/cpu/bin/Release/net10.0/CpuDemo
```

What to expect:

- a total-time call tree
- top functions by sampled time
- optional self-time view when `--calltree-self` is enabled

## Memory

Use `--memory` for allocation-heavy paths and per-type call trees.

```bash
dotnet build -c Release examples/memory/MemoryDemo.csproj
asynkron-profiler --memory -- ./examples/memory/bin/Release/net10.0/MemoryDemo
```

What to expect:

- allocation totals by type
- a sampled allocation call tree
- better signal when the workload is large enough to emit GC allocation ticks

## Exceptions

Use `--exception` when thrown exceptions are part of the performance or correctness issue.

```bash
dotnet build -c Release examples/exception/ExceptionDemo.csproj
asynkron-profiler --exception --exception-type "InvalidOperation" -- ./examples/exception/bin/Release/net10.0/ExceptionDemo
```

What to expect:

- thrown counts
- throw-site call tree
- narrower output when `--exception-type` is supplied

## Contention

Use `--contention` for lock-heavy or thread-blocking scenarios.

```bash
dotnet build -c Release examples/contention/ContentionDemo.csproj
asynkron-profiler --contention -- ./examples/contention/bin/Release/net10.0/ContentionDemo
```

What to expect:

- wait-time call tree
- top contended methods
- clearer results when the workload creates repeatable contention

## Heap

Use `--heap` when retained-memory shape matters more than allocation rate.

```bash
dotnet build -c Release examples/heap/HeapDemo.csproj
asynkron-profiler --heap -- ./examples/heap/bin/Release/net8.0/HeapDemo
```

What to expect:

- top retained types
- heap byte totals and object counts
- a snapshot view rather than an allocation timeline

## Troubleshooting

### Missing prerequisites

If the command fails because a prerequisite tool is missing:

```bash
dotnet tool install -g asynkron-profiler --prerelease
dotnet tool install -g dotnet-trace
dotnet tool install -g dotnet-gcdump
```

### Diagnostics IPC failures

If you see diagnostics session or IPC creation failures:

- confirm the target process allows diagnostics
- avoid `DOTNET_EnableDiagnostics=0`
- avoid `COMPlus_EnableDiagnostics=0`
- run the profiler as the same user that launches the target process

### Empty or weak data

If the output is empty or not useful:

- rerun against built `Release` output instead of `dotnet run`
- increase the workload or iteration count
- use the mode that matches the signal:
  - CPU for hotspots
  - memory for allocations
  - contention for lock waits
  - heap for retained memory
- verify the input artifact matches the replay mode

# Asynkron.Profiler Overview

## Official Sources

- GitHub repository:
  - <https://github.com/asynkron/Asynkron.Profiler>
- Upstream README:
  - <https://github.com/asynkron/Asynkron.Profiler/blob/main/README.md>
- Tool project:
  - <https://github.com/asynkron/Asynkron.Profiler/blob/main/src/ProfileTool/ProfileTool.csproj>
- Releases:
  - <https://github.com/asynkron/Asynkron.Profiler/releases>

## What The Tool Is

`Asynkron.Profiler` is a dotnet global tool that wraps `dotnet-trace` and `dotnet-gcdump` with a CLI focused on readable profiling output for humans, scripts, and agents.

Its core value is not raw trace collection alone. It gives you:

- a single command surface for CPU, memory, exception, contention, and heap scenarios
- plain-text summaries suitable for terminals, CI logs, or agent workflows
- replay support for existing `.nettrace`, `.speedscope.json`, `.etlx`, and `.gcdump` artifacts

## Install Paths

Install the profiler itself:

```bash
dotnet tool install -g asynkron-profiler --prerelease
```

Install required prerequisites:

```bash
dotnet tool install -g dotnet-trace
dotnet tool install -g dotnet-gcdump
```

Verify:

```bash
asynkron-profiler --help
dotnet-trace --version
dotnet-gcdump --version
```

Upstream currently documents `.NET SDK 10.x` as the expected baseline.

## When To Use This Skill

Use `dotnet-asynkron-profiler` when:

- the repo wants readable profiling output without opening a GUI profiler
- you need one command that can both collect and render performance data
- CI or agent automation should keep profiling artifacts and summaries in a stable folder
- you already have a trace file and want a focused report from it

Use `dotnet-profiling` instead when:

- you need the official .NET diagnostics CLIs directly
- you need attach-by-PID, counters, or lower-level trace authoring
- the repo intentionally does not want an extra profiler frontend

## Input And Output Model

### New capture flow

1. Build or choose the target command.
2. Run `asynkron-profiler` in one mode.
3. The tool invokes `dotnet-trace` or `dotnet-gcdump` as needed.
4. Results are written to `profile-output/`.

### Replay flow

1. Point `--input` at an existing artifact.
2. Optionally force the mode.
3. Render the structured report without rerunning the application.

## Supported Input Types

- CPU:
  - `.speedscope.json`
  - `.nettrace`
- Memory:
  - `.nettrace`
  - `.etlx`
- Exceptions:
  - `.nettrace`
  - `.etlx`
- Contention:
  - `.nettrace`
  - `.etlx`
- Heap:
  - `.gcdump`
  - `dotnet-gcdump report` text output

## Practical Defaults

- prefer built `Release` output over `dotnet run`
- start with one mode and only add filters after the baseline run
- keep `profile-output/` under the working directory so traces and reports stay together
- use project or solution paths only when you intentionally want the tool to build and run on your behalf

## Constraints And Tradeoffs

- if `dotnet-trace` or `dotnet-gcdump` is missing from `PATH`, the profiler cannot collect data
- disabled diagnostics IPC on the target process will break trace collection
- `--heap` gives retained-memory shape, not live allocation timelines
- `dotnet run` is convenient but usually less accurate than pointing at the compiled output
- replay mode is ideal for narrowing or sharing a trace, but it cannot recover events that were never captured in the original artifact