Documentation

Overview

Package stats contains support for OpenCensus stats recording.

OpenCensus allows users to create typed measures, record measurements, aggregate the collected data, and export the aggregated data.

Measures

A measure represents a type of data point to be tracked and recorded. For example, latency, request Mb/s, and response Mb/s are measures to collect from a server.

Measure constructors such as Int64 and Float64 automatically register the measure by the given name. Each registered measure needs to be unique by name. Measures also have a description and a unit.

Libraries can define and export measures. Application authors can then create views and collect and break down measures by the tags they are interested in.

Recording measurements

Measurement is a data point to be collected for a measure. For example, for a latency (ms) measure, 100 is a measurement that represents a 100ms latency event. Measurements are created from measures with the current context. Tags from the current context are recorded with the measurements if they are any.

Recorded measurements are dropped immediately if no views are registered for them. There is usually no need to conditionally enable and disable recording to reduce cost. Recording of measurements is cheap.

Libraries can always record measurements, and applications can later decide on which measurements they want to collect by registering views. This allows libraries to turn on the instrumentation by default.

Exemplars

For a given recorded measurement, the associated exemplar is a diagnostic map that gives more information about the measurement.

When aggregated using a Distribution aggregation, an exemplar is kept for each bucket in the Distribution. This allows you to easily find an example of a measurement that fell into each bucket.

For example, if you also use the OpenCensus trace package and you record a measurement with a context that contains a sampled trace span, then the trace span will be added to the exemplar associated with the measurement.

When exported to a supporting back end, you should be able to easily navigate to example traces that fell into each bucket in the Distribution.

Index

Examples

Constants

View Source
const (
	UnitNone          = "1" // Deprecated: Use UnitDimensionless.
	UnitDimensionless = "1"
	UnitBytes         = "By"
	UnitMilliseconds  = "ms"
	UnitSeconds       = "s"
)

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

    Variables

    This section is empty.

    Functions

    func Record

    func Record(ctx context.Context, ms ...Measurement)

      Record records one or multiple measurements with the same context at once. If there are any tags in the context, measurements will be tagged with them.

      Example
      Output:
      
      

      func RecordWithOptions

      func RecordWithOptions(ctx context.Context, ros ...Options) error

        RecordWithOptions records measurements from the given options (if any) against context and tags and attachments in the options (if any). If there are any tags in the context, measurements will be tagged with them.

        func RecordWithTags

        func RecordWithTags(ctx context.Context, mutators []tag.Mutator, ms ...Measurement) error

          RecordWithTags records one or multiple measurements at once.

          Measurements will be tagged with the tags in the context mutated by the mutators. RecordWithTags is useful if you want to record with tag mutations but don't want to propagate the mutations in the context.

          Types

          type Float64Measure

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

            Float64Measure is a measure for float64 values.

            func Float64

            func Float64(name, description, unit string) *Float64Measure

              Float64 creates a new measure for float64 values.

              See the documentation for interface Measure for more guidance on the parameters of this function.

              func (*Float64Measure) Description

              func (m *Float64Measure) Description() string

                Description returns the description of the measure.

                func (*Float64Measure) M

                  M creates a new float64 measurement. Use Record to record measurements.

                  func (*Float64Measure) Name

                  func (m *Float64Measure) Name() string

                    Name returns the name of the measure.

                    func (*Float64Measure) Unit

                    func (m *Float64Measure) Unit() string

                      Unit returns the unit of the measure.

                      type Int64Measure

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

                        Int64Measure is a measure for int64 values.

                        func Int64

                        func Int64(name, description, unit string) *Int64Measure

                          Int64 creates a new measure for int64 values.

                          See the documentation for interface Measure for more guidance on the parameters of this function.

                          func (*Int64Measure) Description

                          func (m *Int64Measure) Description() string

                            Description returns the description of the measure.

                            func (*Int64Measure) M

                            func (m *Int64Measure) M(v int64) Measurement

                              M creates a new int64 measurement. Use Record to record measurements.

                              func (*Int64Measure) Name

                              func (m *Int64Measure) Name() string

                                Name returns the name of the measure.

                                func (*Int64Measure) Unit

                                func (m *Int64Measure) Unit() string

                                  Unit returns the unit of the measure.

                                  type Measure

                                  type Measure interface {
                                  	// Name returns the name of this measure.
                                  	//
                                  	// Measure names are globally unique (among all libraries linked into your program).
                                  	// We recommend prefixing the measure name with a domain name relevant to your
                                  	// project or application.
                                  	//
                                  	// Measure names are never sent over the wire or exported to backends.
                                  	// They are only used to create Views.
                                  	Name() string
                                  
                                  	// Description returns the human-readable description of this measure.
                                  	Description() string
                                  
                                  	// Unit returns the units for the values this measure takes on.
                                  	//
                                  	// Units are encoded according to the case-sensitive abbreviations from the
                                  	// Unified Code for Units of Measure: http://unitsofmeasure.org/ucum.html
                                  	Unit() string
                                  }

                                    Measure represents a single numeric value to be tracked and recorded. For example, latency, request bytes, and response bytes could be measures to collect from a server.

                                    Measures by themselves have no outside effects. In order to be exported, the measure needs to be used in a View. If no Views are defined over a measure, there is very little cost in recording it.

                                    type Measurement

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

                                      Measurement is the numeric value measured when recording stats. Each measure provides methods to create measurements of their kind. For example, Int64Measure provides M to convert an int64 into a measurement.

                                      func (Measurement) Measure

                                      func (m Measurement) Measure() Measure

                                        Measure returns the Measure from which this Measurement was created.

                                        func (Measurement) Value

                                        func (m Measurement) Value() float64

                                          Value returns the value of the Measurement as a float64.

                                          type Options

                                          type Options func(*recordOptions)

                                            Options apply changes to recordOptions.

                                            func WithAttachments

                                            func WithAttachments(attachments metricdata.Attachments) Options

                                              WithAttachments applies provided exemplar attachments.

                                              func WithMeasurements

                                              func WithMeasurements(measurements ...Measurement) Options

                                                WithMeasurements applies provided measurements.

                                                func WithRecorder

                                                func WithRecorder(meter Recorder) Options

                                                  WithRecorder records the measurements to the specified `Recorder`, rather than to the global metrics recorder.

                                                  func WithTags

                                                  func WithTags(mutators ...tag.Mutator) Options

                                                    WithTags applies provided tag mutators.

                                                    type Recorder

                                                    type Recorder interface {
                                                    	// Record records a set of measurements associated with the given tags and attachments.
                                                    	// The second argument is a `[]Measurement`.
                                                    	Record(*tag.Map, interface{}, map[string]interface{})
                                                    }

                                                      Recorder provides an interface for exporting measurement information from the static Record method by using the WithRecorder option.

                                                      Directories

                                                      Path Synopsis
                                                      Package view contains support for collecting and exposing aggregates over stats.
                                                      Package view contains support for collecting and exposing aggregates over stats.