prof

README

Advanced Runtime Profiling Toolkit for Go (Gin + pprof)

prof is a production‑grade profiling module for Go services. It exposes runtime profiling features through both:

• A standalone internal HTTP pprof server
• Gin HTTP routes for dynamic start/stop profiling and on‑demand snapshots

It provides controlled CPU profiling, heap dumps, goroutine snapshots, block/mutex profiling, download endpoints, and automated or manual cleanup of profiling files.

Features

• Standard pprof handlers mounted under /debug/pprof/*
• Start/stop CPU profiling on demand (/cpu/start, /cpu/stop)
• Heap profile dump (/heap)
• Goroutine dump (/goroutines)
• Block profile control (/block/start, /block/stop)
• Mutex contention profile control (/mutex/start, /mutex/stop)
• File retention & cleanup
  • Auto-clean daily old profiling files
  • Optional cleanup after download
  • Manual cleanup endpoint (POST /cleanup) with configurable retention
• Custom output directory for generated profiles
• Structured logging support via slog-compatible interface

---

Installation

go get github.com/alex-cos/prof

---

Quick Start

1. Create the profiling server

logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
pp := prof.New(
  prof.WithHost("127.0.0.1"),
  prof.WithPort(6060),
  prof.WithSlog(logger),
  prof.WithOutputDir("./profiles"),
)
pp.StartNonBlocking() // runs the internal pprof server
defer pp.Stop()

2. Attach profiling routes to your Gin server

r := gin.Default()
pp.AttachRoutes(r)
r.Run(":8080")

---

Usage Examples

Start CPU profiling

POST /cpu/start?seconds=30

Stop CPU profiling manually

POST /cpu/stop

Download last completed CPU profile

GET /download

Capture a heap profile

POST /heap

Capture goroutine dump

GET /goroutines

Enable block profiling

POST /block/start?rate=1

Disable block profiling

POST /block/stop

Manual cleanup (delete profiles older than 24h)

POST /cleanup

Or specify custom retention:

POST /cleanup?retention_hours=2

---

File Retention

prof supports two retention mechanisms:

1. Delete file after download

Automatically removes CPU profiles after they are downloaded.

2. Daily cleanup

Call once during initialization:

pp.RunDailyCleanup(24 * time.Hour)

---

File Layout

Profile files are created using timestamped names:

cpu_YYYYMMDD_HHMMSS.pprof
heap_YYYYMMDD_HHMMSS.pprof
goroutine_YYYYMMDD_HHMMSS.txt

Documentation

Index

• Constants
• type Logger
• type Option
  • func WithHost(host string) Option
  • func WithOutputDir(outputDir string) Option
  • func WithPort(port int) Option
  • func WithSlog(slog Logger) Option
• type Server
  • func New(opts ...Option) *Server
  • func (s *Server) AttachRoutes(r gin.IRoutes)
  • func (s *Server) RunDailyCleanup(retention time.Duration)
  • func (s *Server) StartBlockProfiling(rate int) error
  • func (s *Server) StartBlocking() error
  • func (s *Server) StartCPUProfiling(seconds int) error
  • func (s *Server) StartMutexProfiling(fraction int) error
  • func (s *Server) StartNonBlocking() error
  • func (s *Server) Stop()
  • func (s *Server) StopBlockProfiling() error
  • func (s *Server) StopCPUProfiling() error
  • func (s *Server) StopMutexProfiling() error
  • func (s *Server) WriteGoroutines() (string, error)
  • func (s *Server) WriteHeap() (string, error)

Constants

const (
	DefaultPort              = 8060
	DefaultCPUSeconds        = 30
	DefaultReadHeaderTimeout = 10 * time.Second
	DefaultWriteTimeout      = time.Minute
	DefaultIdleTimeout       = time.Minute
	ShutdownTimeout          = 5 * time.Second
)

Types

type Logger

type Logger interface {
	Debug(msg string, args ...any)
	Enabled(ctx context.Context, level slog.Level) bool
	Error(msg string, args ...any)
	Handler() slog.Handler
	Info(msg string, args ...any)
	Log(ctx context.Context, level slog.Level, msg string, args ...any)
	LogAttrs(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr)
	Warn(msg string, args ...any)
	With(args ...any) *slog.Logger
	WithGroup(name string) *slog.Logger
}

type Option

type Option func(*Server)

func WithHost

func WithHost(host string) Option

func WithOutputDir

func WithOutputDir(outputDir string) Option

func WithPort

func WithPort(port int) Option

func WithSlog

func WithSlog(slog Logger) Option

type Server

type Server struct {
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) *Server

func (*Server) AttachRoutes

func (s *Server) AttachRoutes(r gin.IRoutes)

AttachRoutes attaches a set of endpoints to control profiling and to download snapshots.

func (*Server) RunDailyCleanup

func (s *Server) RunDailyCleanup(retention time.Duration)

RunDailyCleanup launches a goroutine that removes files older than retention duration.

func (*Server) StartBlockProfiling

func (s *Server) StartBlockProfiling(rate int) error

StartBlockProfiling enables block profiling with rate (events/sample). rate==0 disables.

func (*Server) StartBlocking

func (s *Server) StartBlocking() error

func (*Server) StartCPUProfiling

func (s *Server) StartCPUProfiling(seconds int) error

StartCPUProfiling starts a CPU profile for `seconds` seconds. If seconds<=0 uses 30s.

func (*Server) StartMutexProfiling

func (s *Server) StartMutexProfiling(fraction int) error

StartMutexProfiling sets mutex profile fraction. fraction==0 disables.

func (*Server) StartNonBlocking

func (s *Server) StartNonBlocking() error

func (*Server) Stop

func (s *Server) Stop()

func (*Server) StopBlockProfiling

func (s *Server) StopBlockProfiling() error

StopBlockProfiling disables block profiling.

func (*Server) StopCPUProfiling

func (s *Server) StopCPUProfiling() error

StopCPUProfiling stops CPU profiling. It is safe to call multiple times.

func (*Server) StopMutexProfiling

func (s *Server) StopMutexProfiling() error

StopMutexProfiling disables mutex profiling.

func (*Server) WriteGoroutines

func (s *Server) WriteGoroutines() (string, error)

WriteGoroutines writes the goroutine profile (stack traces) to a file, returns path.

func (*Server) WriteHeap

func (s *Server) WriteHeap() (string, error)

WriteHeap writes a heap profile to a file and returns the path.