prometheus

package
v0.0.0-...-8940ca0 Latest Latest
Warning

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

Go to latest
Published: Mar 9, 2023 License: Apache-2.0, MIT Imports: 12 Imported by: 0

Documentation

Overview

Package prometheus contains Prometheus-compliant metric data structures and utilities. It can export data in Prometheus data format, documented at: https://prometheus.io/docs/instrumenting/exposition_formats/

Index

Constants

View Source
const (
	SandboxIDLabel   = "sandbox"
	PodNameLabel     = "pod"
	NamespaceLabel   = "namespace"
	IterationIDLabel = "iteration"
)

Prometheus label names used to identify each sandbox.

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

List of supported Prometheus metric types.

Variables

This section is empty.

Functions

func OrderedLabels

func OrderedLabels(labels ...map[string]string) ([]string, error)

OrderedLabels returns the list of 'label_key="label_value"' in sorted order, except "le" which is a reserved Prometheus label name and should go last.

func Write

func Write(w io.Writer, 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.

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

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

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"`
	// 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 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 coallesced into a float.

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.

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, error)

NewVerifier returns a new metric verifier that can verify the integrity of snapshots against the given metric registration data.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL