Modernize crank's dotnet-trace plumbing (no default-behavior change)

[LoopedBard3]

PR A of the dotnet-trace modernization series. Strictly additive. Every existing --application.dotNetTrace true invocation produces the same trace contents it did before, byte-for-byte.

What changed

• Package bump (minimal). Microsoft.Diagnostics.NETCore.Client 0.2.621003 → 0.2.661903 to pick up the 3-arg StartEventPipeSession(providers, requestRundown, circularBufferMB) overload. Microsoft.Diagnostics.Tracing.TraceEvent stayed at 3.1.23 — bumping it transitively forces System.Text.Json 8.0.5 → 9.0.8 and cascades into System.Text.Encodings.Web and System.IO.Pipelines 9.x across every project in the solution. That's a runtime-version-pack-style change that doesn't belong in a strictly additive PR. Crank uses TraceEvent only for stable ClrTraceEventParser.Keywords enum values, so the bump is safe to defer to its own PR.

• TraceExtensions.cs refreshed from dotnet/diagnostics's current ProviderUtils.cs and ListProfilesCommandHandler.cs:

  • Modern CLR keywords added: monitoring, codesymbols, eventsource, compilation, compilationdiagnostic, methoddiagnostic, typediagnostic, jitinstrumentationdata, profiler, waithandle, allocationsampling.
  • Modern aliases added: assemblyloader (= fusion) and managedheapcollect (= gcheapcollect). Legacy keys preserved.
  • Corrected gcsampledobjectallocation{high,low} aliases added; legacy typo'd gcsampledobjectallcation{high,low} preserved.
  • Modern profiles added: dotnet-common, dotnet-sampled-thread-time, sample-profiler, database.
  • The legacy cpu-sampling profile is intentionally left untouched — that's the empty-providers fallback for --dotNetTrace true, and changing it would be a silent behavior change for every existing crank pipeline.

• New Job knobs (defaults reproduce today's exact behavior):

  • DotNetTraceBufferSizeMB — int, default 256 (today's hardcoded value). Surface: --[JOB].dotnetTraceBufferSizeMB.
  • DotNetTraceRequestRundown — bool, default true (today's implicit 2-arg-overload behavior). Surface: --[JOB].dotnetTraceRequestRundown.

• Startup.cs plumbing — Collect(...) grew a requestRundown parameter and now calls the 3-arg StartEventPipeSession overload; StartDotNetTrace(...) passes the new Job knobs through. The empty-providers fallback stays "cpu-sampling".

• Documentation/README updates:

  • dotnet/diagnostics/blob/master/... → .../main/... in Documentation.cs, README.md, and default.config.yml.
  • The two new flags documented.
  • Two-row "which trace collection mode should I use?" matrix added (DotNetTrace=true vs Collect=true). The collect-linux row lands in PR B.

• Tests:

  • TraceExtensionsTests — legacy + modern keyword resolution, typo/corrected alias equivalence, profile lookup (case-insensitive), ToProvider parsing, plus a smoke test that exercises the new 3-arg StartEventPipeSession overload end-to-end (gracefully skips in sandboxes where diagnostic IPC is unavailable).
  • JobMixedVersionCompatTests — a pre-PR-A job JSON payload (no new fields) deserializes into the legacy default values. Validates that new-agent + old-controller and new-controller + old-agent both keep behaving like today.

Tested

• dotnet build Microsoft.Crank.sln -c Release — clean, 0 warnings, 0 errors.
• dotnet test test/Microsoft.Crank.UnitTests — 67 passed, 0 failed, 0 skipped (28 new TraceExtensions + 3 new mixed-version compat + 36 pre-existing).
• Manual validation on the cobalt aarch64 Ubuntu 24.04 host: pending (will be performed before PR A is un-drafted / retargeted at dotnet/crank).

Out of scope (intentional)

• No collect-linux mode. That's PR B (stacked on this branch as loopedbard3/dotnet-trace-collect-linux).
• No default-provider migration. The cpu-sampling fallback for --dotNetTrace true is unchanged; promoting it to dotnet-sampled-thread-time,dotnet-common is a separate (optional) future PR with its own back-compat justification.
• No TraceEvent bump. Deferred to its own PR — see "Package bump" above.

Follow-ups

1. PR B — adds DotNetTraceCollectMode=collect-linux (lazy dotnet-trace CLI install + shell-out + Linux/root/kernel preflights with a hard-fail no-silent-fallback). Stacks on this branch.
2. Optional future PR — bump TraceEvent 3.1.23 → 3.2.x together with the System.Text.Json 9.0.x pack.
3. Optional future PR — promote the empty-providers default for default mode from cpu-sampling to the modern recommended pair.

---

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

This PR modernizes Crank’s dotnet-trace integration in a strictly additive way by updating provider/profile plumbing and surfacing new (default-preserving) configuration knobs for EventPipe session creation.

Changes:

• Bumps Microsoft.Diagnostics.NETCore.Client to use the 3-arg StartEventPipeSession(providers, requestRundown, circularBufferMB) overload.
• Adds Job knobs DotNetTraceBufferSizeMB (default 256) and DotNetTraceRequestRundown (default true) and wires them through the agent trace collection path.
• Refreshes TraceExtensions keyword/profile mappings and adds unit tests (including mixed-version/default-compat coverage).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/Microsoft.Crank.UnitTests/TraceExtensionsTests.cs	Adds coverage for keyword/profile/provider parsing and a smoke test for the new EventPipe overload.
test/Microsoft.Crank.UnitTests/JobMixedVersionCompatTests.cs	Verifies new Job defaults and backward-compatible JSON behavior.
src/Microsoft.Crank.Models/Job.cs	Introduces new dotnet-trace configuration properties with legacy-preserving defaults.
src/Microsoft.Crank.Controller/README.md	Documents new flags and updates diagnostics docs link to main.
src/Microsoft.Crank.Controller/Documentation.cs	Updates help text with new flags and refreshed docs link.
src/Microsoft.Crank.Controller/default.config.yml	Updates a reference link from master to main.
src/Microsoft.Crank.Agent/TraceExtensions.cs	Adds modern CLR keywords/aliases and modern dotnet-trace profiles while preserving legacy behavior.
src/Microsoft.Crank.Agent/Startup.cs	Plumbs new Job knobs into EventPipe session creation via the 3-arg overload.
Directory.Packages.props	Bumps Microsoft.Diagnostics.NETCore.Client package version.

Comments suppressed due to low confidence (1)

src/Microsoft.Crank.Agent/Startup.cs:6266

• buffersize now comes from user-configurable Job.DotNetTraceBufferSizeMB, but Collect doesn't validate it before passing it to DiagnosticsClient.StartEventPipeSession(...). A value of 0 or negative will likely cause StartEventPipeSession to throw and abort trace collection without a clear error. Consider rejecting invalid values early with a helpful log message (or clamping to a minimum).

            if (String.IsNullOrWhiteSpace(providers))
            {
                providers = "cpu-sampling";
            }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sebastienros]

It would be nice to test it with aditya's new dotnet tool to export traces as LLM consumable. https://github.com/adityamandaleeka/pvanalyze

Some crank skill may document that too.

[LoopedBard3]

It would be nice to test it with aditya's new dotnet tool to export traces as LLM consumable. https://github.com/adityamandaleeka/pvanalyze

Some crank skill may document that too.

Definitely, with this capability being updated I will make sure to update my crank investigation skill to know about the tracing capabilities of crank (it already uses (or tries to use) pvanalyze).