Skip to content

Commit b3b8d4e

Browse files
niemyjskiniemyjski
committed
next: dep updates + skills
1 parent bd7e4fe commit b3b8d4e

File tree

23 files changed

+4144
-311
lines changed

23 files changed

+4144
-311
lines changed

‎src/Exceptionless.AppHost/Exceptionless.AppHost.csproj‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<Project Sdk="Aspire.AppHost.Sdk/13.1.2">
1+
<Project Sdk="Aspire.AppHost.Sdk/13.1.3">
22
<PropertyGroup>
33
<OutputType>Exe</OutputType>
44
<TargetFramework>net10.0</TargetFramework>
@@ -7,9 +7,9 @@
77
<UserSecretsId>a9c2ddcc-e51d-4cd1-9782-96e1d74eec87</UserSecretsId>
88
</PropertyGroup>
99
<ItemGroup>
10-
<PackageReference Include="Aspire.Hosting.Azure.Storage" Version="13.1.2" />
11-
<PackageReference Include="Aspire.Hosting.JavaScript" Version="13.1.2" />
12-
<PackageReference Include="Aspire.Hosting.Redis" Version="13.1.2" />
10+
<PackageReference Include="Aspire.Hosting.Azure.Storage" Version="13.1.3" />
11+
<PackageReference Include="Aspire.Hosting.JavaScript" Version="13.1.3" />
12+
<PackageReference Include="Aspire.Hosting.Redis" Version="13.1.3" />
1313
<PackageReference Include="AspNetCore.HealthChecks.Elasticsearch" Version="9.0.0" />
1414
</ItemGroup>
1515

‎src/Exceptionless.Web/ClientApp/.agents/skills/dotnet-trace-collect/SKILL.md‎

Lines changed: 251 additions & 0 deletions
Large diffs are not rendered by default.

‎src/Exceptionless.Web/ClientApp/.agents/skills/dotnet-trace-collect/references/dotnet-monitor.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# dotnet-monitor
2+
3+
**Purpose**: REST API-based diagnostics collection, designed for container and Kubernetes environments.
4+
5+
| Attribute | Value |
6+
|-----------|-------|
7+
| OS | Windows, Linux, macOS |
8+
| Runtime | Modern .NET (.NET Core 3.1+) |
9+
| .NET Framework | ❌ Not supported |
10+
| Admin required | No |
11+
| Container | ✅ Designed for containers/K8s — runs as a sidecar |
12+
13+
## Installation
14+
15+
```bash
16+
# As a global tool
17+
dotnet tool install -g dotnet-monitor
18+
19+
# As a container image (for K8s sidecar)
20+
# mcr.microsoft.com/dotnet/monitor
21+
```
22+
23+
## Common Commands
24+
25+
```bash
26+
# Production-safe default: keep auth enabled (default) and bind to loopback
27+
dotnet-monitor collect --urls http://127.0.0.1:52323 --metricUrls http://127.0.0.1:52325
28+
29+
# Dev-only shortcut in isolated environments (avoid in production)
30+
dotnet-monitor collect --urls http://127.0.0.1:52323 --no-auth
31+
```
32+
33+
## Security Guidance (Production)
34+
35+
- Do **not** run `dotnet-monitor` with `--no-auth` on production workloads.
36+
- Bind to localhost (`127.0.0.1`) and access through `kubectl port-forward` (or another local-only tunnel).
37+
- If remote access is required, keep auth enabled and restrict network exposure to trusted operators.
38+
39+
## REST API Endpoints
40+
41+
```bash
42+
# Access via local tunnel (recommended in Kubernetes)
43+
kubectl port-forward pod/<pod-name> 52323:52323
44+
45+
# List processes (auth enabled by default)
46+
curl -H "Authorization: Bearer <monitor-token>" http://localhost:52323/processes
47+
48+
# Collect a trace
49+
curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace http://localhost:52323/trace?pid=<PID>&durationSeconds=30
50+
51+
# Collect GC trace
52+
curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace "http://localhost:52323/trace?pid=<PID>&profile=gc-verbose&durationSeconds=30"
53+
54+
# Collect trace with networking providers (HTTP status codes, DNS, TLS, sockets)
55+
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"
56+
57+
# Get live metrics
58+
curl -H "Authorization: Bearer <monitor-token>" http://localhost:52323/livemetrics?pid=<PID>
59+
```
60+
61+
## Kubernetes Sidecar Setup
62+
63+
```yaml
64+
# Pod spec with dotnet-monitor as sidecar
65+
spec:
66+
containers:
67+
- name: app
68+
image: myapp:latest
69+
volumeMounts:
70+
- name: diag
71+
mountPath: /tmp
72+
- name: monitor
73+
image: mcr.microsoft.com/dotnet/monitor:latest
74+
args: ["collect", "--urls", "http://127.0.0.1:52323", "--metricUrls", "http://127.0.0.1:52325"]
75+
volumeMounts:
76+
- name: diag
77+
mountPath: /tmp
78+
ports:
79+
- containerPort: 52323
80+
volumes:
81+
- name: diag
82+
emptyDir: {}
83+
```
84+
85+
The shared `/tmp` volume allows `dotnet-monitor` to access the app's diagnostic Unix domain socket.
86+
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.
87+
88+
## Trade-offs
89+
90+
- ✅ Purpose-built for containers and Kubernetes
91+
- ✅ No tools needed inside the app container
92+
- ✅ REST API is easy to automate and integrate
93+
- ❌ Requires sidecar setup and shared volume
94+
- ❌ Additional resource overhead from sidecar container
95+
- ❌ Requires authentication setup (API key or `--no-auth` flag)
96+
- ⚠️ **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.

