blackfire

package module
v0.0.0-...-4a623d3 Latest Latest
Warning

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

Go to latest
Published: Dec 26, 2023 License: MIT Imports: 34 Imported by: 0

README

Blackfire Profiler for Go

Welcome to the Blackfire profiler SDK for Go!

To integrate Blackfire into your Go applications, read the documentation.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ProfilerErrorAlreadyProfiling = errors.New("A Blackfire profile is currently in progress. Please wait for it to finish.")

Functions

func Configure

func Configure(config *Configuration)

Configure explicitely configures the probe. This should be done before any other API calls.

Configuration is initialized in a set order, with later steps overriding earlier steps:

* Defaults * INI file * Explicit configuration in Go code * Environment variables

config will be ignored if nil.

func DashboardApiHandler

func DashboardApiHandler(w http.ResponseWriter, r *http.Request)

func DashboardHandler

func DashboardHandler(w http.ResponseWriter, r *http.Request)

DashboardHandler displays the current status of the profiler

func Disable

func Disable()

Disable stops profiling.

func DisableHandler

func DisableHandler(w http.ResponseWriter, r *http.Request)

DisableHandler stops profiling via HTTP

func DisableOnSignal

func DisableOnSignal(sig os.Signal) (err error)

DisableOnSignal sets up a trigger to disable profiling when the specified signal is received.

func EnableHandler

func EnableHandler(w http.ResponseWriter, r *http.Request)

EnableHandler starts profiling via HTTP

func EnableOnSignal

func EnableOnSignal(sig os.Signal, duration time.Duration) (err error)

EnableOnSignal sets up a trigger to enable profiling when the specified signal is received. The profiler will profile for the specified duration.

func End

func End()

End ends the current profile, then blocks until the result is uploaded to the agent.

func EndHandler

func EndHandler(w http.ResponseWriter, r *http.Request)

EndHandler stops profiling via HTTP and send the profile to the agent

func EndNoWait

func EndNoWait()

EndNoWait stops profiling, then uploads the result to the agent in a separate goroutine. You must ensure that the program does not exit before uploading is complete. If you can't make such a guarantee, use End() instead.

func EndOnSignal

func EndOnSignal(sig os.Signal) (err error)

EndOnSignal sets up a trigger to end the current profile and upload to Blackfire when the specified signal is received.

func GenerateSubProfileQuery

func GenerateSubProfileQuery() (string, error)

GenerateSubProfileQuery generates a Blackfire query to attach a subprofile with the current one as a parent

func IsProfiling

func IsProfiling() bool

IsProfiling checks if the profiler is running. Only one profiler may run at a time.

func NewAgentClient

func NewAgentClient(configuration *Configuration) (*agentClient, error)

func NewLogger

func NewLogger(path string, level int) zerolog.Logger

func NewLoggerFromEnvVars

func NewLoggerFromEnvVars() zerolog.Logger

func NewServeMux

func NewServeMux(prefix string) (mux *http.ServeMux, err error)

NewServeMux returns an http.ServerMux that allows to manage profiling from HTTP

func SetCurrentTitle

func SetCurrentTitle(title string)

SetCurrentTitle Sets the title to use for following profiles

Types

type BFTime

type BFTime struct {
	time.Time
}

func (*BFTime) UnmarshalJSON

func (m *BFTime) UnmarshalJSON(b []byte) (err error)

type Configuration

type Configuration struct {
	// The configuration path to the Blackfire CLI ini file
	// Defaults to ~/.blackfire.ini
	ConfigFile string

	// Time before dropping an unresponsive agent connection (default 250ms)
	AgentTimeout time.Duration

	// The socket to use when connecting to the Blackfire agent (default depends on OS)
	AgentSocket string

	// The Blackfire query string to be sent with any profiles. This is either
	// provided by the `blackfire run` command in an ENV variable, or acquired
	// via a signing request to Blackfire. You won't need to set this manually.
	BlackfireQuery string

	// Client ID to authenticate with the Blackfire API
	ClientID string

	// Client token to authenticate with the Blackfire API
	ClientToken string

	// Server ID for Blackfire-Auth header
	ServerID string

	// Server token for Blackfire-Auth header
	ServerToken string

	// The Blackfire API endpoint the profile data will be sent to (default https://blackfire.io)
	HTTPEndpoint *url.URL

	// A zerolog Logger (default stderr)
	Logger *zerolog.Logger

	// The maximum duration of a profile. A profile operation can never exceed
	// this duration (default 10 minutes).
	// This guards against runaway profile operations.
	MaxProfileDuration time.Duration

	// Default rate at which the CPU samples are taken. Values > 500 will likely
	// exceed the abilities of most environments.
	// See https://golang.org/src/runtime/pprof/pprof.go#L727
	DefaultCPUSampleRateHz int

	// If not empty, dump the original pprof profiles to this directory whenever
	// a profile ends.
	PProfDumpDir string
	// contains filtered or unexported fields
}

type Ender

type Ender interface {
	End()
	EndNoWait()
}

func Enable

func Enable() Ender

Enable() only profiles when trigerred from an external event (like using blackfire run).

func EnableNow

func EnableNow() Ender

EnableNow starts profiling. Profiling will continue until you call StopProfiling(). If you forget to stop profiling, it will automatically stop after the maximum allowed duration (DefaultMaxProfileDuration or whatever you set via SetMaxProfileDuration()).

func EnableNowFor

func EnableNowFor(duration time.Duration) Ender

EnableNowFor profiles the current process for the specified duration, then connects to the agent and uploads the generated profile.

type Envelope

type Envelope struct {
	Ct  int `json:"ct"`
	CPU int `json:"cpu"`
	MU  int `json:"mu"`
	PMU int `json:"pmu"`
}

type Profile

type Profile struct {
	UUID      string
	URL       string
	APIURL    string
	Title     string   `json:"label"`
	CreatedAt BFTime   `json:"created_at"`
	Status    Status   `json:"status"`
	Envelope  Envelope `json:"envelope"`
	Links     linksMap `json:"_links"`
	// contains filtered or unexported fields
}

type Status

type Status struct {
	Name          string `json:"name"`
	Code          int    `json:"code"`
	FailureReason string `json:"failure_reason"`
}

Directories

Path Synopsis
internal/profile
Package profile provides a representation of profile.proto and methods to encode/decode profiles in this format.
Package profile provides a representation of profile.proto and methods to encode/decode profiles in this format.

Jump to

Keyboard shortcuts

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