profiler

Documentation

Overview

Package profiler periodically collects and sends profiles to the Datadog API. Use Start to start the profiler. An API key needs to be specified by means of the WithAPIKey option.

Example

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

package main

import (
	"log"

	"gitlab.com/otavio3/go-tracer/profiler"
)

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

	// ...
}

Index

• Constants
• func Start(opts ...Option) error
• func Stop()
• type Option
  • func BlockProfileRate(rate int) Option
  • func CPUDuration(d time.Duration) Option
  • func MutexProfileFraction(rate int) Option
  • func WithAPIKey(key string) Option
  • func WithAgentAddr(hostport string) Option
  • func WithEnv(env string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithPeriod(d time.Duration) Option
  • func WithProfileTypes(types ...ProfileType) Option
  • func WithService(name string) Option
  • func WithSite(site string) Option
  • func WithStatsd(client StatsdClient) Option
  • func WithTags(tags ...string) Option
  • func WithUDS(socketPath string) Option
  • func WithURL(url string) Option
  • func WithVersion(version string) Option
• type ProfileType
  • func (t ProfileType) Filename() string
  • func (t ProfileType) String() string
  • func (t ProfileType) Tag() string
• type StatsdClient

Examples

• Package

Constants

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 used by the
	// block profiler. For more information or for changing this value, check
	// BlockProfileRate. The default rate is chosen to prevent high overhead
	// based on the research from:
	// https://github.com/felixge/go-profiler-notes/blob/main/block.md#benchmarks
	DefaultBlockRate = 10000

	// 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.Second * 15
)

Functions

func Start

func Start(opts ...Option) error

Start starts the profiler. 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 stops the profiler.

Types

type Option

type Option func(*config)

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

func BlockProfileRate

func BlockProfileRate(rate int) Option

BlockProfileRate turns on block profiles with the given rate. The profiler samples an average of one blocking event per rate nanoseconds spent blocked. For example, set rate to 1000000000 (aka int(time.Second.Nanoseconds())) to record one sample per second a goroutine is blocked. A rate of 1 catches every event. Setting an aggressive rate can hurt performance. For more information on this value, check runtime.SetBlockProfileRate.

func CPUDuration

func CPUDuration(d time.Duration) Option

CPUDuration specifies the length at which to collect CPU profiles.

func MutexProfileFraction

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 is deprecated and might be removed in future versions of this package. It allows to skip the agent and talk to the Datadog API directly using the provided API key.

func WithAgentAddr

func WithAgentAddr(hostport string) Option

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

func WithEnv

func WithEnv(env string) Option

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

func WithHTTPClient

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 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

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

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 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 synchronization primitives
	// (including timer channels). Block profile is not enabled by default.
	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

func (t ProfileType) Filename() string

Filename is the identifier used on upload.

func (ProfileType) String

func (t ProfileType) String() string

func (ProfileType) Tag

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 distribution 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.