instrument

package
v0.8.3 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2019 License: Apache-2.0 Imports: 19 Imported by: 268

Documentation

Overview

Package instrument implements functions to make instrumenting code, including metrics and logging, easier.

Index

Constants

View Source 
const (
	// InvariantViolatedMetricName is the name of the metric emitted upon
	// invocation of `EmitInvariantViolation`.
	InvariantViolatedMetricName = "invariant_violated"

	// InvariantViolatedLogFieldName is the name of the log field to be
	// used when generating errors/log statements pertaining to the violation
	// of an invariant.
	InvariantViolatedLogFieldName = "violation"

	// InvariantViolatedLogFieldValue is the value of the log field to be
	// used when generating errors/log statements pertaining to the violation
	// of an invariant.
	InvariantViolatedLogFieldValue = InvariantViolatedMetricName

	// ShouldPanicEnvironmentVariableName is the name of the environment variable
	// that must be set to "true" in order for the invariant violated functions
	// to panic after logging / emitting metrics. Should only be set in test
	// environments.
	ShouldPanicEnvironmentVariableName = "PANIC_ON_INVARIANT_VIOLATED"
)

Variables

View Source 
var (
	// Revision is the VCS revision associated with this build. Overridden using ldflags
	// at compile time. Example:
	// $ go build -ldflags "-X github.com/m3db/m3/src/x/instrument.Revision=abcdef" ...
	// Adapted from: https://www.atatus.com/blog/golang-auto-build-versioning/
	Revision = "unknown"

	// Branch is the VCS branch associated with this build.
	Branch = "unknown"

	// Version is the version associated with this build.
	Version = "unknown"

	// BuildDate is the date this build was created.
	BuildDate = "unknown"

	// BuildTimeUnix is the seconds since epoch representing the date this build was created.
	BuildTimeUnix = "0"

	// LogBuildInfoAtStartup controls whether we log build information at startup. If its
	// set to a non-empty string, we log the build information at process startup.
	LogBuildInfoAtStartup string
)

Functions

func EmitAndLogInvariantViolation 

func EmitAndLogInvariantViolation(opts Options, f func(l log.Logger))

EmitAndLogInvariantViolation calls EmitInvariantViolation and then calls the provided function with a supplied logger that is pre-configured with an invariant violated field. Optionally panics if the ShouldPanicEnvironmentVariableName is set to "true".

func EmitInvariantViolation 

func EmitInvariantViolation(opts Options)

EmitInvariantViolation emits a metric to indicate a system invariant has been violated. Users of this method are expected to monitor/alert off this metric to ensure they're notified when such an event occurs. Further, they should log further information to aid diagnostics of the system invariant violated at the callsite of the violation. Optionally panics if the ShouldPanicEnvironmentVariableName is set to "true".

func InvariantErrorf 

func InvariantErrorf(format string, a ...interface{}) error

InvariantErrorf constructs a new error, prefixed with a string indicating that an invariant violation occurred. Optionally panics if the ShouldPanicEnvironmentVariableName is set to "true".

func LogBuildInfo 

func LogBuildInfo()

LogBuildInfo logs the build information to the provided logger.

func MustCreateSampledTimer 

func MustCreateSampledTimer(base tally.Timer, rate float64) tally.Timer

MustCreateSampledTimer creates a new sampled timer, and panics if an error is encountered.

func NewSampledTimer 

func NewSampledTimer(base tally.Timer, rate float64) (tally.Timer, error)

NewSampledTimer creates a new sampled timer.

Types

type BatchMethodMetrics 

type BatchMethodMetrics struct {
	RetryableErrors    tally.Counter
	NonRetryableErrors tally.Counter
	Errors             tally.Counter
	Success            tally.Counter
	Latency            tally.Timer
}

BatchMethodMetrics is a bundle of common metrics for methods with batch semantics.

func NewBatchMethodMetrics 

func NewBatchMethodMetrics(
	scope tally.Scope,
	methodName string,
	samplingRate float64,
) BatchMethodMetrics

NewBatchMethodMetrics creates new batch method metrics.

func (*BatchMethodMetrics) ReportLatency 

func (m *BatchMethodMetrics) ReportLatency(d time.Duration)

ReportLatency reports latency.