‎src/Exceptionless.Web/ClientApp/.agents/skills/dotnet-trace-collect/references/dotnet-trace-collect-linux.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# dotnet-trace collect-linux (.NET 10+)
2+
3+
**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.
4+
5+
| Attribute | Value |
6+
|-----------|-------|
7+
| OS | Linux only (kernel >= 6.4 with `CONFIG_USER_EVENTS=y`) |
8+
| Runtime | .NET 10+ only |
9+
| .NET Framework | ❌ Not supported |
10+
| Admin required | Yes (root) |
11+
| Container | Works inside container (requires root) |
12+
| glibc | >= 2.35 (not supported on Alpine 3.22, CentOS Stream 9, or RHEL 9-based distros) |
13+
14+
## Key Differences from `dotnet-trace collect`
15+
16+
| Feature | `collect` | `collect-linux` |
17+
|---------|-----------|-----------------|
18+
| Trace all processes simultaneously | No | Yes (default — no PID required) |
19+
| Capture native library and kernel events | No | Yes |
20+
| Event callstacks include native frames | No | Yes |
21+
| Requires admin/root | No | Yes |
22+
23+
## Usage
24+
25+
```bash
26+
# Machine-wide trace (all processes, no PID needed)
27+
sudo dotnet-trace collect-linux
28+
29+
# Trace a specific process
30+
sudo dotnet-trace collect-linux -p <PID>
31+
32+
# Trace a process by name
33+
sudo dotnet-trace collect-linux -n <process-name>
34+
35+
# Trace for a specific duration
36+
sudo dotnet-trace collect-linux --duration 00:00:30
37+
38+
# Trace with specific providers
39+
sudo dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime
40+
41+
# Trace with networking providers (HTTP status codes, DNS, TLS, sockets)
42+
sudo dotnet-trace collect-linux --providers System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets
43+
44+
# Trace with networking providers and thread-time profile
45+
sudo dotnet-trace collect-linux --profile thread-time --providers System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets
46+
47+
# Trace with specific profiles
48+
sudo dotnet-trace collect-linux --profile gc-verbose
49+
sudo dotnet-trace collect-linux --profile thread-time
50+
51+
# Trace with additional Linux perf events
52+
sudo dotnet-trace collect-linux --perf-events <list-of-perf-events>
53+
54+
# Output to a specific file
55+
sudo dotnet-trace collect-linux -o /tmp/trace.nettrace
56+
```
57+
58+
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).
59+
60+
## Container Usage
61+
62+
```bash
63+
# Inside container (machine-wide — captures all processes in the container)
64+
sudo dotnet-trace collect-linux -o /tmp/trace.nettrace
65+
66+
# Inside container (specific process)
67+
sudo dotnet-trace collect-linux -p 1 -o /tmp/trace.nettrace
68+
69+
# Copy trace out
70+
kubectl cp <pod>:/tmp/trace.nettrace ./trace.nettrace
71+
```
72+
73+
## Trade-offs
74+
75+
- ✅ Machine-wide tracing without specifying a PID
76+
- ✅ Native (unmanaged) call stacks — essential for diagnosing native interop or runtime issues
77+
- ✅ Captures kernel events and native library events
78+
- ✅ Designed for Linux-first workflows
79+
- ❌ Requires root privileges
80+
- ❌ Only available on .NET 10 and later
81+
- ❌ Linux only (kernel >= 6.4)
82+
- ❌ Requires glibc >= 2.35 (not all supported Linux distros qualify)
83+
- ❌ Native code symbols must be present on disk next to the binary (or in a standard location) during trace capture for symbol resolution
84+
- ❌ Unable to trace cross-namespace processes

