metricdata

Documentation

Overview

Package metricdata contains the metrics data model.

This is an EXPERIMENTAL package, and may change in arbitrary ways without notice.

Index

• type Attachments
• type Bucket
• type BucketOptions
• type Descriptor
• type Distribution
• type Exemplar
• type LabelValue
  • func NewLabelValue(val string) LabelValue
• type Metric
• type Point
  • func NewDistributionPoint(t time.Time, val *Distribution) Point
  • func NewFloat64Point(t time.Time, val float64) Point
  • func NewInt64Point(t time.Time, val int64) Point
  • func NewSummaryPoint(t time.Time, val *Summary) Point
  • func (p Point) ReadValue(vv ValueVisitor)
• type Snapshot
• type Summary
• type TimeSeries
• type Type
  • func (i Type) String() string
• type Unit
• type ValueVisitor

Types

type Attachments

type Attachments map[string]interface{}

Attachments is a map of extra values associated with a recorded data point.

type Bucket

type Bucket struct {
	// Count is the number of values in each bucket of the histogram, as described in
	// bucket_bounds.
	Count int64
	// Exemplar associated with this bucket (if any).
	Exemplar *Exemplar
}

Bucket represents a single bucket (value range) in a distribution.

type BucketOptions

type BucketOptions struct {
	// Bounds specifies a set of bucket upper bounds.
	// This defines len(bounds) + 1 (= N) buckets. The boundaries for bucket
	// index i are:
	//
	// [0, Bounds[i]) for i == 0
	// [Bounds[i-1], Bounds[i]) for 0 < i < N-1
	// [Bounds[i-1], +infinity) for i == N-1
	Bounds []float64
}

BucketOptions describes the bounds of the histogram buckets in this distribution.

type Descriptor

type Descriptor struct {
	Name        string   // full name of the metric
	Description string   // human-readable description
	Unit        Unit     // units for the measure
	Type        Type     // type of measure
	LabelKeys   []string // label keys
}

Descriptor holds metadata about a metric.

type Distribution

type Distribution struct {
	// Count is the number of values in the population. Must be non-negative. This value
	// must equal the sum of the values in bucket_counts if a histogram is
	// provided.
	Count int64
	// Sum is the sum of the values in the population. If count is zero then this field
	// must be zero.
	Sum float64
	// SumOfSquaredDeviation is the sum of squared deviations from the mean of the values in the
	// population. For values x_i this is:
	//
	//     Sum[i=1..n]((x_i - mean)^2)
	//
	// Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition
	// describes Welford's method for accumulating this sum in one pass.
	//
	// If count is zero then this field must be zero.
	SumOfSquaredDeviation float64
	// BucketOptions describes the bounds of the histogram buckets in this
	// distribution.
	//
	// A Distribution may optionally contain a histogram of the values in the
	// population.
	//
	// If nil, there is no associated histogram.
	BucketOptions *BucketOptions
	// Bucket If the distribution does not have a histogram, then omit this field.
	// If there is a histogram, then the sum of the values in the Bucket counts
	// must equal the value in the count field of the distribution.
	Buckets []Bucket
}

Distribution contains summary statistics for a population of values. It optionally contains a histogram representing the distribution of those values across a set of buckets.

type Exemplar

type Exemplar struct {
	Value       float64     // the value that was recorded
	Timestamp   time.Time   // the time the value was recorded
	Attachments Attachments // attachments (if any)
}

Exemplar is an example data point associated with each bucket of a distribution type aggregation.

Their purpose is to provide an example of the kind of thing (request, RPC, trace span, etc.) that resulted in that measurement.

type LabelValue

type LabelValue struct {
	Value   string // string value of the label
	Present bool   // flag that indicated whether a value is present or not
}

LabelValue represents the value of a label. The zero value represents a missing label value, which may be treated differently to an empty string value by some back ends.

func NewLabelValue

func NewLabelValue(val string) LabelValue

