runtime Package Deep — Practice Tasks¶

package main

import (
    "fmt"
    "runtime"
    "time"
)

// Senior decision: keep the struct small and operator-readable. Forty
// MemStats fields are a debugging buffet; a snapshot is for at-a-glance
// triage. Anything beyond seven fields and the eye glazes over.
type Snapshot struct {
    Goroutines      int
    CPUs            int
    GOMAXPROCS      int
    HeapAllocMB     float64
    HeapInUseMB     float64
    NumGC           uint32
    GCPauseTotalMs  float64
}

func Take() Snapshot {
    var m runtime.MemStats
    // Senior decision: ReadMemStats stops the world. We pay it ONCE per
    // snapshot and never inline it into a hot loop. If you need
    // continuous metrics, runtime/metrics is the right tool (Task 11).
    runtime.ReadMemStats(&m)
    return Snapshot{
        Goroutines:     runtime.NumGoroutine(),
        CPUs:           runtime.NumCPU(),
        GOMAXPROCS:     runtime.GOMAXPROCS(0), // read-only when arg <= 0
        HeapAllocMB:    float64(m.HeapAlloc) / (1024 * 1024),
        HeapInUseMB:    float64(m.HeapInuse) / (1024 * 1024),
        NumGC:          m.NumGC,
        GCPauseTotalMs: float64(m.PauseTotalNs) / 1e6,
    }
}

func (s Snapshot) String() string {
    return fmt.Sprintf(
        "goroutines=%d cpus=%d gomaxprocs=%d heap_alloc_mb=%.2f heap_inuse_mb=%.2f num_gc=%d gc_pause_total_ms=%.2f",
        s.Goroutines, s.CPUs, s.GOMAXPROCS,
        s.HeapAllocMB, s.HeapInUseMB,
        s.NumGC, s.GCPauseTotalMs,
    )
}

func main() {
    block := make(chan struct{})
    for i := 0; i < 1000; i++ {
        go func() { <-block }()
    }
    // Give the scheduler a beat to actually start the goroutines.
    time.Sleep(10 * time.Millisecond)

    for i := 0; i < 3; i++ {
        fmt.Println(Take())
        time.Sleep(200 * time.Millisecond)
    }
    close(block)
}

package main

import (
    "fmt"
    "runtime"
)

// Senior decision: name the parameter `skip` everywhere it appears.
// Reading "Caller(1)" with no context is harder than reading "Caller(skip)"
// where skip is a named local — the latter survives the inevitable
// refactor that adds a wrapper layer and shifts every depth by one.
func describe(skip int) string {
    pc, file, line, ok := runtime.Caller(skip)
    if !ok {
        return fmt.Sprintf("skip=%d: unknown", skip)
    }
    fn := runtime.FuncForPC(pc)
    name := "unknown"
    if fn != nil {
        name = fn.Name()
    }
    return fmt.Sprintf("skip=%d %s:%d %s", skip, file, line, name)
}

func WhoCalledMe() {
    // Senior decision: add 1 to every skip because describe() is ITSELF
    // a frame we want to skip. If you forget this offset, every stack
    // dump in the codebase points one frame too deep.
    fmt.Println(describe(1)) // the call site of WhoCalledMe
    fmt.Println(describe(2)) // parent
    fmt.Println(describe(3)) // grandparent
}

func WhoCalledMeAll(maxDepth int) {
    for i := 1; i <= maxDepth; i++ {
        pc, file, line, ok := runtime.Caller(i)
        if !ok {
            return
        }
        name := "unknown"
        if fn := runtime.FuncForPC(pc); fn != nil {
            name = fn.Name()
        }
        fmt.Printf("  [%d] %s:%d %s\n", i, file, line, name)
    }
}

func c() {
    fmt.Println("--- WhoCalledMe ---")
    WhoCalledMe()
    fmt.Println("--- WhoCalledMeAll ---")
    WhoCalledMeAll(32)
}

func b() { c() }
func a() { b() }

func main() { a() }

package main

import (
    "fmt"
    "runtime"
    "strings"
    "time"
)

// Senior decision: production-grade Stack helper grows the buffer until
// the dump fits. Calling Stack with a too-small buffer silently truncates
// — the worst possible failure mode in a debugging tool, because you'll
// never know your stack trace was cut off mid-frame.
func DumpSelf() []byte {
    buf := make([]byte, 64*1024)
    for {
        n := runtime.Stack(buf, false)
        if n < len(buf) {
            return buf[:n]
        }
        buf = make([]byte, 2*len(buf))
        if len(buf) > 64*1024*1024 {
            // Senior decision: cap at 64 MiB. A single goroutine with a
            // larger stack is almost certainly a runaway recursion; better
            // to truncate than to OOM the debugger.
            return buf[:n]
        }
    }
}

func DumpAll() []byte {
    buf := make([]byte, 64*1024)
    for {
        n := runtime.Stack(buf, true)
        if n < len(buf) {
            return buf[:n]
        }
        buf = make([]byte, 2*len(buf))
        if len(buf) > 256*1024*1024 {
            // For thousand-goroutine processes, the all-goroutine dump
            // can exceed 100 MiB. Cap is necessary.
            return buf[:n]
        }
    }
}

func main() {
    block := make(chan struct{})
    for i := 0; i < 10; i++ {
        go func() { <-block }()
    }
    time.Sleep(50 * time.Millisecond) // let them park

    self := DumpSelf()
    all := DumpAll()

    fmt.Printf("self dump: %d bytes, %d goroutine headers\n",
        len(self), strings.Count(string(self), "goroutine "))
    fmt.Printf("all dump:  %d bytes, %d goroutine headers\n",
        len(all), strings.Count(string(all), "goroutine "))

    close(block)
}

package main

import (
    "fmt"
    "runtime"
)

func main() {
    var m runtime.MemStats

    for cycle := 1; cycle <= 3; cycle++ {
        runtime.ReadMemStats(&m)
        before := m.NumGC
        beforeHeapMB := float64(m.HeapAlloc) / (1024 * 1024)

        // Allocate ~50 MiB, then drop the reference so it's collectable.
        garbage := make([][]byte, 0, 50)
        for i := 0; i < 50; i++ {
            garbage = append(garbage, make([]byte, 1024*1024))
        }
        runtime.ReadMemStats(&m)
        peakHeapMB := float64(m.HeapAlloc) / (1024 * 1024)
        garbage = nil //nolint: ineffassign // intentional: drop reference

        // Senior decision: runtime.GC() in production code is almost
        // always a mistake. It overrides the GC pacer's careful trade-off
        // between CPU and memory. The only legitimate uses are
        // (a) deterministic test setup, (b) immediately before taking a
        // memory profile, (c) right before exec() in a long-lived shell
        // that wants to release RSS. Outside those, leave the pacer alone.
        runtime.GC()

        runtime.ReadMemStats(&m)
        after := m.NumGC
        afterHeapMB := float64(m.HeapAlloc) / (1024 * 1024)

        fmt.Printf(
            "cycle=%d NumGC: %d -> %d (delta=%d) heap: %.1f -> %.1f -> %.1f MiB\n",
            cycle, before, after, after-before,
            beforeHeapMB, peakHeapMB, afterHeapMB,
        )
    }
}

package main

import (
    "crypto/sha256"
    "log"
    "math/rand"
    "net/http"
    _ "net/http/pprof" // registers handlers on http.DefaultServeMux
)

// Senior decision: in production the side-effect import is wrong. It
// blanket-registers debug routes on whatever mux happens to be Default,
// which is often the same mux the app listens on. Best practice is a
// SEPARATE mux on a SEPARATE listener bound to localhost or a private
// interface. See Task 12 for the production-grade version.
func main() {
    go busyWorker()
    log.Println("pprof at http://localhost:6060/debug/pprof/")
    log.Fatal(http.ListenAndServe("localhost:6060", nil))
}

func busyWorker() {
    buf := make([]byte, 4096)
    h := sha256.New()
    for {
        rand.Read(buf)
        h.Reset()
        h.Write(buf)
        _ = h.Sum(nil)
    }
}

