prometheus

Documentation

Overview

Package prometheus contains Prometheus-compliant metric data structures and utilities in pure Go. This should not have external dependencies as it is linked into the Sentry. It can export data in Prometheus data format, documented at: https://prometheus.io/docs/instrumenting/exposition_formats/

Index

• Constants
• Variables
• func OrderedLabels(labels ...map[string]string) <-chan LabelOrError
• func Write[T io.StringWriter](w T, options ExportOptions, ...) (int, error)
• func WriteHex[T io.StringWriter](w T, val uint64) (int, error)
• func WriteInteger[T io.StringWriter](w T, val int64) (int, error)
• type Bucket
• type Data
  • func LabeledFloatData(metric *Metric, labels map[string]string, val float64) *Data
  • func LabeledIntData(metric *Metric, labels map[string]string, val int64) *Data
  • func NewFloatData(metric *Metric, val float64) *Data
  • func NewIntData(metric *Metric, val int64) *Data
  • func (d *Data) SetExternalLabels(externalLabels map[string]string) *Data
• type ExportOptions
• type Histogram
• type LabelOrError
• type Metric
• type Number
  • func NewFloat(val float64) *Number
  • func NewInt(val int64) *Number
  • func (n *Number) GreaterThan(other *Number) bool
  • func (n *Number) IsInteger() bool
  • func (n *Number) SameType(other *Number) bool
  • func (n *Number) String() string
  • func (n *Number) ToFloat() float64
• type ReusableWriter
  • func (rw *ReusableWriter[T]) Write(w T, options ExportOptions, ...) (int, error)
• type Snapshot
  • func NewSnapshot() *Snapshot
  • func (s *Snapshot) Add(data ...*Data) *Snapshot
• type SnapshotExportOptions
• type Type
• type Verifier
  • func NewVerifier(registration *pb.MetricRegistration) (*Verifier, func(), error)
  • func (v *Verifier) AllMetrics() []*pb.MetricMetadata
  • func (v *Verifier) Verify(snapshot *Snapshot) error

Constants

const (
	SandboxIDLabel   = "sandbox"
	PodNameLabel     = "pod_name"
	NamespaceLabel   = "namespace_name"
	IterationIDLabel = "iteration"
)

Prometheus label names used to identify each sandbox.

const (
	TypeUntyped = Type(iota)
	TypeGauge
	TypeCounter
	TypeHistogram
)

List of supported Prometheus metric types.

const (

	// MetaMetricPrefix is a prefix used for metrics defined by the metric server,
	// as opposed to metrics generated by each sandbox.
	// For this reason, this prefix is not allowed to be used in sandbox metrics.
	MetaMetricPrefix = "meta_"
)

Variables

var (
	ProcessCPUSecondsTotal = Metric{
		Name: "process_cpu_seconds_total",
		Type: TypeGauge,
		Help: "Total user and system CPU time spent in seconds.",
	}
	ProcessOpenFDs = Metric{
		Name: "process_open_fds",
		Type: TypeGauge,
		Help: "Number of open file descriptors.",
	}
	ProcessMaxFDs = Metric{
		Name: "process_max_fds",
		Type: TypeGauge,
		Help: "Maximum number of open file descriptors.",
	}
	ProcessVirtualMemoryBytes = Metric{
		Name: "process_virtual_memory_bytes",
		Type: TypeGauge,
		Help: "Virtual memory size in bytes.",
	}
	ProcessVirtualMemoryMaxBytes = Metric{
		Name: "process_virtual_memory_max_bytes",
		Type: TypeGauge,
		Help: "Maximum amount of virtual memory available in bytes.",
	}
	ProcessResidentMemoryBytes = Metric{
		Name: "process_resident_memory_bytes",
		Type: TypeGauge,
		Help: "Resident memory size in bytes.",
	}
	ProcessHeapBytes = Metric{
		Name: "process_heap_bytes",
		Type: TypeGauge,
		Help: "Process heap size in bytes.",
	}
	ProcessStartTimeSeconds = Metric{
		Name: "process_start_time_seconds",
		Type: TypeGauge,
		Help: "Start time of the process since unix epoch in seconds.",
	}
	ProcessThreads = Metric{
		Name: "process_threads",
		Type: TypeGauge,
		Help: "Number of OS threads in the process.",
	}
)

Prometheus process-level metric names and definitions. These are not necessarily exported, but we enforce that sandboxes may not export metrics sharing the same names. https://prometheus.io/docs/instrumenting/writing_clientlibs/#process-metrics

Functions

func OrderedLabels

func OrderedLabels(labels ...map[string]string) <-chan LabelOrError

OrderedLabels streams the list of 'label_key="label_value"' in sorted order, except "le" which is a reserved Prometheus label name and should go last. If an error is encountered, it is returned as the Error field of LabelOrError, and no further messages will be sent on the channel.