NewLabelValue creates a new non-nil LabelValue that represents the given string.

type Metric

type Metric struct {
	Descriptor Descriptor         // metric descriptor
	Resource   *resource.Resource // resource against which this was measured
	TimeSeries []*TimeSeries      // one time series for each combination of label values
}

Metric represents a quantity measured against a resource with different label value combinations.

type Point

type Point struct {
	// Time is the point in time that this point represents in a time series.
	Time time.Time
	// Value is the value of this point. Prefer using ReadValue to switching on
	// the value type, since new value types might be added.
	Value interface{}
}

Point is a single data point of a time series.

func NewDistributionPoint

func NewDistributionPoint(t time.Time, val *Distribution) Point

NewDistributionPoint creates a new Point holding a Distribution value.

func NewFloat64Point

func NewFloat64Point(t time.Time, val float64) Point

NewFloat64Point creates a new Point holding a float64 value.

func NewInt64Point

func NewInt64Point(t time.Time, val int64) Point

NewInt64Point creates a new Point holding an int64 value.

func NewSummaryPoint

func NewSummaryPoint(t time.Time, val *Summary) Point

NewSummaryPoint creates a new Point holding a Summary value.

func (Point) ReadValue

func (p Point) ReadValue(vv ValueVisitor)

ReadValue accepts a ValueVisitor and calls the appropriate method with the value of this point. Consumers of Point should use this in preference to switching on the type of the value directly, since new value types may be added.

type Snapshot

type Snapshot struct {
	// Count is the number of values in the snapshot. Optional since some systems don't
	// expose this. Set to 0 if not available.
	Count int64
	// Sum is the sum of values in the snapshot. Optional since some systems don't
	// expose this. If count is 0 then this field must be zero.
	Sum float64
	// Percentiles is a map from percentile (range (0-100.0]) to the value of
	// the percentile.
	Percentiles map[float64]float64
}

Snapshot represents percentiles over an arbitrary time. The values in this struct can be reset at arbitrary unknown times, with the requirement that all of them are reset at the same time.

type Summary

type Summary struct {
	// Count is the cumulative count (if available).
	Count int64
	// Sum is the cumulative sum of values  (if available).
	Sum float64
	// HasCountAndSum is true if Count and Sum are available.
	HasCountAndSum bool
	// Snapshot represents percentiles calculated over an arbitrary time window.
	// The values in this struct can be reset at arbitrary unknown times, with
	// the requirement that all of them are reset at the same time.
	Snapshot Snapshot
}

Summary is a representation of percentiles.

type TimeSeries

type TimeSeries struct {
	LabelValues []LabelValue // label values, same order as keys in the metric descriptor
	Points      []Point      // points sequence
	StartTime   time.Time    // time we started recording this time series
}

TimeSeries is a sequence of points associated with a combination of label values.

type Type

type Type int

Type is the overall type of metric, including its value type and whether it represents a cumulative total (since the start time) or if it represents a gauge value.

const (
	TypeGaugeInt64 Type = iota
	TypeGaugeFloat64
	TypeGaugeDistribution
	TypeCumulativeInt64
	TypeCumulativeFloat64
	TypeCumulativeDistribution
	TypeSummary
)

Metric types.

func (Type) String

func (i Type) String() string

type Unit

type Unit string

Unit is a string encoded according to the case-sensitive abbreviations from the Unified Code for Units of Measure: http://unitsofmeasure.org/ucum.html

const (
	UnitDimensionless Unit = "1"
	UnitBytes         Unit = "By"
	UnitMilliseconds  Unit = "ms"
)

Predefined units. To record against a unit not represented here, create your own Unit type constant from a string.

type ValueVisitor

type ValueVisitor interface {
	VisitFloat64Value(float64)
	VisitInt64Value(int64)
	VisitDistributionValue(*Distribution)
	VisitSummaryValue(*Summary)
}

ValueVisitor allows reading the value of a point.