// Capture a profile from your shell:
//
//   go tool pprof -seconds=10 http://localhost:6060/debug/pprof/profile
//
// Inside the pprof interactive shell:
//
//   (pprof) top
//   Showing nodes accounting for 9.50s, 96.94% of 9.80s total
//         flat  flat%   sum%        cum   cum%
//        4.20s 42.86% 42.86%      4.20s 42.86%  crypto/sha256.block
//        2.10s 21.43% 64.29%      2.10s 21.43%  runtime.memmove
//        ...
//
//   (pprof) list busyWorker
//      ...
//      11    .          .   func busyWorker() {
//      12    .          .       buf := make([]byte, 4096)
//      13    .          .       h := sha256.New()
//      14    .          .       for {
//      15    .       50ms          rand.Read(buf)
//      16    .       30ms          h.Reset()
//      17    .      4.20s          h.Write(buf)
//      18    .       70ms          _ = h.Sum(nil)
//      19    .          .       }
//      20    .          .   }
//
// Or open a flamegraph:
//
//   go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile?seconds=10

package main

import (
    "fmt"
    "os"
    "runtime/pprof"
    "time"
)

func leakedWorker(block <-chan struct{}) {
    <-block // never closed -> leak
}

func main() {
    block := make(chan struct{})
    for i := 0; i < 100; i++ {
        go leakedWorker(block)
    }
    time.Sleep(100 * time.Millisecond) // let them park

    // Senior decision: write BOTH formats. The binary one for tooling,
    // the text one for a human eye when you have only ssh and cat.
    binF, err := os.Create("goroutine.pb.gz")
    must(err)
    defer binF.Close()
    if err := pprof.Lookup("goroutine").WriteTo(binF, 0); err != nil {
        panic(err)
    }

    txtF, err := os.Create("goroutine.txt")
    must(err)
    defer txtF.Close()
    // Debug level 1: deduplicated text. Reads like:
    //   100 @ 0x... 0x... 0x...
    //   #   0x...  main.leakedWorker+0x... /path/main.go:7
    // That "100 @" is the headline of every leak hunt — 100 goroutines
    // share one stack. If you saw "1 @ 100 times" instead, you'd have
    // 100 different leaks, which is a different problem.
    if err := pprof.Lookup("goroutine").WriteTo(txtF, 1); err != nil {
        panic(err)
    }

    fmt.Println("wrote goroutine.pb.gz and goroutine.txt")
    fmt.Println("inspect: go tool pprof goroutine.pb.gz  (then: top, traces)")
    fmt.Println("inspect: less goroutine.txt")

    close(block)
}

func must(err error) {
    if err != nil {
        panic(err)
    }
}

package main

import (
    "fmt"
    "math/rand"
    "os"
    "runtime/trace"
    "sync"
    "time"
)

func main() {
    f, err := os.Create("trace.out")
    if err != nil {
        panic(err)
    }
    defer f.Close()

    // Senior decision: start the trace BEFORE the workload begins so we
    // capture the worker pool spinup too. The first millisecond of any
    // trace is the most informative — that's where laziness in init,
    // unexpected goroutine spawns, and GC warmup show up.
    if err := trace.Start(f); err != nil {
        panic(err)
    }
    defer trace.Stop()

    jobs := make(chan int, 100)
    var wg sync.WaitGroup
    for w := 0; w < 4; w++ {
        wg.Add(1)
        go func(workerID int) {
            defer wg.Done()
            for j := range jobs {
                doJob(workerID, j)
            }
        }(w)
    }
    for j := 0; j < 100; j++ {
        jobs <- j
    }
    close(jobs)
    wg.Wait()

    fmt.Println("wrote trace.out")
    fmt.Println("open with: go tool trace trace.out")
}

func doJob(workerID, jobID int) {
    // Senior decision: the trace UI shows you what each goroutine was
    // doing. If your jobs are all "Sleep" you'll see Sleep blocks; if
    // they're all "channel recv" you'll see those. The richer your
    // workload, the more informative the trace.
    time.Sleep(time.Duration(rand.Intn(5)) * time.Millisecond)
    _ = workerID
    _ = jobID
}

package main

import (
    "fmt"
    "runtime"
    "time"
)

type Item struct {
    Name string
    Next *Item
}

func makeItem(name string) *Item {
    it := &Item{Name: name}
    runtime.SetFinalizer(it, func(i *Item) {
        fmt.Println("collected:", i.Name)
    })
    return it
}

func main() {
    // Round 1: ten independent items.
    items := make([]*Item, 0, 10)
    for i := 0; i < 10; i++ {
        items = append(items, makeItem(fmt.Sprintf("item-%d", i)))
    }
    items = nil // drop refs

    // Senior decision: TWO runtime.GC() calls. Finalizers run AFTER an
    // object is found unreachable, and the runtime "resurrects" the
    // object briefly so the finalizer can touch it. Only the SECOND GC
    // can actually free it (assuming the finalizer didn't stash a
    // reference somewhere). Forgetting the second GC is the #1 source
    // of "my finalizer ran but memory wasn't freed".
    runtime.GC()
    runtime.GC()
    time.Sleep(100 * time.Millisecond) // let finalizer goroutine drain

    fmt.Println("--- chain ---")
    // Round 2: A -> B -> C.
    a := makeItem("A")
    b := makeItem("B")
    c := makeItem("C")
    a.Next = b
    b.Next = c
    a = nil
    _ = b
    _ = c

    // Senior decision: with the chain we'd LIKE to see C-then-B-then-A
    // (deepest first). The actual order depends on the GC implementation
    // — it may collect them all in one cycle. The Go spec gives no
    // ordering guarantee. If you NEED ordering, don't use finalizers;
    // use explicit Close() methods or runtime.AddCleanup (Task 20).
    b = nil
    c = nil
    runtime.GC()
    runtime.GC()
    time.Sleep(100 * time.Millisecond)
}

package main

import (
    "fmt"
    "runtime"
    "time"
)

type Resource struct {
    ID     int
    Handle uintptr // pretend this is a cgo handle
}

func newResource(id int) *Resource {
    r := &Resource{ID: id, Handle: uintptr(id) * 0x1000}
    runtime.SetFinalizer(r, func(rr *Resource) {
        fmt.Printf("freed:  ID=%d Handle=0x%x\n", rr.ID, rr.Handle)
    })
    return r
}

func useHandle(handle uintptr, iter int) {
    fmt.Printf("in use: handle=0x%x iter=%d\n", handle, iter)
}

func brokenDemo() {
    fmt.Println("--- BROKEN (no KeepAlive) ---")
    r := newResource(1)
    // Senior decision: this is the trap. After we extract Handle, the
    // *Resource itself has no more uses in the function. The compiler
    // marks r as dead; the GC collects it; the finalizer fires; the
    // Handle we're holding is now a dangling reference. In cgo this
    // would be a use-after-free.
    handle := r.Handle
    for i := 0; i < 50; i++ {
        useHandle(handle, i)
        // Force GC pressure.
        _ = make([]byte, 1<<20)
        runtime.GC()
        time.Sleep(time.Millisecond)
    }
    fmt.Println("brokenDemo done")
}

func fixedDemo() {
    fmt.Println("--- FIXED (with KeepAlive) ---")
    r := newResource(2)
    handle := r.Handle
    for i := 0; i < 50; i++ {
        useHandle(handle, i)
        _ = make([]byte, 1<<20)
        runtime.GC()
        time.Sleep(time.Millisecond)
    }
    // Senior decision: KeepAlive is a compile-time signal, not a
    // runtime operation. It compiles to nothing — but it stops the
    // compiler from marking r as dead before this line. Placement
    // matters: KeepAlive must be AFTER the last use of the derived
    // value (handle) you want to protect.
    runtime.KeepAlive(r)
    fmt.Println("fixedDemo done")
}

func main() {
    brokenDemo()
    time.Sleep(100 * time.Millisecond)
    fixedDemo()
    time.Sleep(100 * time.Millisecond)
}

file := os.NewFile(fd, "x")
syscall.Write(int(file.Fd()), buf) // file may be collected here
runtime.KeepAlive(file)            // <- required

package main

