profiler

package
v1.67.0 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2024 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 38 Imported by: 119

Documentation

Overview

Package profiler periodically collects and sends profiles to the Datadog API. Use Start to start the profiler.

Example

This example illustrates how to run (and later stop) the Datadog Profiler. 

package main

import (
	"log"

	"gopkg.in/DataDog/dd-trace-go.v1/profiler"
)

func main() {
	err := profiler.Start(
		profiler.WithService("users-db"),
		profiler.WithEnv("staging"),
		profiler.WithTags("version:1.2.0"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer profiler.Stop()

	// ...
}

Output:

Index

Examples

Constants

View Source 
const (
	// DefaultMutexFraction specifies the mutex profile fraction to be used with the mutex profiler.
	// For more information or for changing this value, check MutexProfileFraction
	DefaultMutexFraction = 10

	// DefaultBlockRate specifies the default block profiling rate (in ns) used
	// by the block profiler. For more information or for changing this value,
	// check BlockProfileRate(). The default value of 100ms is somewhat
	// arbitrary. There is no provably safe value that will guarantee low
	// overhead for this profile type for all workloads. We don't recommend
	// enabling it under normal circumstances. See the link below for more
	// information: https://github.com/DataDog/go-profiler-notes/pull/15/files
	DefaultBlockRate = 100000000

	// DefaultPeriod specifies the default period at which profiles will be collected.
	DefaultPeriod = time.Minute

	// DefaultDuration specifies the default length of the CPU profile snapshot.
	DefaultDuration = time.Minute

	// DefaultUploadTimeout specifies the default timeout for uploading profiles.
	// It can be overwritten using the DD_PROFILING_UPLOAD_TIMEOUT env variable
	// or the WithUploadTimeout option.
	DefaultUploadTimeout = 10 * time.Second
)

Variables

This section is empty.

Functions

func Start 

func Start(opts ...Option) error

Start starts the profiler. If the profiler is already running, it will be stopped and restarted with the given options.

It may return an error if an API key is not provided by means of the WithAPIKey option, or if a hostname is not found.

func Stop 

func Stop()

Stop cancels any ongoing profiling or upload operations and returns after everything has been stopped.

Types

type Option 

type Option func(*config)

An Option is used to configure the profiler's behaviour.

func BlockProfileRate added in v1.29.0 

func BlockProfileRate(rate int) Option

BlockProfileRate turns on block profiles with the given rate. We do not recommend enabling this profile type, see DefaultBlockRate for more information. The rate is given in nanoseconds and a block event with a given duration has a min(duration/rate, 1) chance of getting sampled.

func CPUDuration 

func CPUDuration(d time.Duration) Option

CPUDuration specifies the length at which to collect CPU profiles.

func CPUProfileRate added in v1.38.0 

func CPUProfileRate(hz int) Option

CPUProfileRate sets the sampling frequency for CPU profiling. A sample will be taken once for every (1 / hz) seconds of on-CPU time. If not given, profiling will use the default rate from the runtime/pprof.StartCPUProfile function, which is 100 as of Go 1.0.

Setting a different profile rate will result in a spurious warning every time CPU profling is started, like "cannot set cpu profile rate until previous profile has finished". This is a known issue, but the rate will still be set correctly and CPU profiling will work.

func MutexProfileFraction added in v1.29.0 

func MutexProfileFraction(rate int) Option

MutexProfileFraction turns on mutex profiles with rate indicating the fraction of mutex contention events reported in the mutex profile. On average, 1/rate events are reported. Setting an aggressive rate can hurt performance. For more information on this value, check runtime.SetMutexProfileFraction.

func WithAPIKey 

func WithAPIKey(key string) Option

WithAPIKey sets the Datadog API Key and takes precedence over the DD_API_KEY env variable. Historically this option was used to enable agentless uploading, but as of dd-trace-go v1.30.0 the behavior has changed to always default to agent based uploading which doesn't require an API key. So if you currently don't have an agent running on the default localhost:8126 hostport you need to set it up, or use WithAgentAddr to specify the hostport location of the agent. See WithAgentlessUpload for more information.

func WithAgentAddr added in v1.25.0 

func WithAgentAddr(hostport string) Option

WithAgentAddr specifies the address to use when reaching the Datadog Agent.

func WithAgentlessUpload added in v1.30.0 

func WithAgentlessUpload() Option

WithAgentlessUpload is currently for internal usage only and not officially supported. You should not enable it unless somebody at Datadog instructed you to do so. It allows to skip the agent and talk to the Datadog API directly using the provided API key.

func WithCustomProfilerLabelKeys added in v1.60.0 

func WithCustomProfilerLabelKeys(keys ...string) Option

WithCustomProfilerLabelKeys specifies profiler label keys which should be available as attributes for filtering frames for CPU and goroutine profile flame graphs in the Datadog profiler UI.

The profiler is limited to 10 label keys to show in the UI. Any label keys after the first 10 will be ignored (but labels with ignored keys will still be available in the raw profile data).

func WithDeltaProfiles added in v1.35.0 

func WithDeltaProfiles(enabled bool) Option

WithDeltaProfiles specifies if delta profiles are enabled. The default value is true. This option takes precedence over the DD_PROFILING_DELTA environment variable that can be set to "true" or "false" as well. See https://dtdg.co/go-delta-profile-docs for more information.

func WithEnv 

func WithEnv(env string) Option

WithEnv specifies the environment to which these profiles should be registered.

func WithHTTPClient added in v1.29.0 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient specifies the HTTP client to use when submitting profiles to Site. In general, using this method is only necessary if you have need to customize the transport layer, for instance when using a unix domain socket.

func WithHostname added in v1.42.0 

func WithHostname(hostname string) Option

WithHostname sets the hostname which will be added to uploaded profiles through the "host:<hostname>" tag. If no hostname is given, the hostname will default to the output of os.Hostname()

func WithLogStartup added in v1.36.0 

func WithLogStartup(enabled bool) Option

WithLogStartup toggles logging the configuration of the profiler to standard error when profiling is started. The configuration is logged in a JSON format. This option is enabled by default.

func WithPeriod 

func WithPeriod(d time.Duration) Option

WithPeriod specifies the interval at which to collect profiles.

func WithProfileTypes 

func WithProfileTypes(types ...ProfileType) Option

WithProfileTypes specifies the profile types to be collected by the profiler.

func WithService 

func WithService(name string) Option

WithService specifies the service name to attach to a profile.

func WithSite added in v1.25.0 

func WithSite(site string) Option

WithSite specifies the datadog site (datadoghq.com, datadoghq.eu, etc.) which profiles will be sent to.

func WithStatsd 

func WithStatsd(client StatsdClient) Option

WithStatsd specifies an optional statsd client to use for metrics. By default, no metrics are sent.

func WithTags 

func WithTags(tags ...string) Option

WithTags specifies a set of tags to be attached to the profiler. These may help filter the profiling view based on various information.

func WithUDS added in v1.29.0 

func WithUDS(socketPath string) Option

WithUDS configures the HTTP client to dial the Datadog Agent via the specified Unix Domain Socket path.

func WithURL 

func WithURL(url string) Option

WithURL specifies the HTTP URL for the Datadog Profiling API.

func WithUploadTimeout added in v1.30.0 

func WithUploadTimeout(d time.Duration) Option

WithUploadTimeout specifies the timeout to use for uploading profiles. The default timeout is specified by DefaultUploadTimeout or the DD_PROFILING_UPLOAD_TIMEOUT env variable. Using a negative value or 0 will cause an error when starting the profiler.

func WithVersion 

func WithVersion(version string) Option

WithVersion specifies the service version tag to attach to profiles

type ProfileType 

type ProfileType int

ProfileType represents a type of profile that the profiler is able to run. 

const (
	// HeapProfile reports memory allocation samples; used to monitor current
	// and historical memory usage, and to check for memory leaks.
	HeapProfile ProfileType = iota
	// CPUProfile determines where a program spends its time while actively consuming
	// CPU cycles (as opposed to while sleeping or waiting for I/O).
	CPUProfile
	// BlockProfile shows where goroutines block waiting on mutex and channel
	// operations. The block profile is not enabled by default and may cause
	// noticeable CPU overhead. We recommend against enabling it, see
	// DefaultBlockRate for more information.
	BlockProfile
	// MutexProfile reports the lock contentions. When you think your CPU is not fully utilized due
	// to a mutex contention, use this profile. Mutex profile is not enabled by default.
	MutexProfile
	// GoroutineProfile reports stack traces of all current goroutines
	GoroutineProfile

	// MetricsProfile reports top-line metrics associated with user-specified profiles
	MetricsProfile
)

func (ProfileType) Filename added in v1.29.0 

func (t ProfileType) Filename() string

Filename is the identifier used on upload.

func (ProfileType) String 

func (t ProfileType) String() string

String returns the name of the profile.

func (ProfileType) Tag added in v1.29.0 

func (t ProfileType) Tag() string

Tag used on profile metadata

type StatsdClient 

type StatsdClient interface {
	// Count counts how many times an event happened, at the given rate using the given tags.
	Count(event string, times int64, tags []string, rate float64) error
	// Timing creates a histogram metric of the values registered as the duration of a certain event.
	Timing(event string, duration time.Duration, tags []string, rate float64) error
}

StatsdClient implementations can count and time certain event occurrences that happen in the profiler.

Source Files

View all Source files

Directories

Path Synopsis
fastdelta
Package fastdelta tries to match up samples between two pprof profiles and take their difference.
 Package fastdelta tries to match up samples between two pprof profiles and take their difference.
immutable
Package immutable provides read-only types
 Package immutable provides read-only types
pproflite
Package pproflite implements zero-allocation pprof encoding and decoding.
 Package pproflite implements zero-allocation pprof encoding and decoding.
pprofutils
Package pprofutils is a fork of github.com/felixge/pprofutils, see README.
 Package pprofutils is a fork of github.com/felixge/pprofutils, see README.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.