README
¶
profile
Simple profiling for Go.
- Easy management of Go's built-in profiling and tracing
- Based on the widely-used
pkg/profile: mostly-compatible API - Supports generating multiple profiles at once
- Configurable with idiomatic flags:
-cpuprofile,-memprofile, ... just likego test - Configurable by environment variable: key-value interface like
GODEBUG
Install
go get github.com/mmcloughlin/profile
Usage
Enabling profiling in your application is as simple as one line at the top of your main function.
import "github.com/mmcloughlin/profile"
func main() {
defer profile.Start().Stop()
// ...
}
This will write a CPU profile to the current directory. Generate multiple
profiles by passing options to the Start function.
defer profile.Start(profile.CPUProfile, profile.MemProfile).Stop()
Profiles can also be configured by the user via flags or environment variable, as demonstrated in the examples below.
Flags
The following example shows how to configure profile via flags with multiple
available profile types.
func main() {
log.SetPrefix("example: ")
log.SetFlags(0)
// Setup profiler.
p := profile.New(
profile.CPUProfile,
profile.MemProfile,
profile.TraceProfile,
)
// Configure flags.
n := flag.Int("n", 1000000, "sum the integers 1 to `n`")
p.SetFlags(flag.CommandLine)
flag.Parse()
// Start profiler.
defer p.Start().Stop()
// Sum 1 to n.
sum := 0
for i := 1; i <= *n; i++ {
sum += i
}
log.Printf("sum: %d", sum)
}
See the registered flags:
Usage of example:
-cpuprofile file
write a cpu profile to file
-memprofile file
write an allocation profile to file
-memprofilerate rate
set memory allocation profiling rate (see runtime.MemProfileRate)
-n n
sum the integers 1 to n (default 1000000)
-trace file
write an execution trace to file
Profile the application with the following flags:
example -n 1000000000 -cpuprofile cpu.out -memprofile mem.out
We'll see additional logging in the output, as well as the profiles cpu.out
and mem.out written on exit.
example: cpu profile: started
example: mem profile: started
example: sum: 500000000500000000
example: cpu profile: stopped
example: mem profile: stopped
Environment
For a user-facing tool you may not want to expose profiling options via flags.
The profile package also offers configuration by environment variable, similar
to the GODEBUG option offered by the Go runtime.
// Setup profiler.
defer profile.Start(
profile.AllProfiles,
profile.ConfigEnvVar("PROFILE"),
).Stop()
Now you can enable profiling with an environment variable, as follows:
PROFILE=cpuprofile=cpu.out,memprofile=mem.out example -n 1000000000
The output will be just the same as for the previous flags example. Set the
environment variable to help to get help on available options:
PROFILE=help example
In this case you'll see:
blockprofile=file
write a goroutine blocking profile to file
blockprofilerate=rate
set blocking profile rate (see runtime.SetBlockProfileRate)
cpuprofile=file
write a cpu profile to file
goroutineprofile=file
write a running goroutine profile to file
memprofile=file
write an allocation profile to file
memprofilerate=rate
set memory allocation profiling rate (see runtime.MemProfileRate)
mutexprofile=string
write a mutex contention profile to the named file after execution
mutexprofilefraction=int
if >= 0, calls runtime.SetMutexProfileFraction()
threadcreateprofile=file
write a thread creation profile to file
trace=file
write an execution trace to file
Thanks
Thank you to Dave Cheney and
contributors for the
excellent pkg/profile package, which
provided the inspiration and basis for this work.
License
profile is available under the BSD 3-Clause License. The license
retains the copyright notice from
pkg/profile.
Documentation
¶
Overview ¶
Package profile provides simple profiling for Go applications.
Index ¶
- func AllProfiles(p *Profile)
- func BlockProfile(p *Profile)
- func CPUProfile(p *Profile)
- func ConfigEnvVar(key string) func(*Profile)
- func GoroutineProfile(p *Profile)
- func MemProfile(p *Profile)
- func MutexProfile(p *Profile)
- func NoShutdownHook(p *Profile)
- func Quiet(p *Profile)
- func ThreadcreationProfile(p *Profile)
- func TraceProfile(p *Profile)
- func WithLogger(l *log.Logger) func(p *Profile)
- type Profile
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AllProfiles ¶
func AllProfiles(p *Profile)
AllProfiles enables all profiling types. Running all profiles at once is generally not a good idea, so it's recommended that this option is combined with some configuration mechanism, via flags or otherwise.
func BlockProfile ¶
func BlockProfile(p *Profile)
BlockProfile enables block (contention) profiling.
func ConfigEnvVar ¶
ConfigEnvVar specifies an environment variable to configure profiles from.
func GoroutineProfile ¶
func GoroutineProfile(p *Profile)
GoroutineProfile enables goroutine profiling.
func NoShutdownHook ¶
func NoShutdownHook(p *Profile)
NoShutdownHook controls whether the profiling session should shutdown on interrupt. Programs with more sophisticated signal handling should use this option to disable the default shutdown handler, and ensure the profile Stop() method is called during shutdown.
func ThreadcreationProfile ¶
func ThreadcreationProfile(p *Profile)
ThreadcreationProfile enables thread creation profiling.
func WithLogger ¶
WithLogger configures informational messages to be logged to the given logger. Defaults to the standard library global logger.
Types ¶
type Profile ¶
type Profile struct {
// contains filtered or unexported fields
}
Profile represents a profiling session.
Source Files
Directories