‎src/Exceptionless.Web/ClientApp/.agents/skills/dotnet-trace-collect/references/dotnet-trace-collect.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# dotnet-trace collect
2+
3+
**Purpose**: Collect EventPipe traces for CPU profiling, event analysis, and runtime diagnostics.
4+
5+
| Attribute | Value |
6+
|-----------|-------|
7+
| OS | Windows, Linux, macOS |
8+
| Runtime | Modern .NET (.NET Core 3.0+) |
9+
| .NET Framework | ❌ Not supported |
10+
| Admin required | No |
11+
| Container | Works inside container; use `--diagnostic-port` for sidecar |
12+
13+
## Installation
14+
15+
```bash
16+
# As a .NET global tool (requires .NET SDK)
17+
dotnet tool install -g dotnet-trace
18+
19+
# Direct download via aka.ms (no SDK required — useful in containers)
20+
# Linux x64
21+
curl -JL https://aka.ms/dotnet-trace/linux-x64 -o dotnet-trace
22+
chmod +x dotnet-trace
23+
24+
# Linux Arm64
25+
curl -JL https://aka.ms/dotnet-trace/linux-arm64 -o dotnet-trace
26+
chmod +x dotnet-trace
27+
28+
# Linux musl x64 (Alpine)
29+
curl -JL https://aka.ms/dotnet-trace/linux-musl-x64 -o dotnet-trace
30+
chmod +x dotnet-trace
31+
32+
# Windows x64
33+
curl -JL https://aka.ms/dotnet-trace/win-x64 -o dotnet-trace.exe
34+
```
35+
36+
## Common Commands
37+
38+
```bash
39+
# List running .NET processes
40+
dotnet-trace ps
41+
42+
# Collect a trace with the default profiles (dotnet-common and dotnet-sampled-thread-time)
43+
dotnet-trace collect -p <PID>
44+
45+
# Collect with a specific profile
46+
dotnet-trace collect -p <PID> --profile dotnet-sampled-thread-time
47+
dotnet-trace collect -p <PID> --profile gc-verbose
48+
49+
# Collect with specific providers
50+
dotnet-trace collect -p <PID> --providers Microsoft-DotNETCore-SampleProfiler,Microsoft-Windows-DotNETRuntime
51+
52+
# Collect with networking providers (HTTP status codes, DNS, TLS, sockets)
53+
dotnet-trace collect -p <PID> --providers System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets
54+
55+
# Collect for a fixed duration (time span in hh:mm:ss format)
56+
dotnet-trace collect -p <PID> --duration 00:00:30
57+
58+
# Output in Speedscope format for web-based viewing
59+
dotnet-trace collect -p <PID> --format speedscope
60+
```
61+
62+
## Output Formats
63+
64+
| Format | Extension | Analysis Tool |
65+
|--------|-----------|---------------|
66+
| `nettrace` (default) | `.nettrace` | PerfView, Visual Studio, `dotnet-trace report` |
67+
| `speedscope` | `.speedscope.json` | [Speedscope](https://www.speedscope.app/) (web) |
68+
| `chromium` | `.chromium.json` | Chrome DevTools (chrome://tracing) |
69+
70+
## Container Usage
71+
72+
```bash
73+
# Inside container (process is typically PID 1)
74+
dotnet-trace collect -p 1 -o /tmp/trace.nettrace
75+
76+
# Copy trace out of container
77+
kubectl cp <pod>:/tmp/trace.nettrace ./trace.nettrace
78+
# or
79+
docker cp <container>:/tmp/trace.nettrace ./trace.nettrace
80+
```
81+
82+
## Trade-offs
83+
84+
- ✅ Cross-platform, no admin needed, lightweight
85+
- ❌ No native (unmanaged) call stacks — only managed frames
86+
- ❌ Less system-level detail than ETW (PerfView) or perf (perfcollect)

0 commit comments

Comments
 (0)