import (
    "context"
    "crypto/sha256"
    "log"
    "math/rand"
    "net/http"
    _ "net/http/pprof"
    "runtime/pprof"
    "sync"
)

func busyWork(iters int) {
    buf := make([]byte, 4096)
    h := sha256.New()
    for i := 0; i < iters; i++ {
        rand.Read(buf)
        h.Reset()
        h.Write(buf)
        _ = h.Sum(nil)
    }
}

func main() {
    go func() {
        log.Println("pprof at http://localhost:6060/debug/pprof/")
        log.Fatal(http.ListenAndServe("localhost:6060", nil))
    }()

    var wg sync.WaitGroup
    // Senior decision: the LABELS are the schema for slicing your CPU
    // profile after the fact. Pick them ONCE up front and use them
    // everywhere — tenant, endpoint, request_class. Inconsistent label
    // keys ("user" here, "userid" there) destroy the analysis.
    tenants := []string{"acme", "globex", "acme", "acme"} // acme triple-loaded
    for i, t := range tenants {
        wg.Add(1)
        go func(tenant string, idx int) {
            defer wg.Done()
            ctx := context.Background()
            pprof.Do(ctx, pprof.Labels(
                "tenant", tenant,
                "worker_id", fmtInt(idx),
            ), func(ctx context.Context) {
                // Senior decision: the work happens INSIDE pprof.Do.
                // Anything before/after the Do is unattributed in the
                // profile. Wrap the whole hot path, not just the
                // innermost call.
                busyWork(1_000_000)
            })
        }(t, i)
    }
    wg.Wait()
    log.Println("done")
}

func fmtInt(i int) string {
    const digits = "0123456789"
    if i == 0 {
        return "0"
    }
    buf := [16]byte{}
    pos := len(buf)
    for i > 0 {
        pos--
        buf[pos] = digits[i%10]
        i /= 10
    }
    return string(buf[pos:])
}

// Capture and inspect:
//
//   go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10
//   (pprof) tagfocus=tenant=acme
//   (pprof) top
//          flat  flat%        cum   cum%
//         5.20s 75.36%      5.20s 75.36%  crypto/sha256.block
//
//   (pprof) tagfocus=tenant=globex
//   (pprof) top
//          flat  flat%        cum   cum%
//         1.80s 25.71%      1.80s 25.71%  crypto/sha256.block
//
//   acme's three workers took ~75%, globex's one worker took ~25%.
//   That's the per-tenant CPU split, derived from the profile alone.

package main

import (
    "fmt"
    "log"
    "net/http"
    "runtime/metrics"
    "strings"
)

// Senior decision: declare the metrics list ONCE as a package-level
// variable. The Sample slice is allocated per-request inside the handler
// (cheap), but the schema (names + Prometheus mapping) is static — no
// reason to rebuild it every request.
var promMetrics = []struct {
    runtimeName string // runtime/metrics name
    promName    string // Prometheus metric name
    help        string
    kind        string // "gauge" | "counter" | "summary" (derived)
}{
    {"/memory/classes/heap/objects:bytes", "go_memstats_heap_alloc_bytes",
        "Bytes allocated and currently in use.", "gauge"},
    {"/sched/goroutines:goroutines", "go_goroutines",
        "Number of goroutines that currently exist.", "gauge"},
    {"/cpu/classes/gc/total:cpu-seconds", "go_gc_cpu_seconds_total",
        "Cumulative CPU time spent in GC.", "counter"},
    {"/gc/pauses:seconds", "go_gc_pause_seconds",
        "Distribution of GC pause durations.", "summary"},
    {"/sched/latencies:seconds", "go_sched_latencies_seconds",
        "Distribution of times goroutines spent on the scheduler queue.", "summary"},
}

