@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/dotnet-trace-collect/NOTICE

@@ -0,0 +1,65 @@
+.NET Trace Collect
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-diag/skills/dotnet-trace-collect/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line.
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+- Move the complete ### Step 2: Recommend diagnostic tools section verbatim into references/tool-selection.md to fit the body limit; leave a direct pointer.
+- Add direct conditional pointers for all otherwise-indirect reference/script/asset files: references/dotnet-monitor.md, references/dotnet-trace-collect-linux.md, references/dotnet-trace-collect.md, references/perfcollect.md, references/perfview.md.
+- Place approval guards immediately before complete Markdown tables so original rows remain intact.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+references/dotnet-monitor.md:
+- Quote the dotnet-monitor trace URL containing ampersand.
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+
+references/dotnet-trace-collect.md:
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+
+references/perfcollect.md:
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+- Place approval guards immediately before complete Markdown tables so original rows remain intact.
+
+references/perfview.md:
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+- Add marked approval and pinned-version guidance before the official direct-download/source-build fallback.
+
+references/tool-selection.md:
+- Adjust the moved reference-relative Markdown links to preserve their targets.
+- Contain the section moved verbatim from SKILL.md, with a reference H1 title.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.
+
+Executes or downloads (instructions retained, not executed by this import):
+- references/tool-selection.md: 3. **`perfcollect`** — inside the container when native stacks are needed on pre-.NET 10 (requires `SYS_ADMIN` / `--privileged`).
+- SKILL.md: 1. **Installation**: How to install the tool if it is not already available (e.g. `dotnet tool install -g dotnet-trace`). **When recommending multiple tools, provide installation and usage instructions for each one** — do not mention a tool without showing how to install and use it.
+- SKILL.md: | `perfcollect` in container without `SYS_ADMIN` | Containers drop `SYS_ADMIN` by default. Run with `--privileged` or add `SYS_ADMIN` capability, or fall back to `dotnet-trace`. |
+- SKILL.md: | Forgetting to install tools in container image | Add `dotnet tool install` to your Dockerfile, or use `dotnet-monitor` as a sidecar to avoid modifying the app image. |
+- references/dotnet-monitor.md: dotnet tool install -g dotnet-monitor
+- references/dotnet-trace-collect.md: dotnet tool install -g dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/linux-x64 -o dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/linux-arm64 -o dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/linux-musl-x64 -o dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/win-x64 -o dotnet-trace.exe
+- references/perfcollect.md: | Container | Needs `SYS_ADMIN` / `--privileged` |
+- references/perfcollect.md: curl -OL https://aka.ms/perfcollect
+- references/perfcollect.md: sudo ./perfcollect install
+- references/perfcollect.md: docker run --privileged ...
+- references/perfcollect.md: privileged: true
+- references/perfcollect.md: allowPrivilegeEscalation: true
+- references/perfcollect.md: ./perfcollect install
+- references/perfcollect.md: - ❌ In containers, requires `SYS_ADMIN` or `--privileged`
+- references/perfview.md: Download from [https://github.com/microsoft/perfview/releases](https://github.com/microsoft/perfview/releases). PerfView is a standalone `.exe` — no installation required.
+- references/perfview.md: > **PerfView inside containers**: `PerfView.exe` does not run in many slimmed-down Windows container images. To run PerfView inside a container (needed for the merge step in process-isolation, or for direct collection in Hyper-V), build **PerfViewCollect** from [https://github.com/microsoft/perfview](https://github.com/microsoft/perfview) as a self-contained publish, then copy the output binaries into the container.

package/package/corpus/skills/dotnet-trace-collect/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: dotnet-trace-collect
+description: 'Guides capturing diagnostic artifacts to diagnose production .NET performance problems: choosing tools, collecting performance data, and understanding trade-offs across Windows and Linux, .NET Framework and modern .NET, and container and non-container environments. Use when the user needs help choosing a diagnostic tool or collecting performance data for a .NET process. Not for crash dumps (use dump-collect), repository-level profiling workflows (use profiling), or analyzing collected traces.'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-diag/skills/dotnet-trace-collect/SKILL.md; see NOTICE) -->
+
+# .NET Trace Collect
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+This skill helps developers diagnose production performance issues by recommending the right diagnostic tools for their environment, guiding data collection, and suggesting analysis approaches. It does not analyze code for anti-patterns or perform the analysis itself.
+
+## When to Use
+
+- A developer needs to investigate a production performance issue (high CPU, memory leak, slow requests, excessive GC, networking errors, etc.)
+- Choosing the right diagnostic tool for a specific runtime, OS, or deployment topology
+- Setting up and running diagnostic tool commands for data collection
+- Understanding trade-offs between available tools (e.g. PerfView vs dotnet-trace)
+- Collecting diagnostics from containerized or Kubernetes workloads
+
+## When Not to Use
+
+- Reviewing source code for performance anti-patterns (use a code review skill instead)
+- Benchmarking during development (e.g. BenchmarkDotNet setup)
+- Analyzing collected trace or dump files (this skill recommends tools for analysis, but does not perform it)
+
+## Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| Symptom | Yes | What the developer is observing (high CPU, memory growth, slow requests, hangs, excessive GC, HTTP 5xx errors, networking timeouts, connection failures, assembly loading failures, etc.) |
+| Runtime | Yes | .NET Framework or modern .NET (and version, especially whether .NET 10+) |
+| OS | Yes | Windows or Linux |
+| Deployment | Yes | Non-container, container, or Kubernetes |
+| Admin privileges | Recommended | Whether the developer has admin/root access on the target machine |
+| Repro characteristics | Recommended | Whether the issue is easy to reproduce or requires a long time to manifest |
+
+## Workflow
+
+### Step 1: Understand the environment
+
+Determine or ask the developer to clarify:
+
+1. **Symptom**: What they are observing (high CPU, memory leak, slow requests, hangs, excessive GC, HTTP 5xx errors, networking timeouts, connection failures, assembly loading failures, etc.)
+2. **Runtime**: .NET Framework or modern .NET? If modern .NET, which version? (Especially whether .NET 10 or later.)
+3. **OS**: Windows or Linux?
+4. **Deployment**: Running directly on the host, in a container, or in Kubernetes?
+5. **Admin privileges**: Do they have admin/root access on the target machine or container?
+6. **Repro characteristics**: Does the issue reproduce quickly, or does it take a long time to manifest?
+7. **Workload context**: Determine or ask the user if you are running in the context of the workload (i.e., on the same machine or connected to the same environment where the issue is occurring). If so, you can run diagnostic commands directly on their behalf. If not, provide the commands as guidance for the user to run themselves.
+
+Use this information to select the right tool in Step 2.
+
+Read references/tool-selection.md when selecting the relevant diagnostic workflow.
+
+### Step 3: Guide data collection
+
+Provide the specific commands for the recommended tool. Load the appropriate reference file from the [tool reference lookup](references/tool-selection.md#tool-reference-lookup) table for detailed command-line examples.
+
+Key guidance to include:
+
+> **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+1. **Installation**: How to install the tool if it is not already available (e.g. `dotnet tool install -g dotnet-trace`). **When recommending multiple tools, provide installation and usage instructions for each one** — do not mention a tool without showing how to install and use it.
+2. **PID discovery (required before any `-p <PID>` command)**: Verify the target process first (for example: `dotnet-trace ps`, `curl <monitor-endpoint>/processes`, or `ps` inside a container). If the app is expected to be PID 1 in a container, still verify before collecting.
+3. **Collection command**: The exact command to run, including relevant providers, output format, and duration.
+4. **Container considerations**:
+   - Collecting from **inside** the container: ensure the tool is installed in the image or use `kubectl cp` to copy it in.
+   - Collecting from **outside** the container: use `dotnet-monitor` as a sidecar with a shared diagnostic port (Unix domain socket in `/tmp`).
+   - Kubernetes: `dotnet-monitor` as a sidecar container, or `kubectl debug` for ephemeral debug containers.
+5. **Long-running repros** (Windows/PerfView): show how to use trigger arguments and circular buffer settings.
+6. **Output location**: Where the collected file will be saved and how to copy it off the target for analysis.
+7. **Artifact handoff checklist**: Include runtime version, OS/kernel, container image tag or build SHA, PID/process name, UTC collection start/end timestamps, exact command used, and final artifact path when handing traces to someone else for analysis.
+
+### Step 4: Recommend analysis approach
+
+After data is collected, recommend the appropriate tool for analysis. Do **not** perform the analysis — just point the developer to the right tool and documentation.
+
+| Collected Data | Analysis Tool | Notes |
+|----------------|---------------|-------|
+| `.nettrace` file | PerfView (Windows), Speedscope (web) | PerfView gives the richest view on Windows |
+| `.etl` / `.etl.zip` file | PerfView | ETW traces from PerfView or perfcollect |
+| `perf.data.nl` from perfcollect | PerfView (Windows) | Copy the file to a Windows machine and open with PerfView |
+
+## Validation
+
+- [ ] The recommended tool is compatible with the developer's runtime, OS, and deployment topology
+- [ ] The collection command runs without errors
+- [ ] The output file is generated in the expected location
+- [ ] The developer knows which analysis tool to use for the collected data
+
+## Common Pitfalls
+
+> **Cratis:** Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+> **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+
+| Pitfall | Solution |
+|---------|----------|
+| Using `dotnet-trace` on .NET Framework | `dotnet-trace` only works with modern .NET (.NET Core 3.0+). Use PerfView for .NET Framework. |
+| PerfView without admin privileges | PerfView requires admin for ETW tracing. Fall back to `dotnet-trace` if admin is not available. |
+| `perfcollect` in container without `SYS_ADMIN` | Containers drop `SYS_ADMIN` by default. Run with `--privileged` or add `SYS_ADMIN` capability, or fall back to `dotnet-trace`. |
+| Huge trace files from long repros | On Windows, use PerfView `/StopOn` triggers that fire on the symptom you want to capture (e.g., `/StopOnPerfCounter`, `/StopOnGCEvent`, `/StopOnException`) with `/CircularMB` and `/BufferSizeMB`. **Never trigger on recovery** — the circular buffer continuously overwrites old data, so the interesting behavior may be lost by the time collection stops. |
+| Diagnostic port not accessible in container | Mount `/tmp` as a shared volume between the app container and `dotnet-monitor` sidecar for the diagnostic Unix domain socket. |
+| Forgetting to install tools in container image | Add `dotnet tool install` to your Dockerfile, or use `dotnet-monitor` as a sidecar to avoid modifying the app image. |
+| Exposing `dotnet-monitor` with `--no-auth` in production | Keep auth enabled, bind to localhost, and use `kubectl port-forward` for access. Use `--no-auth` only for short-lived isolated debugging. |
+| Collecting only CPU/thread-time trace for networking issues | CPU and thread-time traces alone do not show HTTP status codes, DNS timing, or connection pool behavior. Add the networking providers (`System.Net.Http`, `System.Net.NameResolution`, `System.Net.Security`, `System.Net.Sockets`) alongside the thread-time trace. |
+| Enabling all networking providers when only one is needed | Each networking provider adds overhead. If the issue is clearly HTTP-level (5xx status codes), `System.Net.Http` alone may be sufficient. Add DNS, TLS, and socket providers when the root cause is unclear. |
+
+## Reference navigation
+
+- Read references/dotnet-monitor.md when working on dotnet monitor.
+- Read references/dotnet-trace-collect-linux.md when working on dotnet trace collect linux.
+- Read references/dotnet-trace-collect.md when working on dotnet trace collect.
+- Read references/perfcollect.md when working on perfcollect.
+- Read references/perfview.md when working on perfview.

package/package/corpus/skills/dotnet-trace-collect/references/dotnet-monitor.md

@@ -0,0 +1,97 @@
+# dotnet-monitor
+
+**Purpose**: REST API-based diagnostics collection, designed for container and Kubernetes environments.
+
+| Attribute | Value |
+|-----------|-------|
+| OS | Windows, Linux, macOS |
+| Runtime | Modern .NET (.NET Core 3.1+) |
+| .NET Framework | ❌ Not supported |
+| Admin required | No |
+| Container | ✅ Designed for containers/K8s — runs as a sidecar |
+
+## Installation
+
+```bash
+# As a global tool
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+dotnet tool install -g dotnet-monitor
+
+# As a container image (for K8s sidecar)
+# mcr.microsoft.com/dotnet/monitor
+```
+
+## Common Commands
+
+```bash
+# Production-safe default: keep auth enabled (default) and bind to loopback
+dotnet-monitor collect --urls http://127.0.0.1:52323 --metricUrls http://127.0.0.1:52325
+
+# Dev-only shortcut in isolated environments (avoid in production)
+dotnet-monitor collect --urls http://127.0.0.1:52323 --no-auth
+```
+
+## Security Guidance (Production)
+
+- Do **not** run `dotnet-monitor` with `--no-auth` on production workloads.
+- Bind to localhost (`127.0.0.1`) and access through `kubectl port-forward` (or another local-only tunnel).
+- If remote access is required, keep auth enabled and restrict network exposure to trusted operators.
+
+## REST API Endpoints
+
+```bash
+# Access via local tunnel (recommended in Kubernetes)
+kubectl port-forward pod/<pod-name> 52323:52323
+
+# List processes (auth enabled by default)
+curl -H "Authorization: Bearer <monitor-token>" http://localhost:52323/processes
+
+# Collect a trace
+curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace "http://localhost:52323/trace?pid=<PID>&durationSeconds=30"
+
+# Collect GC trace
+curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace "http://localhost:52323/trace?pid=<PID>&profile=gc-verbose&durationSeconds=30"
+
+# Collect trace with networking providers (HTTP status codes, DNS, TLS, sockets)
+curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace "http://localhost:52323/trace?pid=<PID>&durationSeconds=30&providers=System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets"
+
+# Get live metrics
+curl -H "Authorization: Bearer <monitor-token>" http://localhost:52323/livemetrics?pid=<PID>
+```
+
+## Kubernetes Sidecar Setup
+
+```yaml
+# Pod spec with dotnet-monitor as sidecar
+spec:
+  containers:
+  - name: app
+    image: myapp:latest
+    volumeMounts:
+    - name: diag
+      mountPath: /tmp
+  - name: monitor
+    image: mcr.microsoft.com/dotnet/monitor:latest
+    args: ["collect", "--urls", "http://127.0.0.1:52323", "--metricUrls", "http://127.0.0.1:52325"]
+    volumeMounts:
+    - name: diag
+      mountPath: /tmp
+    ports:
+    - containerPort: 52323
+  volumes:
+  - name: diag
+    emptyDir: {}
+```
+
+The shared `/tmp` volume allows `dotnet-monitor` to access the app's diagnostic Unix domain socket.
+Keep auth enabled (default), and access the API via `kubectl port-forward` rather than exposing a public Service unless you have explicit authentication and network controls in place.
+
+## Trade-offs
+
+- ✅ Purpose-built for containers and Kubernetes
+- ✅ No tools needed inside the app container
+- ✅ REST API is easy to automate and integrate
+- ❌ Requires sidecar setup and shared volume
+- ❌ Additional resource overhead from sidecar container
+- ❌ Requires authentication setup (API key or `--no-auth` flag)
+- ⚠️ **When running in the workload context** (console access to the container), prefer console-based tools (`dotnet-trace`, `dotnet-trace collect-linux`) to avoid authentication setup. Use `dotnet-monitor` when console access is not available or when it is already deployed.

package/package/corpus/skills/dotnet-trace-collect/references/dotnet-trace-collect-linux.md

@@ -0,0 +1,84 @@
+# dotnet-trace collect-linux (.NET 10+)
+
+**Purpose**: Collects diagnostic traces using `perf_events`, a Linux OS technology. Provides native call stacks, kernel events, and machine-wide tracing that standard `dotnet-trace collect` cannot.
+
+| Attribute | Value |
+|-----------|-------|
+| OS | Linux only (kernel >= 6.4 with `CONFIG_USER_EVENTS=y`) |
+| Runtime | .NET 10+ only |
+| .NET Framework | ❌ Not supported |
+| Admin required | Yes (root) |
+| Container | Works inside container (requires root) |
+| glibc | >= 2.35 (not supported on Alpine 3.22, CentOS Stream 9, or RHEL 9-based distros) |
+
+## Key Differences from `dotnet-trace collect`
+
+| Feature | `collect` | `collect-linux` |
+|---------|-----------|-----------------|
+| Trace all processes simultaneously | No | Yes (default — no PID required) |
+| Capture native library and kernel events | No | Yes |
+| Event callstacks include native frames | No | Yes |
+| Requires admin/root | No | Yes |
+
+## Usage
+
+```bash
+# Machine-wide trace (all processes, no PID needed)
+sudo dotnet-trace collect-linux
+
+# Trace a specific process
+sudo dotnet-trace collect-linux -p <PID>
+
+# Trace a process by name
+sudo dotnet-trace collect-linux -n <process-name>
+
+# Trace for a specific duration
+sudo dotnet-trace collect-linux --duration 00:00:30
+
+# Trace with specific providers
+sudo dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime
+
+# Trace with networking providers (HTTP status codes, DNS, TLS, sockets)
+sudo dotnet-trace collect-linux --providers System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets
+
+# Trace with networking providers and thread-time profile
+sudo dotnet-trace collect-linux --profile thread-time --providers System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets
+
+# Trace with specific profiles
+sudo dotnet-trace collect-linux --profile gc-verbose
+sudo dotnet-trace collect-linux --profile thread-time
+
+# Trace with additional Linux perf events
+sudo dotnet-trace collect-linux --perf-events <list-of-perf-events>
+
+# Output to a specific file
+sudo dotnet-trace collect-linux -o /tmp/trace.nettrace
+```
+
+When `--providers`, `--profile`, `--clrevents`, and `--perf-events` are not specified, `collect-linux` enables these profiles by default: `dotnet-common` (lightweight .NET runtime diagnostics) and `cpu-sampling` (kernel CPU sampling).
+
+## Container Usage
+
+```bash
+# Inside container (machine-wide — captures all processes in the container)
+sudo dotnet-trace collect-linux -o /tmp/trace.nettrace
+
+# Inside container (specific process)
+sudo dotnet-trace collect-linux -p 1 -o /tmp/trace.nettrace
+
+# Copy trace out
+kubectl cp <pod>:/tmp/trace.nettrace ./trace.nettrace
+```
+
+## Trade-offs
+
+- ✅ Machine-wide tracing without specifying a PID
+- ✅ Native (unmanaged) call stacks — essential for diagnosing native interop or runtime issues
+- ✅ Captures kernel events and native library events
+- ✅ Designed for Linux-first workflows
+- ❌ Requires root privileges
+- ❌ Only available on .NET 10 and later
+- ❌ Linux only (kernel >= 6.4)
+- ❌ Requires glibc >= 2.35 (not all supported Linux distros qualify)
+- ❌ Native code symbols must be present on disk next to the binary (or in a standard location) during trace capture for symbol resolution
+- ❌ Unable to trace cross-namespace processes

package/package/corpus/skills/dotnet-trace-collect/references/dotnet-trace-collect.md

@@ -0,0 +1,91 @@
+# dotnet-trace collect
+
+**Purpose**: Collect EventPipe traces for CPU profiling, event analysis, and runtime diagnostics.
+
+| Attribute | Value |
+|-----------|-------|
+| OS | Windows, Linux, macOS |
+| Runtime | Modern .NET (.NET Core 3.0+) |
+| .NET Framework | ❌ Not supported |
+| Admin required | No |
+| Container | Works inside container; use `--diagnostic-port` for sidecar |
+
+## Installation
+
+```bash
+# As a .NET global tool (requires .NET SDK)
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+dotnet tool install -g dotnet-trace
+
+# Direct download via aka.ms (no SDK required — useful in containers)
+# Linux x64
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+curl -JL https://aka.ms/dotnet-trace/linux-x64 -o dotnet-trace
+chmod +x dotnet-trace
+
+# Linux Arm64
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+curl -JL https://aka.ms/dotnet-trace/linux-arm64 -o dotnet-trace
+chmod +x dotnet-trace
+
+# Linux musl x64 (Alpine)
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+curl -JL https://aka.ms/dotnet-trace/linux-musl-x64 -o dotnet-trace
+chmod +x dotnet-trace
+
+# Windows x64
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+curl -JL https://aka.ms/dotnet-trace/win-x64 -o dotnet-trace.exe
+```
+
+## Common Commands
+
+```bash
+# List running .NET processes
+dotnet-trace ps
+
+# Collect a trace with the default profiles (dotnet-common and dotnet-sampled-thread-time)
+dotnet-trace collect -p <PID>
+
+# Collect with a specific profile
+dotnet-trace collect -p <PID> --profile dotnet-sampled-thread-time
+dotnet-trace collect -p <PID> --profile gc-verbose
+
+# Collect with specific providers
+dotnet-trace collect -p <PID> --providers Microsoft-DotNETCore-SampleProfiler,Microsoft-Windows-DotNETRuntime
+
+# Collect with networking providers (HTTP status codes, DNS, TLS, sockets)
+dotnet-trace collect -p <PID> --providers System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets
+
+# Collect for a fixed duration (time span in hh:mm:ss format)
+dotnet-trace collect -p <PID> --duration 00:00:30
+
+# Output in Speedscope format for web-based viewing
+dotnet-trace collect -p <PID> --format speedscope
+```
+
+## Output Formats
+
+| Format | Extension | Analysis Tool |
+|--------|-----------|---------------|
+| `nettrace` (default) | `.nettrace` | PerfView, Visual Studio, `dotnet-trace report` |
+| `speedscope` | `.speedscope.json` | Speedscope |
+| `chromium` | `.chromium.json` | Chrome DevTools (chrome://tracing) |
+
+## Container Usage
+
+```bash
+# Inside container (process is typically PID 1)
+dotnet-trace collect -p 1 -o /tmp/trace.nettrace
+
+# Copy trace out of container
+kubectl cp <pod>:/tmp/trace.nettrace ./trace.nettrace
+# or
+docker cp <container>:/tmp/trace.nettrace ./trace.nettrace
+```
+
+## Trade-offs
+
+- ✅ Cross-platform, no admin needed, lightweight
+- ❌ No native (unmanaged) call stacks — only managed frames
+- ❌ Less system-level detail than ETW (PerfView) or perf (perfcollect)

package/package/corpus/skills/dotnet-trace-collect/references/perfcollect.md

@@ -0,0 +1,200 @@
+# perfcollect
+
+## Contents
+
+- Installation
+- Common Commands
+- Container Usage
+- Kubernetes Usage
+- Analyzing perfcollect Output
+- Trade-offs
+
+**Purpose**: Wrapper script for `perf` and `LTTng` on Linux. Collects CPU profiles with native call stacks.
+
+> **Cratis:** Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+
+| Attribute | Value |
+|-----------|-------|
+| OS | Linux only |
+| Runtime | Modern .NET (.NET Core 2.0+) |
+| .NET Framework | ❌ Not supported |
+| Admin required | Yes (root) |
+| Container | Needs `SYS_ADMIN` / `--privileged` |
+
+## Installation
+
+```bash
+# Download the script
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+curl -OL https://aka.ms/perfcollect
+chmod +x perfcollect
+
+# Install prerequisites (perf, LTTng)
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+sudo ./perfcollect install
+```
+
+## Common Commands
+
+```bash
+# Collect a trace (runs until Ctrl+C)
+sudo ./perfcollect collect mytrace
+
+# Collect for a specific duration
+sudo timeout 30 ./perfcollect collect mytrace
+```
+
+## Container Usage
+
+```bash
+# Docker — run with privileged mode
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+docker run --privileged ...
+```
+
+## Kubernetes Usage
+
+In Kubernetes, use a **diagnostics sidecar container** to avoid modifying your application image. The sidecar runs alongside your app, shares its process namespace and `/tmp` directory, and contains the diagnostic tools.
+
+### Step 1: Add a privileged diagnostics sidecar
+
+Add a diagnostics container to your deployment and mark it as privileged:
+
+```yaml
+      - name: diagnostics-container
+        image: ubuntu
+        command: ["/bin/sh", "-c", "sleep infinity"]
+        securityContext:
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+          privileged: true
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+          allowPrivilegeEscalation: true
+        volumeMounts:
+        - name: shared-tmp
+          mountPath: /tmp
+```
+
+### Step 2: Enable shared process namespace
+
+Set `shareProcessNamespace: true` in the pod spec so the sidecar can see and profile the app's processes:
+
+```yaml
+    spec:
+      shareProcessNamespace: true
+```
+
+### Step 3: Share /tmp between containers
+
+Create an `emptyDir` volume mounted at `/tmp` in both the app and sidecar containers. This is needed for perf map files (`perf-$pid.map`), perfcollect logs, and other profiling artifacts:
+
+```yaml
+      volumes:
+      - name: shared-tmp
+        emptyDir: {}
+```
+
+Mount it in both containers:
+
+```yaml
+        volumeMounts:
+        - name: shared-tmp
+          mountPath: /tmp
+```
+
+### Step 4: Set environment variables in the app container
+
+Enable perf map generation and LTTng event logging in the application container:
+
+```yaml
+        env:
+        - name: COMPlus_PerfMapEnabled
+          value: "1"
+        - name: COMPlus_EnableEventLog
+          value: "1"
+```
+
+### Step 5: Collect the trace
+
+Connect to the cluster node, exec into the diagnostics sidecar, install perfcollect, and capture:
+
+```bash
+# Exec into the diagnostics sidecar
+kubectl exec -it <pod-name> -c diagnostics-container -- /bin/bash
+
+# Inside the sidecar: install perfcollect
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+curl -OL https://aka.ms/perfcollect
+chmod +x perfcollect
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+./perfcollect install
+
+# Capture a trace
+./perfcollect collect mytrace
+```
+
+This produces `mytrace.trace.zip`, which can be copied out and analyzed.
+
+### End-to-end Kubernetes deployment example
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: sample
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: sample
+  template:
+    metadata:
+      labels:
+        app: sample
+    spec:
+      shareProcessNamespace: true
+      volumes:
+      - name: shared-tmp
+        emptyDir: {}
+      containers:
+      - name: sample-app
+        image: myapp:latest
+        ports:
+        - containerPort: 80
+        env:
+        - name: COMPlus_PerfMapEnabled
+          value: "1"
+        - name: COMPlus_EnableEventLog
+          value: "1"
+        volumeMounts:
+        - name: shared-tmp
+          mountPath: /tmp
+      - name: diagnostics-container
+        image: ubuntu
+        command: ["/bin/sh", "-c", "sleep infinity"]
+        securityContext:
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+          privileged: true
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+          allowPrivilegeEscalation: true
+        volumeMounts:
+        - name: shared-tmp
+          mountPath: /tmp
+```
+
+## Analyzing perfcollect Output
+
+The output is a `*.trace.zip` file containing `perf.data.nl`. To analyze:
+
+1. Copy the `.trace.zip` to a Windows machine
+2. Open with PerfView — it can read perfcollect output and display flame graphs
+
+## Trade-offs
+
+- ✅ Captures native (unmanaged) call stacks — essential for diagnosing native interop or runtime issues
+- ✅ Uses kernel-level `perf` for accurate CPU profiling
+- ❌ Requires root/admin privileges
+- ❌ Linux only
+> **Cratis:** Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+- ❌ In containers, requires `SYS_ADMIN` or `--privileged`