@cratis/pi 7.102.0 → 7.103.1

package/package/corpus/skills/dump-collect/references/container-dumps.md

@@ -0,0 +1,412 @@
+# Container Crash Dump Collection
+
+## Contents
+
+- Docker
+- Kubernetes
+- Verification
+- Container Considerations
+- Troubleshooting
+
+| Need | Tool | Runtime | Requires |
+|------|------|---------|----------|
+| Automatic dump on crash (CoreCLR) | `DOTNET_DbgEnableMiniDump` env vars + `createdump` | CoreCLR | `SYS_PTRACE`, volume mount |
+| Automatic dump on crash (NativeAOT, preferred) | `--ulimit core=-1` + `core_pattern` | NativeAOT | `SYS_PTRACE`, volume mount |
+| Automatic dump on crash (NativeAOT, alternative) | `createdump` + `DOTNET_DbgEnableMiniDump` env vars | NativeAOT | `SYS_PTRACE`, volume mount |
+| On-demand from running container | `dotnet-dump collect` (CoreCLR), `gcore` (NativeAOT) | Per-runtime | `SYS_PTRACE` |
+| Copy dump out of container | `docker cp` / `kubectl cp` | Both | — |
+
+Collecting crash dumps from .NET applications running in Docker or Kubernetes containers requires additional configuration for capabilities, storage, and environment variables.
+
+> **Note:** The `%e`, `%p`, `%h`, `%t` format specifiers in `DOTNET_DbgMiniDumpName` require .NET 7+. On .NET 6, use a literal path instead.
+>
+> **Dump types** for `DOTNET_DbgMiniDumpType`: 1=Mini, 2=Heap, 3=Triage, 4=Full. Use 4 for maximum diagnostic value. NativeAOT and CoreCLR single-file apps only support full dumps (type 4).
+
+## Docker
+
+### Required Capability
+
+The `SYS_PTRACE` capability is required for `dotnet-dump collect`, `createdump`, and `gcore` to attach to processes:
+
+```bash
+# docker run
+docker run --cap-add=SYS_PTRACE -v /tmp/dumps:/dumps myapp
+
+# docker compose
+```
+
+```yaml
+# docker-compose.yml
+services:
+  myapp:
+    image: myapp
+    cap_add:
+      - SYS_PTRACE
+    volumes:
+      - ./dumps:/dumps
+    environment:
+      # CoreCLR automatic crash dumps
+      DOTNET_DbgEnableMiniDump: "1"
+      DOTNET_DbgMiniDumpType: "4"
+      DOTNET_DbgMiniDumpName: "/dumps/%e_%p_%t.dmp"
+      DOTNET_EnableCrashReport: "1"
+```
+
+### CoreCLR in Docker
+
+Add environment variables to enable automatic crash dumps. Either in `docker run`:
+
+```bash
+docker run --cap-add=SYS_PTRACE \
+  -v /tmp/dumps:/dumps \
+  -e DOTNET_DbgEnableMiniDump=1 \
+  -e DOTNET_DbgMiniDumpType=4 \
+  -e DOTNET_DbgMiniDumpName="/dumps/%e_%p_%t.dmp" \
+  -e DOTNET_EnableCrashReport=1 \
+  myapp
+```
+
+Or in the Dockerfile (baked into the image):
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/aspnet:10.0
+
+# Configure crash dump collection
+ENV DOTNET_DbgEnableMiniDump=1
+ENV DOTNET_DbgMiniDumpType=4
+ENV DOTNET_DbgMiniDumpName="/dumps/%e_%p_%t.dmp"
+ENV DOTNET_EnableCrashReport=1
+
+# Create dump directory
+RUN mkdir -p /dumps
+
+COPY --from=build /app .
+ENTRYPOINT ["dotnet", "myapp.dll"]
+```
+
+### NativeAOT in Docker
+
+Since NativeAOT only supports full dumps, OS-level core dump mechanisms are the simplest approach — no extra tooling to copy or configure.
+
+**Preferred: OS-level core dumps:**
+
+```bash
+docker run --cap-add=SYS_PTRACE \
+  --ulimit core=-1 \
+  -v /tmp/dumps:/dumps \
+  myapp
+```
+
+**Note:** You may also need to set the core pattern inside the container. If the host's `core_pattern` pipes to `systemd-coredump`, container core dumps may not be written where expected. Override at runtime:
+
+```bash
+docker run --cap-add=SYS_PTRACE \
+  --ulimit core=-1 \
+# Cratis: Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+  --privileged \
+  -v /tmp/dumps:/dumps \
+  myapp sh -c 'echo "/dumps/core.%e.%p" > /proc/sys/kernel/core_pattern && exec ./myapp'
+```
+
+> **Cratis:** Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+⚠️ `--privileged` is needed to write to `/proc/sys/kernel/core_pattern`. For production, prefer configuring the core pattern on the host instead.
+
+**Alternative: Use createdump with DOTNET_DbgEnableMiniDump** (same env vars as CoreCLR). Copy `createdump` next to the app binary in the image:
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/runtime-deps:10.0
+
+# Copy createdump from the runtime (match your .NET version)
+COPY --from=mcr.microsoft.com/dotnet/runtime:10.0 /usr/share/dotnet/shared/Microsoft.NETCore.App/ /tmp/runtime/
+RUN find /tmp/runtime -name createdump -exec cp {} /app/ \; && rm -rf /tmp/runtime/
+
+# Configure crash dump collection
+ENV DOTNET_DbgEnableMiniDump=1
+ENV DOTNET_DbgMiniDumpType=4
+ENV DOTNET_DbgMiniDumpName="/dumps/%e_%p_%t.dmp"
+
+RUN mkdir -p /dumps
+
+COPY --from=build /app .
+ENTRYPOINT ["./myapp"]
+```
+
+For .NET 11+, use `DOTNET_DbgCreateDumpToolPath` instead of co-locating:
+
+```dockerfile
+ENV DOTNET_DbgCreateDumpToolPath=/opt/tools/createdump
+ENV DOTNET_DbgEnableMiniDump=1
+ENV DOTNET_DbgMiniDumpType=4
+ENV DOTNET_DbgMiniDumpName="/dumps/%e_%p_%t.dmp"
+```
+
+Run with:
+```bash
+docker run --cap-add=SYS_PTRACE \
+  -v /tmp/dumps:/dumps \
+  myapp
+```
+
+### On-Demand Collection in Docker
+
+```bash
+# Find the container and process
+docker exec <container> dotnet-dump ps         # CoreCLR
+docker exec <container> sh -c 'ps aux | grep myapp'    # NativeAOT
+
+# Collect dump (CoreCLR)
+docker exec <container> dotnet-dump collect -p <pid> --output /dumps/myapp.dmp
+
+# Collect dump (NativeAOT — requires gdb/gcore in the image)
+docker exec <container> gcore -o /dumps/myapp <pid>
+
+# Copy dump out of container (alternative to volume mount)
+docker cp <container>:/dumps/myapp.dmp ./myapp.dmp
+```
+
+## Kubernetes
+
+### Pod Spec for CoreCLR
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp
+spec:
+  containers:
+    - name: myapp
+      image: myapp:latest
+      securityContext:
+        capabilities:
+          add: ["SYS_PTRACE"]
+      env:
+        - name: DOTNET_DbgEnableMiniDump
+          value: "1"
+        - name: DOTNET_DbgMiniDumpType
+          value: "4"
+        - name: DOTNET_DbgMiniDumpName
+          value: "/dumps/%e_%p_%t.dmp"
+        - name: DOTNET_EnableCrashReport
+          value: "1"
+      volumeMounts:
+        - name: dumps
+          mountPath: /dumps
+  volumes:
+    - name: dumps
+      emptyDir:
+        sizeLimit: 5Gi    # Adjust based on expected dump size
+```
+
+### Pod Spec for NativeAOT
+
+**Preferred: OS-level core dumps** (simplest — no extra tooling needed):
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-nativeaot
+spec:
+  containers:
+    - name: myapp
+      image: myapp:latest
+      securityContext:
+        capabilities:
+          add: ["SYS_PTRACE"]
+      command: ["/bin/sh", "-c"]
+      args: ["ulimit -c unlimited && exec ./myapp"]
+      volumeMounts:
+        - name: dumps
+          mountPath: /dumps
+  volumes:
+    - name: dumps
+      emptyDir:
+        sizeLimit: 10Gi
+```
+
+**Alternative: Use createdump** (bundled in the image next to the app, or via `DOTNET_DbgCreateDumpToolPath` on .NET 11+):
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-nativeaot
+spec:
+  containers:
+    - name: myapp
+      image: myapp:latest
+      securityContext:
+        capabilities:
+          add: ["SYS_PTRACE"]
+      env:
+        - name: DOTNET_DbgEnableMiniDump
+          value: "1"
+        - name: DOTNET_DbgMiniDumpType
+          value: "4"
+        - name: DOTNET_DbgMiniDumpName
+          value: "/dumps/%e_%p_%t.dmp"
+        # .NET 11+ only — uncomment if createdump is not next to the binary:
+        # - name: DOTNET_DbgCreateDumpToolPath
+        #   value: "/opt/tools/createdump"
+      volumeMounts:
+        - name: dumps
+          mountPath: /dumps
+  volumes:
+    - name: dumps
+      emptyDir:
+        sizeLimit: 5Gi
+```
+
+### Using a Persistent Volume for Dumps
+
+For production, use a PersistentVolumeClaim instead of `emptyDir` so dumps survive pod restarts:
+
+```yaml
+volumes:
+  - name: dumps
+    persistentVolumeClaim:
+      claimName: dump-storage
+
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: dump-storage
+spec:
+  accessModes: ["ReadWriteOnce"]
+  resources:
+    requests:
+      storage: 20Gi
+```
+
+### On-Demand Collection in Kubernetes
+
+```bash
+# Find the pod and process
+kubectl exec <pod> -- dotnet-dump ps           # CoreCLR
+kubectl exec <pod> -- sh -c 'ps aux | grep myapp'      # NativeAOT
+
+# Collect dump
+kubectl exec <pod> -- dotnet-dump collect -p <pid> --output /dumps/myapp.dmp
+
+# Copy dump out of the pod
+kubectl cp <pod>:/dumps/myapp.dmp ./myapp.dmp
+```
+
+### Deployment-Level Configuration
+
+To apply dump collection to all pods in a Deployment:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: myapp
+spec:
+  template:
+    spec:
+      containers:
+        - name: myapp
+          image: myapp:latest
+          securityContext:
+            capabilities:
+              add: ["SYS_PTRACE"]
+          env:
+            - name: DOTNET_DbgEnableMiniDump
+              value: "1"
+            - name: DOTNET_DbgMiniDumpType
+              value: "4"
+            - name: DOTNET_DbgMiniDumpName
+              value: "/dumps/%e_%p_%t.dmp"
+          volumeMounts:
+            - name: dumps
+              mountPath: /dumps
+      volumes:
+        - name: dumps
+          emptyDir:
+            sizeLimit: 5Gi
+```
+
+## Verification
+
+**Docker:**
+
+```bash
+# Check env vars inside the container
+docker exec <container> env | grep DOTNET_Dbg
+
+# Check dump directory exists and is writable
+docker exec <container> ls -la /dumps/
+
+# Check createdump is available (NativeAOT)
+docker exec <container> ls -la /app/createdump 2>/dev/null || echo "createdump not co-located"
+
+# After a crash, check for dump files
+docker exec <container> sh -c 'ls -la /dumps/*.dmp' 2>/dev/null
+# Or from the host via volume mount:
+ls -la /tmp/dumps/*.dmp
+```
+
+**Kubernetes:**
+
+```bash
+# Check env vars
+kubectl exec <pod> -- env | grep DOTNET_Dbg
+
+# Check dump directory
+kubectl exec <pod> -- ls -la /dumps/
+
+# After a crash, list dumps
+kubectl exec <pod> -- sh -c 'ls -la /dumps/*.dmp' 2>/dev/null
+
+# Copy dumps out for inspection
+kubectl cp <pod>:/dumps/ ./dumps/
+```
+
+## Container Considerations
+
+### Non-Root Users
+
+If your container runs as a non-root user, ensure the dump directory is writable:
+
+```dockerfile
+RUN mkdir -p /dumps && chown -R app:app /dumps
+USER app
+```
+
+For Kubernetes, use an init container or `securityContext.fsGroup`:
+
+```yaml
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 1000
+  fsGroup: 1000    # matches the app user's group
+```
+
+When using `runAsNonRoot: true`, the dump directory must be writable by the non-root user. Use `fsGroup` to grant group write access to the mounted volume, or set permissions in the Dockerfile.
+
+### Alpine / musl-Based Images
+
+`createdump`, `dotnet-dump`, and CoreCLR automatic crash dumps all work on the supported .NET Alpine images. No special configuration is needed beyond the standard setup described above.
+
+### SELinux / AppArmor
+
+On hosts with SELinux or AppArmor, `SYS_PTRACE` alone may not be sufficient:
+
+- **SELinux**: The container may need `--security-opt label=disable` or an appropriate SELinux policy allowing ptrace
+- **AppArmor**: Use `--security-opt apparmor=unconfined` for debugging, or create a custom profile that allows ptrace
+
+⚠️ Disabling security modules is acceptable for debugging but should not be used in production.
+
+## Troubleshooting
+
+> **Cratis:** Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `dotnet-dump collect` fails with "permission denied" | Missing `SYS_PTRACE` capability | Add `SYS_PTRACE` to securityContext / cap_add |
+| Dump file not created on crash | Dump directory doesn't exist | Ensure `/dumps` directory exists in the image or init container |
+| Core dump goes to wrong location | Host `core_pattern` overrides container | Configure `core_pattern` on the host or use `--privileged` |
+| Dump file is 0 bytes | Disk space exhausted | Increase `emptyDir.sizeLimit` or PVC size |
+| `createdump` not found in container | Minimal runtime image | For CoreCLR: use `dotnet-dump collect` instead. For NativeAOT: copy `createdump` from the runtime image (see NativeAOT in Docker section) or use the full SDK image |