func (*BatchMethodMetrics) ReportNonRetryableErrors 

func (m *BatchMethodMetrics) ReportNonRetryableErrors(n int)

ReportNonRetryableErrors reports non-retryable errors.

func (*BatchMethodMetrics) ReportRetryableErrors 

func (m *BatchMethodMetrics) ReportRetryableErrors(n int)

ReportRetryableErrors reports retryable errors.

func (*BatchMethodMetrics) ReportSuccess 

func (m *BatchMethodMetrics) ReportSuccess(n int)

ReportSuccess reports successess.

type ExtendedMetricsType 

type ExtendedMetricsType int

ExtendedMetricsType is a type of extended metrics to report. 

const (
	// NoExtendedMetrics describes no extended metrics.
	NoExtendedMetrics ExtendedMetricsType = iota

	// SimpleExtendedMetrics describes just a simple level of extended metrics:
	// - number of active goroutines
	// - number of configured gomaxprocs
	SimpleExtendedMetrics

	// ModerateExtendedMetrics describes a moderately verbose level of extended metrics:
	// - number of active goroutines
	// - number of configured gomaxprocs
	// - number of file descriptors
	ModerateExtendedMetrics

	// DetailedExtendedMetrics describes a detailed level of extended metrics:
	// - number of active goroutines
	// - number of configured gomaxprocs
	// - number of file descriptors
	// - memory allocated running count
	// - memory used by heap
	// - memory used by heap that is idle
	// - memory used by heap that is in use
	// - memory used by stack
	// - number of garbage collections
	// - GC pause times
	DetailedExtendedMetrics

	// DefaultExtendedMetricsType is the default extended metrics level.
	DefaultExtendedMetricsType = SimpleExtendedMetrics
)

func (ExtendedMetricsType) String 

func (t ExtendedMetricsType) String() string

func (*ExtendedMetricsType) UnmarshalYAML 

func (t *ExtendedMetricsType) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML unmarshals an ExtendedMetricsType into a valid type from string.

type MethodMetrics 

type MethodMetrics struct {
	Errors         tally.Counter
	Success        tally.Counter
	ErrorsLatency  tally.Timer
	SuccessLatency tally.Timer
}

MethodMetrics is a bundle of common metrics with a uniform naming scheme.

func NewMethodMetrics 

func NewMethodMetrics(scope tally.Scope, methodName string, samplingRate float64) MethodMetrics

NewMethodMetrics returns a new Method metrics for the given method name.

func (*MethodMetrics) ReportError 

func (m *MethodMetrics) ReportError(d time.Duration)

ReportError reports an error.

func (*MethodMetrics) ReportSuccess 

func (m *MethodMetrics) ReportSuccess(d time.Duration)

ReportSuccess reports a success.

func (*MethodMetrics) ReportSuccessOrError 

func (m *MethodMetrics) ReportSuccessOrError(e error, d time.Duration)

ReportSuccessOrError increments Error/Success counter dependending on the error.

type MetricSanitizationType 

type MetricSanitizationType int

MetricSanitizationType is a type of sanitizer to use for metrics. 

const (
	// NoMetricSanitization performs no metric sanitization.
	NoMetricSanitization MetricSanitizationType = iota

	// M3MetricSanitization performs M3 metric sanitization.
	M3MetricSanitization

	// PrometheusMetricSanitization performs Prometheus metric sanitization.
	PrometheusMetricSanitization
)

func (*MetricSanitizationType) NewOptions 

func (t *MetricSanitizationType) NewOptions() *tally.SanitizeOptions

NewOptions returns a new set of sanitization options for the sanitization type.

func (MetricSanitizationType) String 

func (t MetricSanitizationType) String() string

func (*MetricSanitizationType) UnmarshalYAML 

func (t *MetricSanitizationType) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML unmarshals a MetricSanitizationType into a valid type from string.

type MetricsConfiguration 

type MetricsConfiguration struct {
	// Root scope configuration.
	RootScope *ScopeConfiguration `yaml:"scope"`

	// M3 reporter configuration.
	M3Reporter *m3.Configuration `yaml:"m3"`

	// Prometheus reporter configuration.
	PrometheusReporter *prometheus.Configuration `yaml:"prometheus"`

	// Metrics sampling rate.
	SamplingRate float64 `yaml:"samplingRate" validate:"nonzero,min=0.0,max=1.0"`

	// Extended metrics type.
	ExtendedMetrics *ExtendedMetricsType `yaml:"extended"`

	// Metric sanitization type.
	Sanitization *MetricSanitizationType `yaml:"sanitization"`
}