// Senior decision: runtime/metrics is the right choice over MemStats
// for continuous monitoring because (a) most reads are lock-free atomic
// loads, no stop-the-world; (b) metrics are versioned and stable across
// Go releases; (c) histograms preserve the distribution (MemStats only
// gives totals). The migration cost is one-time; the operational win is
// permanent.
func metricsHandler(w http.ResponseWriter, r *http.Request) {
    samples := make([]metrics.Sample, len(promMetrics))
    for i, m := range promMetrics {
        samples[i].Name = m.runtimeName
    }
    metrics.Read(samples)

    var sb strings.Builder
    for i, m := range promMetrics {
        s := samples[i]
        if s.Value.Kind() == metrics.KindBad {
            // Metric doesn't exist on this Go version — skip with a
            // comment rather than erroring. The exporter must NEVER fail
            // closed on metric absence; that crashes alerting.
            fmt.Fprintf(&sb, "# %s not available on this Go version\n", m.runtimeName)
            continue
        }
        fmt.Fprintf(&sb, "# HELP %s %s\n", m.promName, m.help)
        fmt.Fprintf(&sb, "# TYPE %s %s\n", m.promName, m.kind)
        switch s.Value.Kind() {
        case metrics.KindUint64:
            fmt.Fprintf(&sb, "%s %d\n", m.promName, s.Value.Uint64())
        case metrics.KindFloat64:
            fmt.Fprintf(&sb, "%s %g\n", m.promName, s.Value.Float64())
        case metrics.KindFloat64Histogram:
            h := s.Value.Float64Histogram()
            p50 := percentile(h, 0.50)
            p99 := percentile(h, 0.99)
            fmt.Fprintf(&sb, "%s{quantile=\"0.50\"} %g\n", m.promName, p50)
            fmt.Fprintf(&sb, "%s{quantile=\"0.99\"} %g\n", m.promName, p99)
        }
    }
    w.Header().Set("Content-Type", "text/plain; version=0.0.4")
    w.Write([]byte(sb.String()))
}

// percentile interpolates the cumulative histogram for a given quantile.
// runtime/metrics histograms use OPEN buckets — h.Counts[i] is the count
// in the range (h.Buckets[i], h.Buckets[i+1]].
func percentile(h *metrics.Float64Histogram, q float64) float64 {
    var total uint64
    for _, c := range h.Counts {
        total += c
    }
    if total == 0 {
        return 0
    }
    target := uint64(float64(total) * q)
    var sum uint64
    for i, c := range h.Counts {
        sum += c
        if sum >= target {
            // Senior decision: return the upper edge of the bucket.
            // Linear interpolation across the bucket would be slightly
            // more accurate but require remembering the previous edge —
            // for a tail percentile (p99) the bucket is wide and the
            // interpolation isn't worth the code.
            return h.Buckets[i+1]
        }
    }
    return h.Buckets[len(h.Buckets)-1]
}

func main() {
    http.HandleFunc("/metrics", metricsHandler)
    log.Println("metrics at http://localhost:8080/metrics")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

package main

import (
    "crypto/subtle"
    "log"
    "net"
    "net/http"
    "net/http/pprof"
    "os"
    "strings"
)

// Senior decision: defence in depth. Either auth OR allowlist alone is
// flawed: auth on a public port still lets attackers probe with brute
// force; allowlist alone is bypassed by anyone inside the trusted network.
// Both together raise the bar enough that a misconfigured ingress
// firewall doesn't immediately leak a CPU profile.
type pprofGate struct {
    user, pass string
    nets       []*net.IPNet
    inner      http.Handler
}

func (g *pprofGate) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // Check IP first — cheaper than basic auth, denies before we even
    // touch the password.
    host, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        http.Error(w, "bad RemoteAddr", http.StatusBadRequest)
        return
    }
    ip := net.ParseIP(host)
    if ip == nil {
        http.Error(w, "bad RemoteAddr", http.StatusBadRequest)
        return
    }
    allowed := false
    for _, n := range g.nets {
        if n.Contains(ip) {
            allowed = true
            break
        }
    }
    if !allowed {
        http.Error(w, "forbidden", http.StatusForbidden)
        return
    }

    // Basic auth.
    user, pass, ok := r.BasicAuth()
    if !ok {
        w.Header().Set("WWW-Authenticate", `Basic realm="pprof"`)
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }
    // Senior decision: constant-time compare on BOTH credentials. Using
    // == on the password leaks length and partial-prefix information via
    // timing. ConstantTimeCompare is the standard mitigation.
    userOK := subtle.ConstantTimeCompare([]byte(user), []byte(g.user)) == 1
    passOK := subtle.ConstantTimeCompare([]byte(pass), []byte(g.pass)) == 1
    if !userOK || !passOK {
        w.Header().Set("WWW-Authenticate", `Basic realm="pprof"`)
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }

    g.inner.ServeHTTP(w, r)
}