func Write

func Write[T io.StringWriter](w T, options ExportOptions, snapshotsToOptions map[*Snapshot]SnapshotExportOptions) (int, error)

Write writes one or more snapshots to the writer. This ensures same-name metrics across different snapshots are printed together, per spec. If the caller will call `Write` successively for multiple snapshots, it is more efficient to use the `ReusableWriter` type instead of this function.

func WriteHex

func WriteHex[T io.StringWriter](w T, val uint64) (int, error)

WriteHex writes the given integer as hex to a writer without allocating strings.

func WriteInteger

func WriteInteger[T io.StringWriter](w T, val int64) (int, error)

WriteInteger writes the given integer to a writer without allocating strings.

Types

type Bucket

type Bucket struct {
	// UpperBound is the upper bound of the bucket.
	// The lower bound of the bucket is the largest UpperBound within other Histogram Buckets that
	// is smaller than this bucket's UpperBound.
	// The bucket with the smallest UpperBound within a Histogram implicitly has -Inf as lower bound.
	// This should be set to +Inf to mark the "last" bucket.
	UpperBound Number `json:"le"`

	// Samples is the number of samples in the bucket.
	// Note: When exported to Prometheus, they are exported cumulatively, i.e. the count of samples
	// exported in Bucket i is actually sum(histogram.Buckets[j].Samples for 0 <= j <= i).
	Samples uint64 `json:"n,omitempty"`
}

Bucket is a single histogram bucket.

type Data

type Data struct {
	// Metric is the metric for which the value is being reported.
	Metric *Metric `json:"metric"`

	// Labels is a key-value pair representing the labels set on this metric.
	// This may be merged with other labels during export.
	Labels map[string]string `json:"labels,omitempty"`

	// ExternalLabels are more labels merged together with `Labels`.
	// They can be set using SetExternalLabels.
	// They are useful in the case where a single Data needs labels from two sources:
	// labels specific to this data point (which should be in `Labels`), and labels
	// that are shared between multiple data points (stored in `ExternalLabels`).
	// This avoids allocating unique `Labels` maps for each Data struct, when
	// most of the actual labels would be shared between them.
	ExternalLabels map[string]string `json:"external_labels,omitempty"`

	// Number is used for all numerical types.
	Number *Number `json:"val,omitempty"`

	// Histogram is used for histogram-typed metrics.
	HistogramValue *Histogram `json:"histogram,omitempty"`
}

Data is an observation of the value of a single metric at a certain point in time.

func LabeledFloatData

func LabeledFloatData(metric *Metric, labels map[string]string, val float64) *Data

LabeledFloatData returns a new Data struct with the given metric, labels, and value.

func LabeledIntData

func LabeledIntData(metric *Metric, labels map[string]string, val int64) *Data

LabeledIntData returns a new Data struct with the given metric, labels, and value.

func NewFloatData

func NewFloatData(metric *Metric, val float64) *Data

NewFloatData returns a new Data struct with the given metric and value.

func NewIntData

func NewIntData(metric *Metric, val int64) *Data

NewIntData returns a new Data struct with the given metric and value.

func (*Data) SetExternalLabels

func (d *Data) SetExternalLabels(externalLabels map[string]string) *Data

SetExternalLabels sets d.ExternalLabels. See its docstring for more information. Returns `d` for chainability.

type ExportOptions

type ExportOptions struct {
	// CommentHeader is prepended as a comment before any metric data is exported.
	CommentHeader string

	// MetricsWritten memoizes written metric preambles (help/type comments)
	// by metric name.
	// If specified, this map can be used to avoid duplicate preambles across multiple snapshots.
	// Note that this map is modified in-place during the writing process.
	MetricsWritten map[string]bool
}

ExportOptions contains options that control how metric data is exported in Prometheus format.

type Histogram

type Histogram struct {
	// Total is the sum of sample values across all buckets.
	Total Number `json:"total"`
	// Min is the minimum sample ever recorded in this histogram.
	Min Number `json:"min"`
	// Max is the maximum sample ever recorded in this histogram.
	Max Number `json:"max"`
	// SumOfSquaredDeviations is the number of squared deviations of all samples.
	SumOfSquaredDeviations Number `json:"ssd"`
	// Buckets contains per-bucket data.
	// A distribution with n finite-boundary buckets should have n+2 entries here.
	// The 0th entry is the underflow bucket (i.e. the one with -inf as lower bound),
	// and the last aka (n+1)th entry is the overflow bucket (i.e. the one with +inf as upper bound).
	Buckets []Bucket `json:"buckets,omitempty"`
}

Histogram contains data about histogram values.

type LabelOrError