MetricsConfiguration configures options for emitting metrics.

func (*MetricsConfiguration) NewRootScope 

func (mc *MetricsConfiguration) NewRootScope() (tally.Scope, io.Closer, error)

NewRootScope creates a new tally.Scope based on a tally.CachedStatsReporter based on the the the config.

func (*MetricsConfiguration) NewRootScopeReporter 

func (mc *MetricsConfiguration) NewRootScopeReporter(
	r tally.CachedStatsReporter,
) (tally.Scope, io.Closer)

NewRootScopeReporter creates a new tally.Scope based on a given tally.CachedStatsReporter and given root scope config. In most cases NewRootScope should be used, but for cases such as hooking into the reporter to manually flush it.

func (*MetricsConfiguration) ReportInterval 

func (mc *MetricsConfiguration) ReportInterval() time.Duration

ReportInterval returns the metrics reporting interval.

func (*MetricsConfiguration) SampleRate 

func (mc *MetricsConfiguration) SampleRate() float64

SampleRate returns the metrics sampling rate.

type Options 

type Options interface {
	// SetLogger sets the logger.
	SetLogger(value log.Logger) Options

	// Logger returns the logger.
	Logger() log.Logger

	// SetZapLogger sets the zap logger
	SetZapLogger(value *zap.Logger) Options

	// ZapLogger returns the zap logger
	ZapLogger() *zap.Logger

	// SetMetricsScope sets the metrics scope.
	SetMetricsScope(value tally.Scope) Options

	// MetricsScope returns the metrics scope.
	MetricsScope() tally.Scope

	// Tracer returns the tracer.
	Tracer() opentracing.Tracer

	// SetTracer sets the tracer.
	SetTracer(tracer opentracing.Tracer) Options

	// SetMetricsSamplingRate sets the metrics sampling rate.
	SetMetricsSamplingRate(value float64) Options

	// SetMetricsSamplingRate returns the metrics sampling rate.
	MetricsSamplingRate() float64

	// ReportInterval sets the time between reporting metrics within the system.
	SetReportInterval(time.Duration) Options

	// GetReportInterval returns the time between reporting metrics within the system.
	ReportInterval() time.Duration
}

Options represents the options for instrumentation.

func NewOptions 

func NewOptions() Options

NewOptions creates new instrument options.

type Reporter 

type Reporter interface {
	// Start starts the reporter.
	Start() error
	// Stop stops the reporter.
	Stop() error
}

Reporter reports metrics about a component.

func NewBuildReporter 

func NewBuildReporter(
	opts Options,
) Reporter

NewBuildReporter returns a new build version reporter.

func NewExtendedMetricsReporter 

func NewExtendedMetricsReporter(
	scope tally.Scope,
	reportInterval time.Duration,
	metricsType ExtendedMetricsType,
) Reporter

NewExtendedMetricsReporter creates a new extended metrics reporter that reports runtime and process metrics.

func NewProcessReporter 

func NewProcessReporter(
	scope tally.Scope,
	reportInterval time.Duration,
) Reporter

NewProcessReporter returns a new reporter that reports process metrics, currently just the process file descriptor count.

func StartReportingExtendedMetrics 

func StartReportingExtendedMetrics(
	scope tally.Scope,
	reportInterval time.Duration,
	metricsType ExtendedMetricsType,
) (Reporter, error)

StartReportingExtendedMetrics creates a extend metrics reporter and starts the reporter returning it so it may be stopped if successfully started.

type ScopeConfiguration 

type ScopeConfiguration struct {
	// Prefix of metrics in this scope.
	Prefix string `yaml:"prefix"`

	// Metrics reporting interval.
	ReportingInterval time.Duration `yaml:"reportingInterval"`

	// Common tags shared by metrics reported.
	CommonTags map[string]string `yaml:"tags"`
}

ScopeConfiguration configures a metric scope.

Source Files

View all Source files

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.