func newPprofMux() *http.ServeMux {
    // Senior decision: build the pprof mux ourselves rather than using
    // http.DefaultServeMux. Registering on Default contaminates the
    // process-wide mux; explicit registration on a private mux keeps
    // pprof scoped to the debug listener only.
    mux := http.NewServeMux()
    mux.HandleFunc("/debug/pprof/", pprof.Index)
    mux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
    mux.HandleFunc("/debug/pprof/profile", pprof.Profile)
    mux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
    mux.HandleFunc("/debug/pprof/trace", pprof.Trace)
    return mux
}

func parseAllowlist(cidrs []string) []*net.IPNet {
    out := make([]*net.IPNet, 0, len(cidrs))
    for _, c := range cidrs {
        _, n, err := net.ParseCIDR(c)
        if err != nil {
            log.Fatalf("bad CIDR %q: %v", c, err)
        }
        out = append(out, n)
    }
    return out
}

func main() {
    user := os.Getenv("PPROF_USER")
    pass := os.Getenv("PPROF_PASS")
    if user == "" || pass == "" {
        log.Fatal("PPROF_USER and PPROF_PASS must be set")
    }
    raw := os.Getenv("PPROF_ALLOW") // e.g. "10.0.0.0/8,127.0.0.1/32"
    if raw == "" {
        raw = "127.0.0.1/32,::1/128"
    }
    nets := parseAllowlist(strings.Split(raw, ","))

    gate := &pprofGate{
        user:  user,
        pass:  pass,
        nets:  nets,
        inner: newPprofMux(),
    }

    // Senior decision: bind the debug listener to localhost by default
    // and document that exposing it requires explicit ingress config.
    // The auth + allowlist are the second and third layers; "don't
    // expose at all" is the first.
    log.Println("pprof at https://127.0.0.1:6060/debug/pprof/")
    log.Fatal(http.ListenAndServe("127.0.0.1:6060", gate))
}

// Test:
//   curl -i http://127.0.0.1:6060/debug/pprof/      # 401
//   curl -i -u user:pass http://127.0.0.1:6060/debug/pprof/  # 200
//   (from a non-allowlisted IP) curl ... # 403

package main

import (
    "fmt"
    "math"
    "runtime"
    "runtime/debug"
    "runtime/metrics"
    "time"
)

func readGCCycles() uint64 {
    s := []metrics.Sample{{Name: "/gc/cycles/total:gc-cycles"}}
    metrics.Read(s)
    return s[0].Value.Uint64()
}

func readHeapInUse() float64 {
    s := []metrics.Sample{{Name: "/memory/classes/heap/objects:bytes"}}
    metrics.Read(s)
    return float64(s[0].Value.Uint64()) / (1024 * 1024)
}

func allocChurn(durationMs int) (peakMiB float64) {
    var keep [][]byte
    deadline := time.Now().Add(time.Duration(durationMs) * time.Millisecond)
    for time.Now().Before(deadline) {
        // Allocate 8 MiB chunks; keep up to 50 of them rotating.
        keep = append(keep, make([]byte, 8*1024*1024))
        if len(keep) > 50 {
            keep = keep[1:]
        }
        if mb := readHeapInUse(); mb > peakMiB {
            peakMiB = mb
        }
        time.Sleep(2 * time.Millisecond)
    }
    runtime.KeepAlive(keep)
    return
}