type LabelOrError struct {
	Key, Value string
	Error      error
}

LabelOrError is used in OrderedLabels. It represents either a key-value pair, or an error.

type Metric

type Metric struct {
	// Name is the Prometheus metric name.
	Name string `json:"name"`

	// Type is the type of the metric.
	Type Type `json:"type"`

	// Help is an optional helpful string explaining what the metric is about.
	Help string `json:"help"`
}

Metric is a Prometheus metric metadata.

type Number

type Number struct {
	// Float is the float value of this number.
	// Mutually exclusive with Int.
	Float float64 `json:"float,omitempty"`

	// Int is the integer value of this number.
	// Mutually exclusive with Float.
	Int int64 `json:"int,omitempty"`
}

Number represents a numerical value. In Prometheus, all numbers are float64s. However, for the purpose of usage of this library, we support expressing numbers as integers, which makes things like counters much easier and more precise. At data export time (i.e. when written out in Prometheus data format), it is coalesced into a float.

func NewFloat

func NewFloat(val float64) *Number

NewFloat returns a new floating-point Number.

func NewInt

func NewInt(val int64) *Number

NewInt returns a new integer Number.

func (*Number) GreaterThan

func (n *Number) GreaterThan(other *Number) bool

GreaterThan returns true if n > other. Precondition: n.SameType(other) is true. Panics otherwise.

func (*Number) IsInteger

func (n *Number) IsInteger() bool

IsInteger returns whether this number contains an integer value. This is defined as either having the `Float` part set to zero (in which case the `Int` part takes precedence), or having `Float` be a value equal to its own rounding and not a special float.

func (*Number) SameType

func (n *Number) SameType(other *Number) bool

SameType returns true if `n` and `other` are either both floating-point or both integers. If a `Number` is zero, it is considered of the same type as any other zero `Number`.

func (*Number) String

func (n *Number) String() string

String returns a string representation of this number.

func (*Number) ToFloat

func (n *Number) ToFloat() float64

ToFloat returns this number as a floating-point number, regardless of which type the number was encoded as. An integer Number will have its value cast to a float, while a floating-point Number will have its value returned as-is.

type ReusableWriter

type ReusableWriter[T io.StringWriter] struct {
	// contains filtered or unexported fields
}

ReusableWriter is a writer that can be reused to efficiently write successive snapshots.

func (*ReusableWriter[T]) Write

func (rw *ReusableWriter[T]) Write(w T, options ExportOptions, snapshotsToOptions map[*Snapshot]SnapshotExportOptions) (int, error)

Write writes one or more snapshots to the writer. This method may not be used concurrently for the same `ReusableWriter`.

type Snapshot

type Snapshot struct {
	// When is the timestamp at which the snapshot was taken.
	// Note that Prometheus ultimately encodes timestamps as millisecond-precision int64s from epoch.
	When time.Time `json:"when,omitempty"`

	// Data is the whole snapshot data.
	// Each Data must be a unique combination of (Metric, Labels) within a Snapshot.
	Data []*Data `json:"data,omitempty"`
}

Snapshot is a snapshot of the values of all the metrics at a certain point in time.

func NewSnapshot

func NewSnapshot() *Snapshot

NewSnapshot returns a new Snapshot at the current time.

func (*Snapshot) Add

func (s *Snapshot) Add(data ...*Data) *Snapshot

Add data point(s) to the snapshot. Returns itself for chainability.

type SnapshotExportOptions

type SnapshotExportOptions struct {
	// ExporterPrefix is prepended to all metric names.
	ExporterPrefix string

	// ExtraLabels is added as labels for all metric values.
	ExtraLabels map[string]string
}

SnapshotExportOptions contains options that control how metric data is exported for an individual Snapshot.

type Type

type Type int

Type is a Prometheus metric type.

type Verifier

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

Verifier allows verifying metric snapshot against metric registration data. The aim is to prevent a compromised Sentry from emitting bogus data or DoS'ing metric ingestion. A single Verifier should be used per sandbox. It is expected to be reused across exports such that it can enforce the export snapshot timestamp is strictly monotonically increasing.

func NewVerifier

func NewVerifier(registration *pb.MetricRegistration) (*Verifier, func(), error)

NewVerifier returns a new metric verifier that can verify the integrity of snapshots against the given metric registration data. It returns a cleanup function that must be called when the Verifier is no longer needed.

func (*Verifier) AllMetrics

func (v *Verifier) AllMetrics() []*pb.MetricMetadata

AllMetrics returns the metadata of all the metrics that were declared as part of this Verifier.

func (*Verifier) Verify

func (v *Verifier) Verify(snapshot *Snapshot) error

Verify verifies the integrity of a snapshot against the metric registration data of the Verifier. It assumes that it will be called on snapshots obtained chronologically over time.