pyroscope

README

Pyroscope Golang Client

This is a golang integration for Pyroscope — open source continuous profiling platform.

For more information, please visit our golang integration documentation.

Profiling Go applications

To start profiling a Go application, you need to include our Go module in your app:

go get github.com/grafana/pyroscope-go

Then add the following code to your application:

package main

import "github.com/grafana/pyroscope-go"

func main() {
  pyroscope.Start(pyroscope.Config{
    ApplicationName: "simple.golang.app",

    // replace this with the address of pyroscope server
    ServerAddress:   "http://pyroscope-server:4040",

    // you can disable logging by setting this to nil
    Logger:          pyroscope.StandardLogger,

    // Optional HTTP Basic authentication (Grafana Cloud)
    BasicAuthUser:     "<User>",
    BasicAuthPassword: "<Password>",
    // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
    // TenantID:          "<TenantID>",

    // by default all profilers are enabled,
    // but you can select the ones you want to use:
    ProfileTypes: []pyroscope.ProfileType{
      pyroscope.ProfileCPU,
      pyroscope.ProfileAllocObjects,
      pyroscope.ProfileAllocSpace,
      pyroscope.ProfileInuseObjects,
      pyroscope.ProfileInuseSpace,
    },
  })

  // your code goes here
}

Tags

It is possible to add tags (labels) to the profiling data. These tags can be used to filter the data in the UI.

// these two ways of adding tags are equivalent:
pyroscope.TagWrapper(context.Background(), pyroscope.Labels("controller", "slow_controller"), func(c context.Context) {
  slowCode()
})

pprof.Do(context.Background(), pprof.Labels("controller", "slow_controller"), func(c context.Context) {
  slowCode()
})

Pull Mode

Go integration supports pull mode, which means that you can profile applications without adding any extra code. For that to work you will need to make sure you have profiling routes (/debug/pprof) enabled in your http server. Generally, that means that you need to add net/http/pprof package:

import _ "net/http/pprof"

Examples

Check out the examples directory in our repository to learn more. 🔥

Maintainers

This package is maintained by @grafana/pyroscope-go. Mention this team on issues or PRs for feedback.

Documentation

Index

• Variables
• func TagWrapper(ctx context.Context, labels LabelSet, cb func(context.Context))
• type Config
• type LabelSet
• type Logger
• type ProfileType
• type Profiler
  • func Start(cfg Config) (*Profiler, error)
  • func (p *Profiler) Flush(wait bool)
  • func (p *Profiler) Stop() error
• type Session
  • func NewSession(c SessionConfig) (*Session, error)
  • func (ps *Session) Start() error
  • func (ps *Session) Stop()
• type SessionConfig

Variables

var DefaultProfileTypes = []ProfileType{
	ProfileCPU,
	ProfileAllocObjects,
	ProfileAllocSpace,
	ProfileInuseObjects,
	ProfileInuseSpace,
}

var Labels = pprof.Labels //nolint:gochecknoglobals

var (
	StandardLogger = &standardLoggerImpl{} //nolint:gochecknoglobals
)

Functions

func TagWrapper

func TagWrapper(ctx context.Context, labels LabelSet, cb func(context.Context))

Types

type Config

type Config struct {
	ApplicationName   string // e.g backend.purchases
	Tags              map[string]string
	ServerAddress     string // e.g http://pyroscope.services.internal:4040
	BasicAuthUser     string // http basic auth user
	BasicAuthPassword string // http basic auth password
	TenantID          string // specify TenantId when using phlare multi-tenancy
	UploadRate        time.Duration
	Logger            Logger
	ProfileTypes      []ProfileType
	DisableGCRuns     bool // this will disable automatic runtime.GC runs between getting the heap profiles
	HTTPHeaders       map[string]string
	HTTPClient        remote.HTTPClient

	// Deprecated: the field will be removed in future releases.
	// Use BasicAuthUser and BasicAuthPassword instead.
	AuthToken string // specify this token when using pyroscope cloud
	// Deprecated: the field will be removed in future releases.
	// Use UploadRate instead.
	DisableAutomaticResets bool
	// Deprecated: the field will be removed in future releases.
	// DisableCumulativeMerge is ignored.
	DisableCumulativeMerge bool
	// Deprecated: the field will be removed in future releases.
	// SampleRate is set to 100 and is not configurable.
	SampleRate uint32
}

type LabelSet

type LabelSet = pprof.LabelSet

type Logger

type Logger interface {
	Infof(_ string, _ ...interface{})
	Debugf(_ string, _ ...interface{})
	Errorf(_ string, _ ...interface{})
}

Logger is an interface that library users can use It is based on logrus, but much smaller — That's because we don't want library users to have to implement all of the logrus's methods

type ProfileType

type ProfileType string

const (
	ProfileCPU           ProfileType = "cpu"
	ProfileInuseObjects  ProfileType = "inuse_objects"
	ProfileAllocObjects  ProfileType = "alloc_objects"
	ProfileInuseSpace    ProfileType = "inuse_space"
	ProfileAllocSpace    ProfileType = "alloc_space"
	ProfileGoroutines    ProfileType = "goroutines"
	ProfileMutexCount    ProfileType = "mutex_count"
	ProfileMutexDuration ProfileType = "mutex_duration"
	ProfileBlockCount    ProfileType = "block_count"
	ProfileBlockDuration ProfileType = "block_duration"
	DefaultSampleRate                = 100
)

type Profiler

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

func Start

func Start(cfg Config) (*Profiler, error)

Start starts continuously profiling go code

func (*Profiler) Flush

func (p *Profiler) Flush(wait bool)

Flush resets current profiling session. if wait is true, also waits for all profiles to be uploaded synchronously

func (*Profiler) Stop

func (p *Profiler) Stop() error

Stop stops continuous profiling session and uploads the remaining profiling data

type Session

type Session struct {

	// Deprecated: the field will be removed in future releases.
	DisableAutomaticResets bool
	// contains filtered or unexported fields
}

func NewSession

func NewSession(c SessionConfig) (*Session, error)

func (*Session) Start

func (ps *Session) Start() error

func (*Session) Stop

func (ps *Session) Stop()

type SessionConfig

type SessionConfig struct {
	Upstream       upstream.Upstream
	Logger         Logger
	AppName        string
	Tags           map[string]string
	ProfilingTypes []ProfileType
	DisableGCRuns  bool
	UploadRate     time.Duration

	// Deprecated: the field will be removed in future releases.
	// Use UploadRate instead.
	DisableAutomaticResets bool
	// Deprecated: the field will be removed in future releases.
	// DisableCumulativeMerge is ignored.
	DisableCumulativeMerge bool
	// Deprecated: the field will be removed in future releases.
	// SampleRate is set to 100 and is not configurable.
	SampleRate uint32
}