stats

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 metric to be tracked and recorded. For example, latency, request Mb/s, and response Mb/s are measures to collect from a server.

Each measure needs to be registered before being used. 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 for their end users to create views and collect instrumentation data.

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. Users collect data points on the existing 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 user is not aggregating them via views. Users don't necessarily need to conditionally enable/disable recording to reduce cost. Recording of measurements is cheap.

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

Index

• Constants
• func Record(ctx context.Context, ms ...Measurement)
• type Float64Measure
  • func Float64(name, description, unit string) *Float64Measure
  • func (m *Float64Measure) Description() string
  • func (m *Float64Measure) M(v float64) Measurement
  • func (m *Float64Measure) Name() string
  • func (m *Float64Measure) Unit() string
• type Int64Measure
  • func Int64(name, description, unit string) *Int64Measure
  • func (m *Int64Measure) Description() string
  • func (m *Int64Measure) M(v int64) Measurement
  • func (m *Int64Measure) Name() string
  • func (m *Int64Measure) Unit() string
• type Measure
• type Measurement
  • func (m Measurement) Measure() Measure
  • func (m Measurement) Value() float64

Examples

• Record

Constants

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

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

Functions

func Record

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

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

Example

package main

import (
	"context"

	"go.opencensus.io/stats"
)

func main() {
	ctx := context.Background()

	// Measures are usually declared as package-private global variables.
	openConns := stats.Int64("example.com/measure/openconns", "open connections", stats.UnitDimensionless)

	// Instrumented packages call stats.Record() to record measuremens.
	stats.Record(ctx, openConns.M(124)) // Record 124 open connections.

	// Without any views or exporters registered, this statement has no observable effects.
}

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

func (m *Float64Measure) M(v float64) Measurement

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.