func main() {
    // Senior decision: read the current limit BEFORE setting one. In
    // containerised production the limit is typically set via the
    // GOMEMLIMIT env var; logging it on startup makes "what limit am I
    // running under" answerable from logs.
    current := debug.SetMemoryLimit(-1)
    fmt.Printf("startup memory limit: %d bytes (%.0f MiB)\n",
        current, float64(current)/(1024*1024))

    fmt.Println("--- Phase A: limit = 200 MiB ---")
    debug.SetMemoryLimit(200 * 1024 * 1024)
    gcBefore := readGCCycles()
    peakA := allocChurn(2000)
    gcAfter := readGCCycles()
    fmt.Printf("Phase A: %d GC cycles, peak heap %.1f MiB\n",
        gcAfter-gcBefore, peakA)

    fmt.Println("--- Phase B: limit = unlimited ---")
    debug.SetMemoryLimit(math.MaxInt64)
    gcBefore = readGCCycles()
    peakB := allocChurn(2000)
    gcAfter = readGCCycles()
    fmt.Printf("Phase B: %d GC cycles, peak heap %.1f MiB\n",
        gcAfter-gcBefore, peakB)

    // Senior decision: typical output —
    //   Phase A: 47 GC cycles, peak heap 215.4 MiB
    //   Phase B:  9 GC cycles, peak heap 401.8 MiB
    //
    // Phase A's pacer is FIGHTING to stay near 200 MiB by GCing 5x more
    // often. CPU goes up; memory stays bounded. Phase B's pacer is in
    // "GOGC=100" steady state — fewer cycles, but the heap floats up
    // to wherever the working set wants. The memory limit is the right
    // dial when you'd rather pay CPU than be OOM-killed.
}

//go:build linux

package main

import (
    "fmt"
    "runtime"
    "sync"
    "syscall"
)

// Senior decision: prefer syscall.Gettid over cgo for THIS demo because
// it's portable across Go versions and doesn't require a C toolchain.
// In production, the cgo equivalent applies to anything libc — OpenGL,
// X11, gettext, glibc locale, signal masks, OpenSSL thread-local error
// queues. The pattern is identical.
func currentTID() int {
    return syscall.Gettid()
}

func observeWithoutLock(iters int) map[int]int {
    counts := map[int]int{}
    var mu sync.Mutex
    var wg sync.WaitGroup
    wg.Add(1)
    go func() {
        defer wg.Done()
        for i := 0; i < iters; i++ {
            tid := currentTID()
            mu.Lock()
            counts[tid]++
            mu.Unlock()
            // Give the runtime an opportunity to migrate us.
            runtime.Gosched()
        }
    }()
    wg.Wait()
    return counts
}

func observeWithLock(iters int) map[int]int {
    counts := map[int]int{}
    var mu sync.Mutex
    var wg sync.WaitGroup
    wg.Add(1)
    go func() {
        // Senior decision: Lock BEFORE the first thread-local call,
        // Unlock AFTER the LAST. If you Lock too late, the first call
        // is on a random thread; if you forget to Unlock, the M is
        // pinned to this goroutine forever — which is what you want for
        // signal-handler init goroutines but a leak for ad-hoc workers.
        runtime.LockOSThread()
        defer runtime.UnlockOSThread()
        defer wg.Done()
        for i := 0; i < iters; i++ {
            tid := currentTID()
            mu.Lock()
            counts[tid]++
            mu.Unlock()
            runtime.Gosched()
        }
    }()
    wg.Wait()
    return counts
}

func main() {
    // Force a multi-P scheduler so goroutines can actually migrate.
    runtime.GOMAXPROCS(4)

    a := observeWithoutLock(10_000)
    fmt.Printf("without lock: %d distinct TIDs\n", len(a))
    for tid, n := range a {
        fmt.Printf("  tid=%d count=%d\n", tid, n)
    }

    b := observeWithLock(10_000)
    fmt.Printf("with lock: %d distinct TIDs\n", len(b))
    for tid, n := range b {
        fmt.Printf("  tid=%d count=%d\n", tid, n)
    }
}

// Typical output:
//   without lock: 3 distinct TIDs
//     tid=12345 count=4123
//     tid=12346 count=3210
//     tid=12347 count=2667
//   with lock: 1 distinct TIDs
//     tid=12348 count=10000
//
// The "3 distinct TIDs" is the bug for any cgo function that depends on
// thread-local state. errno read after a libc call may come from a
// thread that didn't make the call. OpenGL contexts will be "current"
// on a thread that's no longer running the goroutine. Signal masks set
// will affect the wrong thread.