pprof

package
v14.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: BSD-3-Clause Imports: 6 Imported by: 0

README

Iris Pprof Middleware

Overview

This middleware mounts the standard library's net/http/pprof handlers on an Iris route, so the CPU, heap, goroutine and trace profiles of a running application are reachable over HTTP.

Features

  • CPU Profiling: Capture CPU usage over time.
  • Heap Profiling: Analyze memory allocations.
  • Goroutine Profiling: Inspect stack traces of all current goroutines.
  • Thread Creation Profiling: Track the creation of new OS threads.
  • Block Profiling: Identify blocking on synchronization primitives.
  • Mutex Profiling: Trace holders of contended mutexes.
  • Execution Tracing: Record execution trace of the program.
  • Command Line Invocation: View the command line invocation of the current program.

Installation

To use the Iris Pprof middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v14/middleware/pprof"

Usage

Basic Setup

To use the pprof middleware Router, you need to import the necessary packages and configure the middleware in your Iris application. Here is a basic example:

package main

import (
	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/pprof"
)

func main() {
	app := iris.New()

	// Register the pprof router.
	app.Router("/debug/pprof", pprof.New())

	app.Get("/", func(ctx iris.Context) {
		ctx.HTML("<h1> Please click <a href='/debug/pprof'>here</a> to access pprof</h1>")
	})

	app.Listen(":8080")
}

There is pprof.Handler which is an iris.Handler that you can use to register the pprof routes manually or execute inside an existing route handler.

Accessing Pprof

Once the middleware is registered, you can access the pprof tools by navigating to /debug/pprof in your web browser. The available profiles include:

  • /debug/pprof/allocs: A sampling of all past memory allocations.
  • /debug/pprof/block: Stack traces that led to blocking on synchronization primitives.
  • /debug/pprof/cmdline: The command line invocation of the current program.
  • /debug/pprof/goroutine: Stack traces of all current goroutines.
  • /debug/pprof/heap: A sampling of memory allocations of live objects.
  • /debug/pprof/mutex: Stack traces of holders of contended mutexes.
  • /debug/pprof/profile: CPU profile. You can specify the duration in the seconds GET parameter.
  • /debug/pprof/threadcreate: Stack traces that led to the creation of new OS threads.
  • /debug/pprof/trace: A trace of execution of the current program.
Protecting Pprof

You can protect the pprof routes with an authentication middleware to prevent unauthorized access.

import (
	"github.com/kataras/iris/v14/middleware/basicauth"
	"github.com/kataras/iris/v14/middleware/pprof"
)
auth := basicauth.Default(map[string]string{
	"admin": "admin",
	"gerasimos": "p@ss",
})
app.Router("/debug/pprof", auth, pprof.New())

References

Documentation

Overview

Package pprof provides native pprof support via middleware.

Its entry point is New(), which returns a *ProfilingRouter rather than a Handler: pprof is a set of sibling endpoints (heap, profile, trace, ...), so the value is registered as a party with app.Any("/debug/pprof/{action:path}", pprof.New()) and it dispatches on the sub-path itself.

Labels policy: Iris sets no pprof labels. If labels are ever added, they must carry route metadata only (route path, method), never request data — see the SECURITY WARNING on `New` for why.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Handler

func Handler(ctx *context.Context)

Handler is the pprof (profile, cmdline, symbol, goroutine, heap, threadcreate, debug/block) middleware handler. Note: Route MUST have the last named parameter wildcard named '{action:path}'. Example:

app.Handle("GET", "/debug/pprof /debug/pprof/{action:path}", pprof.Handler)

Types

type ProfilingRouter

type ProfilingRouter struct{}

ProfilingRouter is the pprof (profile, cmdline, symbol, goroutine, heap, threadcreate, debug/block) Router.

func New

func New() *ProfilingRouter

New returns a new pprof (profile, cmdline, symbol, goroutine, heap, threadcreate, debug/block) Router.

SECURITY WARNING: these endpoints MUST NOT be reachable without authentication.

GET /debug/pprof/goroutine?debug=2

dumps every goroutine's stack - source paths, function names and often argument values, which is where session identifiers and tokens live. The heap profile discloses the same through allocation sites. Anyone who can reach the route gets a detailed picture of the running process.

Goroutine dumps also include the goroutines' pprof labels, and for go1.27 modules labels print in panic traceback headers too - bypassing the recovery middleware's header redaction. Never put request data in pprof labels.

Usage - always behind a guard:

import "github.com/kataras/iris/v14/middleware/pprof"
import "github.com/kataras/iris/v14/middleware/basicauth"
[...]
app := iris.New()

auth := basicauth.Default(map[string]string{"admin": os.Getenv("PPROF_PASSWORD")})
app.Router("/debug/pprof", pprof.New()).Use(auth)

or restrict it by address with the ipaccess middleware, or bind the profiling endpoints to a separate, internal-only listener.

func (*ProfilingRouter) Routing

func (p *ProfilingRouter) Routing(r router.Router)

Routing registers the necessary routes for the pprof middleware. Implements the `router.Controller` interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL