How do I enable pprof on Cosmo Router?

Set the PPROF_ADDR environment variable to the address you want the server to listen on, for example :6060. The router starts an HTTP server with the standard Go pprof endpoints. When PPROF_ADDR is unset, pprof is off and adds no overhead.

Which profiles are available?

Heap (memory allocations), profile (CPU), goroutine (active goroutines and stack traces), threadcreate (thread creation), and block (blocking operations).

How long is a CPU profile?

CPU profiles default to 30 seconds. The duration is configurable via the seconds query parameter; for example curl http://localhost:6060/debug/pprof/profile?seconds=60 captures a one-minute profile.

How do I visualize a profile?

Use go tool pprof. The command go tool pprof -http 127.0.0.1:8079 profile.out starts an interactive web UI with flame graphs, top tables, source views, and call trees. Any compatible Go profiling visualizer reads the same output format.

Is it safe to expose pprof in production?

The pprof endpoint is disabled by default and should be enabled only when you need it. Never expose the pprof port to the public internet; bind it to a private interface and gate access at the network level.

How do I share a profile with support?

Profile files are self-contained. Capture the relevant profile types (heap, CPU, goroutine), archive them, and share the archive with WunderGraph support or your performance team.

Does pprof add overhead?

No overhead when pprof is disabled. When enabled, profiles are captured on-demand only; endpoints do nothing until they are called.

Go pprof Profiling for Cosmo Router | Cosmo by WunderGraph

The problem

Symptom-level metrics do not fix performance

Dashboards tell you something is wrong. A profile tells you what is wrong.

Metrics show symptoms, not causes

CPU at 80% says you have a problem. It does not say which function. Without a profile, optimization becomes a search problem.

Memory leaks hide in production

Heap usage grows over days. Restart restores normal, for a while. Without a profile, the leak survives the restart and so does the on-call.

Deadlocks reveal themselves slowly

The router stops responding but does not crash. Logs are clean. The behavior is obvious in a goroutine dump and invisible without one.

Our solution

Native Go pprof, one environment variable away

Cosmo Router integrates Go's standard pprof package. Set PPROF_ADDR and the full set of profiling endpoints becomes available: heap, CPU, goroutine, threadcreate, and block.

From symptom to root cause

Set PPROF_ADDR=:6060 to start the pprof HTTP server inside the router.
Capture profiles via curl: /debug/pprof/heap for memory, /debug/pprof/profile for CPU, /debug/pprof/goroutine for goroutines.
/debug/pprof/threadcreate and /debug/pprof/block cover thread creation and blocking operations.
CPU profiles run for 30 seconds by default; the duration is configurable via the seconds query parameter.
Run go tool pprof on the captured profile for flame graphs, top tables, and call trees in your browser.
When the endpoint is unset, there is no overhead; pprof is off entirely.

No instrumentation library. No SDK. Standard Go.

Profiling

Before & After

Before Cosmo	With Cosmo
Metrics show memory growth but not which code path allocates	Heap profiles pinpoint hot allocation sites in the router
Production memory leaks discovered only after OOM	PPROF_ADDR enables targeted captures without redeploying subgraphs
Blocked goroutines surface slowly through logs alone	goroutine and block profiles show contention and stalls
Always-on profiling tax on every request	pprof is off until PPROF_ADDR is set: capture on demand only

Operational safety

Off by default

The pprof endpoint is disabled until PPROF_ADDR is set. Enable only when you need it. Bind to a private interface and never expose the pprof port to the public internet.

How profiling works in Cosmo Router

01

One env var. Off by default.

Enable

Set PPROF_ADDR to the address you want the pprof HTTP server on (for example :6060). The endpoint is off by default; you only pay for it when you turn it on.

02

curl one endpoint per profile type.

Capture

Pull a heap, CPU, goroutine, threadcreate, or block profile with curl. CPU profiles capture 30 seconds of activity by default.

03

Standard go tool pprof, any viewer.

Visualize

go tool pprof renders the profile as flame graphs, top tables, and source views. Any compatible Go profiling visualizer reads the same output.

04

Hot function, allocation site, blocker.

Diagnose

Find the hot function, the growing allocation site, or the blocked goroutine. Ship the fix with data, not guesswork.

Telemetry controls

Profile types and safety

Heap, CPU, goroutine, block, and thread profiles, on demand with no overhead when disabled.

CPU profile

Pull a 30-second CPU profile during peak load. Use the seconds query parameter to set a different duration.

Heap profile

Capture heap snapshots at intervals. go tool pprof diff mode shows what is growing between samples.

Goroutine dump

Use /debug/pprof/goroutine?debug=2 for stack traces of every goroutine. The view that finds deadlocks and lock contention.

Visualization

go tool pprof -http 127.0.0.1:8079 profile.out starts a local web UI with flame graphs, top tables, and source views.

Security note

The pprof endpoint is disabled by default. When you enable it, bind to a private interface (for example a Kubernetes internal service) and gate access at the network level. Never expose the pprof port to the public internet.

Profile the router when you need to

Set PPROF_ADDR, capture heap or CPU profiles with curl, and visualize with go tool pprof.

Start Free Read the Docs

Diagnose CPU, memory, and deadlocks with Go pprof