Documentation

Overview

    Package metricdata contains the metrics data model.

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

    Index

    Constants

    View Source
    const (
    	AttachmentKeySpanContext = "SpanContext"
    )

      Exemplars keys.

      Variables

      This section is empty.

      Functions

      This section is empty.

      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   []LabelKey // 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 LabelKey

                  type LabelKey struct {
                  	Key         string
                  	Description string
                  }

                    LabelKey represents key of a label. It has optional description attribute.

                    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.