package/package/corpus/skills/dump-collect/references/coreclr-dumps.md

@@ -0,0 +1,108 @@
+# CoreCLR Crash Dump Collection
+
+## Contents
+
+- Automatic Crash Dumps (All Platforms)
+- On-Demand Dump Collection
+- Verification
+
+| Need | Tool | Platforms |
+|------|------|-----------|
+| Automatic dump on crash | `DOTNET_DbgEnableMiniDump` env vars | All |
+| On-demand from running process | `dotnet-dump collect` (recommended) | All |
+| On-demand via OS tools | `gcore` (Linux) | Linux |
+
+## Automatic Crash Dumps (All Platforms)
+
+CoreCLR has built-in crash dump support via environment variables. Set these before launching the app:
+
+```bash
+# Enable crash dumps (required)
+export DOTNET_DbgEnableMiniDump=1
+
+# Dump type: 1=Mini, 2=Heap, 3=Triage, 4=Full
+# Use 4 (Full) for maximum diagnostic value, 1 (Mini) for smaller files
+export DOTNET_DbgMiniDumpType=4
+
+# Output path — supports format specifiers (.NET 7+):
+#   %p = PID, %e = process name, %h = hostname, %t = timestamp
+export DOTNET_DbgMiniDumpName=/tmp/dumps/%e_%p_%t.dmp
+
+# Optional: generate a JSON crash report alongside the dump
+export DOTNET_EnableCrashReport=1
+
+# Optional: diagnostics if dump creation itself fails
+export DOTNET_CreateDumpDiagnostics=1
+```
+
+**On Windows (PowerShell):**
+```powershell
+$env:DOTNET_DbgEnableMiniDump = "1"
+$env:DOTNET_DbgMiniDumpType = "4"
+$env:DOTNET_DbgMiniDumpName = "C:\dumps\%e_%p_%t.dmp"
+$env:DOTNET_EnableCrashReport = "1"
+```
+
+### Dump Type Reference
+
+| Value | Type | Size | Use When |
+|-------|------|------|----------|
+| 1 | Mini | Small | Stack traces only, minimal disk usage |
+| 2 | Heap | Large | Need to inspect managed heap objects |
+| 3 | Triage | Small | The same as mini, but redacts known file paths |
+| 4 | Full | Largest | Full process memory, maximum diagnostic value |
+
+### Important Notes
+
+- The dump output directory must exist before the crash — CoreCLR will not create it.
+- Format specifiers (`%p`, `%e`, `%h`, `%t`) require .NET 7+. On .NET 6, use a literal path.
+- The legacy `COMPlus_` prefix (e.g., `COMPlus_DbgEnableMiniDump`) still works but `DOTNET_` is preferred for .NET 6+.
+- Single-file published apps only support full dumps (`DOTNET_DbgMiniDumpType=4`), same as NativeAOT.
+
+## On-Demand Dump Collection
+
+### Using dotnet-dump (Recommended)
+
+```bash
+# Install (one-time, 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-dump
+
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+# Without the SDK, download directly from https://github.com/dotnet/diagnostics/releases
+
+# List .NET processes
+dotnet-dump ps
+
+# Collect a dump from a running process
+dotnet-dump collect -p <pid>
+
+# Specify dump type and output path
+dotnet-dump collect -p <pid> --type Full --output /tmp/dumps/myapp.dmp
+```
+
+**Supported `--type` values:** `Full`, `Heap`, `Mini`
+
+### Using gcore (Linux Only)
+
+```bash
+# Requires gdb installed
+gcore -o /tmp/dumps/myapp <pid>
+# Produces /tmp/dumps/myapp.<pid>
+```
+
+## Verification
+
+After enabling crash dumps, verify the configuration:
+
+```bash
+# Check env vars are set
+env | grep DOTNET_Dbg
+env | grep DOTNET_EnableCrashReport
+
+# Ensure dump directory exists and is writable
+ls -la /tmp/dumps/
+
+# After a crash, check for dump files
+ls -la /tmp/dumps/*.dmp
+```