Conversation
Describe dotnet-trace without requiring command-verb context, present record-trace as the user-facing OneCollect tool, and identify PerfCollect as the earlier LTTng-based Linux workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Retain the original profiler-selection context, keep the Linux subsection focused on collect-linux, distinguish record-trace and perf workflows, and modernize .NET terminology. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Distinguish platform facilities from collectors, remove PerfCollect from the EventPipe comparison, keep the specialized diagnostics overview focused on mechanisms, and document PerfCollect as the earlier LTTng-dependent workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document PerfView and TraceEvent 3.2.1 analysis-time symbol lookup for .NET, R2R, and Azure Linux binaries, plus local symbol paths and a valid offline dotnet-symbol workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Clarify the recommended memory-leak and deadlock artifacts, use dotnet-dump consistently for deadlock collection, fix the ThreadPool trace command, and prefer collect-linux for intermittent starvation analysis on .NET 10+ Linux. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Provide a cross-tool decision path from observed symptoms to metrics, traces, snapshots, and dumps, and simplify the diagnostics landing page around that workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Provide one runnable sample with distinct CPU, memory, GC, blocking, I/O, exception, startup, process, mixed-cause, and healthy-control scenarios. Organize the walkthrough around the collection strategy and analysis pivot each symptom requires. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
A few documentation details are inconsistent or potentially misleading (PerfView platform note, --duration format, and one sentence that contradicts analysis-time symbol resolution), and there’s a user-facing typo.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This pull request expands the .NET diagnostics documentation with a symptom-first path for performance investigations, introduces dedicated dotnet-trace collect-linux guidance plus runnable Linux scenarios, and updates existing diagnostics pages to reflect current tooling and workflows.
Changes:
- Adds a new performance decision guide and two Linux-focused
collect-linuxarticles (workflow guidance plus scenario-based practice). - Updates the diagnostics landing page and navigation TOC to make the new performance path discoverable.
- Refreshes multiple existing diagnostics articles to align terminology and tool recommendations (PerfCollect vs
collect-linux, OneCollectrecord-trace, symbols guidance, and updated tutorials).
File summaries
| File | Description |
|---|---|
| docs/navigate/tools-diagnostics/toc.yml | Adds navigation entries for the new performance decision guide and Linux collect-linux articles. |
| docs/core/diagnostics/trace-perfcollect-lttng.md | Adds guidance to prefer collect-linux for .NET 10+ Linux, and clarifies LTTng version constraints. |
| docs/core/diagnostics/tools-overview.md | Updates tool descriptions and adds OneCollect record-trace context alongside PerfCollect/collect-linux. |
| docs/core/diagnostics/specialized-diagnostics-overview.md | Refreshes tracing/tool references and links into collect-linux guidance. |
| docs/core/diagnostics/performance-diagnostics.md | New symptom-first performance troubleshooting guide with platform-specific collection recommendations. |
| docs/core/diagnostics/index.md | Reorganizes the landing page to point readers toward the new performance decision guide and updated tutorial grouping. |
| docs/core/diagnostics/eventpipe.md | Updates EventPipe comparisons and points to collect-linux and OneCollect for platform context. |
| docs/core/diagnostics/dotnet-trace.md | Adds collect-linux cross-links and expands symbol-resolution guidance for Linux traces. |
| docs/core/diagnostics/dotnet-trace-collect-linux-scenarios.md | New tutorial with runnable Linux performance investigation scenarios. |
| docs/core/diagnostics/dotnet-trace-collect-linux-performance.md | New how-to guide for collecting and analyzing collect-linux traces across common symptom areas. |
| docs/core/diagnostics/debug-threadpool-starvation.md | Updates commands and adds collect-linux guidance for Linux blocking/ThreadPool investigations. |
| docs/core/diagnostics/debug-memory-leak.md | Refreshes prerequisites/terminology and adds guidance for choosing dotnet-gcdump vs dumps. |
| docs/core/diagnostics/debug-highcpu.md | Refreshes the tutorial and adds Linux guidance for collect-linux, OneCollect, and perf workflows. |
| docs/core/diagnostics/debug-deadlock.md | Refreshes the tutorial to emphasize dumps for deadlocks and points to Linux trace guidance for deadlock formation. |
Review details
- Files reviewed: 14/14 changed files
- Comments generated: 6
- Review effort level: Lite
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
noahfalk
reviewed
Sep 9, 2026
noahfalk
left a comment
noahfalk
left a comment
Member
There was a problem hiding this comment.
I put some comments inline but this might be something you want to iterate on with @lateralusX. I think you may want to adjust the structure and scope somewhat before worrying about the smaller stuff.
Add reusable CPU, GC, event, and symbol workflows for saved traces. Keep PerfView as a normal alternative and distinguish Linux-native ELF symbols from managed PDBs. Scope collect-linux and EventPipe guidance to their supported environments without dated audit caveats. Copilot-Session: 119f6389-0d6f-4eb4-8780-e04b7a8acacf Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace the scenario catalog with two self-contained CPU and LOH walkthroughs and optional symptom-based entry points. Update navigation and add the scenarios-page redirect together with all stale cross-links, including the deadlock tutorial's removed Linux tracing detour. Copilot-Session: 119f6389-0d6f-4eb4-8780-e04b7a8acacf Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Apply tutorial review feedback after the shared analysis guidance and consolidated examples are available. Put Visual Studio first for trace analysis, retain perf and PerfView where appropriate, remove the gcdump detour, and correct Bombardier. Copilot-Session: 119f6389-0d6f-4eb4-8780-e04b7a8acacf Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a focused tutorial for investigating Linux performance with
dotnet-trace collect-linux, and update related diagnostics guidance to help readers move from a performance symptom to useful evidence and a diagnosis.This change:
dotnet-countersstarting point, rather than adding a separate triage page.The scenario walkthrough uses the companion
dotnet/samplessample at/samples/dotnet/samples/dotnet-trace-collect-linux-performance-scenarios/. The samples PR should merge before or with this PR so that route is available when the walkthrough is published.Validation included checking all changed relative links and heading anchors, parsing the diagnostics TOC as YAML, checking every commit independently for forward references, and verifying Markdown formatting.
Internal previews
Toggle expand/collapse
Build report