.NET Profiling
Use only within this skill's stated task; general workflow advice does not apply to unrelated tasks. Cratis rules in .cratis/ai/rules/ (including csharp.md, specs.csharp.md, and orleans.md) and the cratis-* skills win where they differ. Write outputs only to the task's .ai-work/<task>/ folder; run collection commands there, not in profile-output/.
Trigger On
- the repo needs performance or runtime profiling for a .NET application
- the user asks about slow code, high CPU, GC pressure, allocation growth, exception storms, lock contention, or startup diagnostics
- the team wants official CLI-based diagnostics without depending on
dnx
Value
- produce a concrete project delta: code, docs, config, tests, CI, or review artifact
- reduce ambiguity through explicit planning, verification, and final validation skills
- leave reusable project context so future tasks are faster and safer
Do Not Use For
- replacing realistic performance tests or load tests with ad-hoc tracing alone
- production heap collection when the pause risk has not been accepted
- GUI-only workflows that the repo cannot automate or document
Inputs
- the nearest
AGENTS.md
- target application, process, or startup path
- the symptom being investigated: CPU, memory, GC, contention, exceptions, or startup
Quick Start
- Read the nearest
AGENTS.md and confirm scope and constraints.
- Run this skill's
Workflow through the Ralph Loop until outcomes are acceptable.
- Return the
Required Result Format with concrete artifacts and verification evidence.
Workflow
- Build and run a realistic target first:
- prefer
Release
- prefer realistic config, inputs, and data volume
- Start with the lightest useful tool:
dotnet-counters for live health signals
dotnet-trace for CPU, exception, contention, GC, and startup traces
dotnet-gcdump for managed heap inspection when memory shape matters
- Prefer installed CLI tools over
dnx one-shot execution so the repo commands stay stable and reproducible.
- Capture one focused profile at a time instead of mixing every signal into one run.
- For CPU and general runtime hotspots, start with
dotnet-trace collect.
- For live triage, start with
dotnet-counters monitor on System.Runtime.
- For heap analysis, use
dotnet-gcdump carefully and document the pause risk.
- After each change, rerun the same measurement path and compare before versus after.
Bootstrap When Missing
If official .NET profiling tools are not available yet:
- Detect current state:
dotnet --info
dotnet tool list --global
command -v dotnet-counters
command -v dotnet-trace
command -v dotnet-gcdump
- Choose the install path deliberately:
- preferred machine-level install:
Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (dotnet tool install <tool> --version <x>)
dotnet tool install --global dotnet-counters --version <x>
Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (dotnet tool install <tool> --version <x>)
dotnet tool install --global dotnet-trace --version <x>
Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (dotnet tool install <tool> --version <x>)
dotnet tool install --global dotnet-gcdump --version <x>
Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (dotnet tool install <tool> --version <x>)
- direct-download fallback when global tools are not suitable:
Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (dotnet tool install <tool> --version <x>)
- use the official Microsoft Learn download links for
dotnet-counters, dotnet-trace, and dotnet-gcdump
- Verify the installed tools resolve correctly:
dotnet-counters --version
dotnet-trace --version
dotnet-gcdump --version
- Record the exact profiling commands in the task's
.ai-work/<task>/ notes or the final report (propose an AGENTS.md or project-doc change only when the user asks for one; managed corpus files are never edited by hand), for example:
dotnet-counters monitor --process-id PID --counters System.Runtime
dotnet-trace collect --process-id PID --profile dotnet-common,dotnet-sampled-thread-time -o trace.nettrace
dotnet-gcdump collect --process-id PID --output heap.gcdump
- Run one bounded command and return
status: configured or status: improved.
- If the repo intentionally standardizes on another profiling stack and does not want these tools, return
status: not_applicable.
Deliver
- explicit official .NET profiling commands
- a clear profiling path for CPU, counters, and heap inspection
- reproducible diagnostics commands that humans and agents can rerun
Validate
- the chosen tool matches the actual symptom
- commands target a realistic process and configuration
- before/after comparisons use the same scenario
- heap collection warnings are explicit when
dotnet-gcdump is used
Ralph Loop
Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
- Plan first (mandatory):
- analyze current state
- define target outcome, constraints, and risks
- write a detailed execution plan
- list final validation skills to run at the end, with order and reason
- Execute one planned step and produce a concrete delta.
- Review the result and capture findings with actionable next fixes.
- Apply fixes in small batches and rerun the relevant checks or review steps.
- Update the plan after each iteration.
- Repeat until outcomes are acceptable or only explicit exceptions remain.
- If a dependency is missing, bootstrap it or return
status: not_applicable with explicit reason and fallback path.
Required Result Format
status: complete | clean | improved | configured | not_applicable | blocked
plan: concise plan and current iteration step
actions_taken: concrete changes made
validation_skills: final skills run, or skipped with reasons
verification: commands, checks, or review evidence summary
remaining: top unresolved items or none
For setup-only requests with no execution, return status: configured and exact next commands.
Load References
- references/commands.md
- references/patterns.md
- references/profiling.md
Example Requests
- "Profile this .NET app for CPU hotspots."
- "Investigate GC pressure in this service."
- "Capture counters and a trace from startup."
- "Set up official .NET profiling tools for local investigations."
1---2name: profiling3description: Use when investigating a .NET application's CPU, GC, allocation, exception or contention behavior through runtime profiling. Not for crash dumps, benchmark design or replacing realistic load tests with ad-hoc traces.4compatibility: Requires a .NET app or process to inspect; respects the repo's `AGENTS.md` commands first.5license: MIT6metadata:7 source: https://skillmd.com/skills/cratis/profiling8---910<!-- Modified by Cratis from managedcode's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/managedcode/dotnet-skills (catalog/Tools/Profiling/skills/profiling/SKILL.md; see NOTICE) -->1112# .NET Profiling1314Use only within this skill's stated task; general workflow advice does not apply to unrelated tasks. Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ. Write outputs only to the task's `.ai-work/<task>/` folder; run collection commands there, not in `profile-output/`.1516## Trigger On1718- the repo needs performance or runtime profiling for a .NET application19- the user asks about slow code, high CPU, GC pressure, allocation growth, exception storms, lock contention, or startup diagnostics20- the team wants official CLI-based diagnostics without depending on `dnx`2122## Value2324- produce a concrete project delta: code, docs, config, tests, CI, or review artifact25- reduce ambiguity through explicit planning, verification, and final validation skills26- leave reusable project context so future tasks are faster and safer2728## Do Not Use For2930- replacing realistic performance tests or load tests with ad-hoc tracing alone31- production heap collection when the pause risk has not been accepted32- GUI-only workflows that the repo cannot automate or document3334## Inputs3536- the nearest `AGENTS.md`37- target application, process, or startup path38- the symptom being investigated: CPU, memory, GC, contention, exceptions, or startup3940## Quick Start41421. Read the nearest `AGENTS.md` and confirm scope and constraints.432. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable.443. Return the `Required Result Format` with concrete artifacts and verification evidence.4546## Workflow47481. Build and run a realistic target first:49 - prefer `Release`50 - prefer realistic config, inputs, and data volume512. Start with the lightest useful tool:52 - `dotnet-counters` for live health signals53 - `dotnet-trace` for CPU, exception, contention, GC, and startup traces54 - `dotnet-gcdump` for managed heap inspection when memory shape matters553. Prefer installed CLI tools over `dnx` one-shot execution so the repo commands stay stable and reproducible.564. Capture one focused profile at a time instead of mixing every signal into one run.575. For CPU and general runtime hotspots, start with `dotnet-trace collect`.586. For live triage, start with `dotnet-counters monitor` on `System.Runtime`.597. For heap analysis, use `dotnet-gcdump` carefully and document the pause risk.608. After each change, rerun the same measurement path and compare before versus after.6162## Bootstrap When Missing6364If official .NET profiling tools are not available yet:65661. Detect current state:67 - `dotnet --info`68 - `dotnet tool list --global`69 - `command -v dotnet-counters`70 - `command -v dotnet-trace`71 - `command -v dotnet-gcdump`722. Choose the install path deliberately:73 - preferred machine-level install:74 > **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)75 - `dotnet tool install --global dotnet-counters --version <x>`76 > **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)77 - `dotnet tool install --global dotnet-trace --version <x>`78 > **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)79 - `dotnet tool install --global dotnet-gcdump --version <x>`80 > **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)81 - direct-download fallback when global tools are not suitable:82 > **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)83 - use the official Microsoft Learn download links for `dotnet-counters`, `dotnet-trace`, and `dotnet-gcdump`843. Verify the installed tools resolve correctly:85 - `dotnet-counters --version`86 - `dotnet-trace --version`87 - `dotnet-gcdump --version`884. Record the exact profiling commands in the task's `.ai-work/<task>/` notes or the final report (propose an `AGENTS.md` or project-doc change only when the user asks for one; managed corpus files are never edited by hand), for example:89 - `dotnet-counters monitor --process-id PID --counters System.Runtime`90 - `dotnet-trace collect --process-id PID --profile dotnet-common,dotnet-sampled-thread-time -o trace.nettrace`91 - `dotnet-gcdump collect --process-id PID --output heap.gcdump`925. Run one bounded command and return `status: configured` or `status: improved`.936. If the repo intentionally standardizes on another profiling stack and does not want these tools, return `status: not_applicable`.9495## Deliver9697- explicit official .NET profiling commands98- a clear profiling path for CPU, counters, and heap inspection99- reproducible diagnostics commands that humans and agents can rerun100101## Validate102103- the chosen tool matches the actual symptom104- commands target a realistic process and configuration105- before/after comparisons use the same scenario106- heap collection warnings are explicit when `dotnet-gcdump` is used107108## Ralph Loop109110Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.1111121. Plan first (mandatory):113 - analyze current state114 - define target outcome, constraints, and risks115 - write a detailed execution plan116 - list final validation skills to run at the end, with order and reason1172. Execute one planned step and produce a concrete delta.1183. Review the result and capture findings with actionable next fixes.1194. Apply fixes in small batches and rerun the relevant checks or review steps.1205. Update the plan after each iteration.1216. Repeat until outcomes are acceptable or only explicit exceptions remain.1227. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.123124### Required Result Format125126- `status`: `complete` | `clean` | `improved` | `configured` | `not_applicable` | `blocked`127- `plan`: concise plan and current iteration step128- `actions_taken`: concrete changes made129- `validation_skills`: final skills run, or skipped with reasons130- `verification`: commands, checks, or review evidence summary131- `remaining`: top unresolved items or `none`132133For setup-only requests with no execution, return `status: configured` and exact next commands.134135## Load References136137- [references/commands.md](references/commands.md)138- [references/patterns.md](references/patterns.md)139- [references/profiling.md](references/profiling.md)140141## Example Requests142143- "Profile this .NET app for CPU hotspots."144- "Investigate GC pressure in this service."145- "Capture counters and a trace from startup."146- "Set up official .NET profiling tools for local investigations."