metric

Documentation

Overview

Package metric provides primitives for collecting metrics.

Index

• Variables
• func Disable() error
• func EmitMetricUpdate()
• func Initialize() error
• func MustRegisterCustomUint64Metric(name string, cumulative, sync bool, description string, ...)
• func RegisterCustomUint64Metric(name string, cumulative, sync bool, units pb.MetricMetadata_Units, ...) error
• func StartStage(stage InitStage) func()
• type Field
• type InitStage
• type Uint64Metric
  • func MustCreateNewUint64Metric(name string, sync bool, description string, fields ...Field) *Uint64Metric
  • func MustCreateNewUint64NanosecondsMetric(name string, sync bool, description string) *Uint64Metric
  • func NewUint64Metric(name string, sync bool, units pb.MetricMetadata_Units, description string, ...) (*Uint64Metric, error)
  • func (m *Uint64Metric) Increment(fieldValues ...string)
  • func (m *Uint64Metric) IncrementBy(v uint64, fieldValues ...string)
  • func (m *Uint64Metric) Value(fieldValues ...string) uint64

Variables

var (
	// ErrNameInUse indicates that another metric is already defined for
	// the given name.
	ErrNameInUse = errors.New("metric name already in use")

	// ErrInitializationDone indicates that the caller tried to create a
	// new metric after initialization.
	ErrInitializationDone = errors.New("metric cannot be created after initialization is complete")

	// WeirdnessMetric is a metric with fields created to track the number
	// of weird occurrences such as time fallback, partial_result, vsyscall
	// count, watchdog startup timeouts and stuck tasks.
	WeirdnessMetric = MustCreateNewUint64Metric("/weirdness", true, "Increment for weird occurrences of problems such as time fallback, partial result, vsyscalls invoked in the sandbox, watchdog startup timeouts and stuck tasks.",
		Field{
			name:          "weirdness_type",
			allowedValues: []string{"time_fallback", "partial_result", "vsyscall_count", "watchdog_stuck_startup", "watchdog_stuck_tasks"},
		})

	// SuspiciousOperationsMetric is a metric with fields created to detect
	// operations such as opening an executable file to write from a gofer.
	SuspiciousOperationsMetric = MustCreateNewUint64Metric("/suspicious_operations", true, "Increment for suspicious operations such as opening an executable file to write from a gofer.",
		Field{
			name:          "operation_type",
			allowedValues: []string{"opened_write_execute_file"},
		})
)

Functions

func Disable

func Disable() error

Disable sends an empty metric registration event over the event channel, disabling metric collection.

Precondition:

• All metrics are registered.
• Initialize/Disable has not been called.

func EmitMetricUpdate

func EmitMetricUpdate()

EmitMetricUpdate emits a MetricUpdate over the event channel.

Only metrics that have changed since the last call are emitted.

EmitMetricUpdate is thread-safe.

Preconditions: * Initialize has been called.

func Initialize

func Initialize() error

Initialize sends a metric registration event over the event channel.

Precondition:

• All metrics are registered.
• Initialize/Disable has not been called.

func MustRegisterCustomUint64Metric

func MustRegisterCustomUint64Metric(name string, cumulative, sync bool, description string, value func(...string) uint64, fields ...Field)

MustRegisterCustomUint64Metric calls RegisterCustomUint64Metric for metrics without fields and panics if it returns an error.

func RegisterCustomUint64Metric

func RegisterCustomUint64Metric(name string, cumulative, sync bool, units pb.MetricMetadata_Units, description string, value func(...string) uint64, fields ...Field) error

RegisterCustomUint64Metric registers a metric with the given name.

Register must only be called at init and will return and error if called after Initialized.

Preconditions: * name must be globally unique. * Initialize/Disable have not been called. * value is expected to accept exactly len(fields) arguments.

func StartStage

func StartStage(stage InitStage) func()

StartStage should be called when an initialization stage is started. It returns a function that must be called to indicate that the stage ended. Alternatively, future calls to StartStage will implicitly indicate that the previous stage ended. Stage information will be emitted in the next call to EmitMetricUpdate after a stage has ended.

This function may (and is expected to) be called prior to final initialization of this metric library, as it has to capture early stages of Sentry initialization.

Types

type Field

type Field struct {
	// contains filtered or unexported fields
}

Field contains the field name and allowed values for the metric which is used in registration of the metric.

type InitStage

type InitStage string

InitStage is the name of a Sentry initialization stage.

var (
	InitRestoreConfig InitStage = "restore_config"
	InitExecConfig    InitStage = "exec_config"
	InitRestore       InitStage = "restore"
	InitCreateProcess InitStage = "create_process"
	InitTaskStart     InitStage = "task_start"
)

List of all Sentry initialization stages.

type Uint64Metric

type Uint64Metric struct {
	// contains filtered or unexported fields
}

Uint64Metric encapsulates a uint64 that represents some kind of metric to be monitored. We currently support metrics with at most one field.

Metrics are not saved across save/restore and thus reset to zero on restore.

TODO(b/67298427): Support metric fields.

func MustCreateNewUint64Metric

func MustCreateNewUint64Metric(name string, sync bool, description string, fields ...Field) *Uint64Metric

MustCreateNewUint64Metric calls NewUint64Metric and panics if it returns an error.

func MustCreateNewUint64NanosecondsMetric

func MustCreateNewUint64NanosecondsMetric(name string, sync bool, description string) *Uint64Metric

MustCreateNewUint64NanosecondsMetric calls NewUint64Metric and panics if it returns an error.

func NewUint64Metric

func NewUint64Metric(name string, sync bool, units pb.MetricMetadata_Units, description string, fields ...Field) (*Uint64Metric, error)

NewUint64Metric creates and registers a new cumulative metric with the given name.

Metrics must be statically defined (i.e., at init).

func (*Uint64Metric) Increment

func (m *Uint64Metric) Increment(fieldValues ...string)

Increment increments the metric field by 1.

func (*Uint64Metric) IncrementBy

func (m *Uint64Metric) IncrementBy(v uint64, fieldValues ...string)

IncrementBy increments the metric by v.

func (*Uint64Metric) Value

func (m *Uint64Metric) Value(fieldValues ...string) uint64

Value returns the current value of the metric for the given set of fields.