On-demand Go profiling

Kanshi can request a bounded diagnostic capture from a Go service already exposing net/http/pprof. Profiling is opt-in: the Agent reports only configured target names, keeps their URLs local, and rejects Dashboard-supplied URLs.

Caution

Profiles can reveal function names and source filenames. Keep pprof endpoints on loopback or a private service network, never expose them to the public internet, and approve only services whose diagnostic data operators may access.

Approve targets

Use an explicit endpoint when its port is fixed:

curl -fsSL https://kanshi.dev/install.sh | \
  sudo KANSHI_PPROF_TARGETS='checkout=http://127.0.0.1:6060' sh -s -- --service

Use bounded discovery when a service may bind one of a few ports:

curl -fsSL https://kanshi.dev/install.sh | \
  sudo KANSHI_PPROF_DISCOVERY='checkout=http://127.0.0.1:6059-6061' sh -s -- --service

Discovery probes only the configured host, lowest port first, when a capture begins. It does not scan CIDR ranges. Each range may contain at most 8 ports, and an Agent may expose at most 20 unique names across explicit and discovered targets.

Capture a profile

Open an Agent, select Profiles, choose an approved target and capture type, then start the capture. Only one capture may be queued or active per Agent.

Type	Duration	Dashboard result
CPU	5, 10, or 30 seconds	Flamegraph and raw pprof download
Execution trace	1 or 5 seconds	Metadata and raw trace download
Heap, allocs, goroutine, mutex, block, thread creation	Instant	Flamegraph and raw pprof download

Mutex and block profiles can legitimately be empty when the service has not enabled the corresponding runtime sampling or has no contention. The raw artifact remains available even when there is no flamegraph data.

Captures are limited to 10 MiB, queued work expires after five minutes, and completed artifacts are retained for 24 hours. Metrics and trace shipping continue while the Agent’s separate capture worker is busy.

Use Go tools

Download any artifact from its capture row. Inspect pprof captures locally:

go tool pprof ./your-service capture.pb.gz

Open an execution trace with:

go tool trace capture.trace

The Dashboard flamegraph supports sample selection, hover details, click-to-zoom, and an accessible top-functions table. Execution traces are intentionally downloaded for go tool trace instead of converted to flamegraphs.