stats

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Feb 12, 2018 License: Apache-2.0 Imports: 7 Imported by: 1,727

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.

Example (Record)
package main

import (
	"context"
	"log"

	"go.opencensus.io/stats"
)

func main() {
	m, err := stats.Int64("my.org/measure/openconns", "open connections", "")
	if err != nil {
		log.Fatal(err)
	}

	stats.Record(context.TODO(), m.M(124)) // Record 124 open connections.
}
Output:

Example (View)
package main

import (
	"log"

	"go.opencensus.io/stats"
	"go.opencensus.io/stats/view"
)

func main() {
	m, err := stats.Int64("my.org/measure/openconns", "open connections", "")
	if err != nil {
		log.Fatal(err)
	}

	view, err := view.New(
		"my.org/views/openconns",
		"open connections",
		nil,
		m,
		view.DistributionAggregation([]float64{0, 1000, 2000}),
	)
	if err != nil {
		log.Fatal(err)
	}
	if err := view.Subscribe(); err != nil {
		log.Fatal(err)
	}

	// Use stats.RegisterExporter to export collected data.
}
Output:

Index

Examples

Constants

View Source
const (
	UnitNone         = "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

Variables

This section is empty.

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.

Types

type Float64Measure added in v0.3.0

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

Float64Measure is a measure of type float64.

func Float64 added in v0.3.0

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

Float64 creates a new measure of type Float64Measure. It returns an error if a measure with the same name already exists.

func (*Float64Measure) Description added in v0.3.0

func (m *Float64Measure) Description() string

Description returns the description of the measure.

func (*Float64Measure) M added in v0.3.0

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

func (*Float64Measure) Name added in v0.3.0

func (m *Float64Measure) Name() string

Name returns the name of the measure.

func (*Float64Measure) Unit added in v0.3.0

func (m *Float64Measure) Unit() string

Unit returns the unit of the measure.

type Int64Measure added in v0.3.0

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

Int64Measure is a measure of type int64.

func Int64 added in v0.3.0

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

Int64 creates a new measure of type Int64Measure. It returns an error if a measure with the same name already exists.

func (*Int64Measure) Description added in v0.3.0

func (m *Int64Measure) Description() string

Description returns the description of the measure.

func (*Int64Measure) M added in v0.3.0

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

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

func (*Int64Measure) Name added in v0.3.0

func (m *Int64Measure) Name() string

Name returns the name of the measure.

func (*Int64Measure) Unit added in v0.3.0

func (m *Int64Measure) Unit() string

Unit returns the unit of the measure.

type Measure

type Measure interface {
	Name() string
	Description() string
	Unit() string
}

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 registers the measure by the given name. Each registered measure needs to be unique by name. Measures also have a description and a unit.

func FindMeasure

func FindMeasure(name string) Measure

type Measurement

type Measurement struct {
	Value   interface{} // int64 or float64
	Measure Measure
}

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.

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.

Jump to

Keyboard shortcuts

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