stats

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Dec 15, 2017 License: Apache-2.0 Imports: 12 Imported by: 1,581

Documentation

Overview

Package stats contains support for OpenCensus stats collection.

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 NewMeasureInt64 and NewMeasureFloat64 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.

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 is 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-user can later decide on which measurements they want to collect by registering views. This allows libraries to turn on the instrumentation by default.

Views

In order to collect measurements, views need to be defined and registered. A view allows recorded measurements to be filtered and aggregated over a time window.

All recorded measurements can be filtered by a list of tags.

OpenCensus provides several aggregation methods: count, distribution, sum and mean. Count aggregation only counts the number of measurement points. Distribution aggregation provides statistical summary of the aggregated data. Sum distribution sums up the measurement points. Mean provides the mean of the recorded measurements. Aggregations can either happen cumulatively or over an interval.

Users can dynamically create and delete views.

Libraries can export their own views and claim the view names by registering them themselves.

Exporting

Collected and aggregated data can be exported to a metric collection backend by registering its exporter.

Multiple exporters can be registered to upload the data to various different backends. Users need to unregister the exporters once they no longer are needed.

Example (Record) 
package main

import (
	"context"
	"log"

	"go.opencensus.io/stats"
)

func main() {
	m, err := stats.NewMeasureInt64("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"
	"time"

	"go.opencensus.io/stats"
)

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

	view, err := stats.NewView(
		"my.org/views/openconns",
		"open connections distribution over one second time window",
		nil,
		m,
		stats.DistributionAggregation([]float64{0, 1000, 2000}),
		stats.Interval{Duration: time.Second},
	)
	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

This section is empty.

Variables

This section is empty.

Functions

func DeleteMeasure 

func DeleteMeasure(m Measure) error

DeleteMeasure deletes an existing measure to allow for creation of a new measure with the same name. It returns an error if the measure cannot be deleted, such as one or multiple registered views refer to it.

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.

func RegisterExporter 

func RegisterExporter(e Exporter)

RegisterExporter registers an exporter. Collected data will be reported via all the registered exporters. Once you don't want data to be expoter on the registered exporter, use UnregisterExporter.

func RegisterView 

func RegisterView(v *View) error

RegisterView registers view. It returns an error if the view is already registered.

Subscription automatically registers a view. Most users will not register directly but register via subscription. Registeration can be used by libraries to claim a view name.

Unregister the view once the view is not required anymore.

func SetReportingPeriod 

func SetReportingPeriod(d time.Duration)

SetReportingPeriod sets the interval between reporting aggregated views in the program. If duration is less than or equal to zero, it enables the default behavior.

func UnregisterExporter 

func UnregisterExporter(e Exporter)

UnregisterExporter unregisters an exporter.

func UnregisterView 

func UnregisterView(v *View) error

UnregisterView removes the previously registered view. It returns an error if the view wasn't registered. All data collected and not reported for the corresponding view will be lost. The view is automatically be unsubscribed.

Types

type Aggregation 

type Aggregation interface {
	// contains filtered or unexported methods
}

Aggregation represents a data aggregation method. There are several aggregation methods made available in the package such as CountAggregation, SumAggregation, MeanAggregation and DistributionAggregation.

type AggregationData 

type AggregationData interface {
	// contains filtered or unexported methods
}

AggregationData represents an aggregated value from a collection. They are reported on the view data during exporting. Mosts users won't directly access aggregration data.

type CountAggregation 

type CountAggregation struct{}

CountAggregation indicates that data collected and aggregated with this method will be turned into a count value. For example, total number of accepted requests can be aggregated by using CountAggregation.

type CountData 

type CountData int64

CountData is the aggregated data for a CountAggregation. A count aggregation processes data and counts the recordings.

Most users won't directly access count data.

type Cumulative 

type Cumulative struct{}

Cumulative is a window that indicates that the aggregation occurs over the lifetime of the view.

type DistributionAggregation 

type DistributionAggregation []float64

DistributionAggregation indicates that the desired aggregation is a histogram distribution. An distribution aggregation may contain a histogram of the values in the population. The bucket boundaries for that histogram are described by DistributionAggregation slice. This defines length+1 buckets.

If length >= 2 then the boundaries for bucket index i are: 

[-infinity, bounds[i]) for i = 0
[bounds[i-1], bounds[i]) for 0 < i < length
[bounds[i-1], +infinity) for i = length

If length is 0 then there is no histogram associated with the distribution. There will be a single bucket with boundaries (-infinity, +infinity).

If length is 1 then there is no finite buckets, and that single element is the common boundary of the overflow and underflow buckets.

type DistributionData 

type DistributionData struct {
	Count           int64   // number of data points aggregated
	Min             float64 // minimum value in the distribution
	Max             float64 // max value in the distribution
	Mean            float64 // mean of the distribution
	SumOfSquaredDev float64 // sum of the squared deviation from the mean
	CountPerBucket  []int64 // number of occurrences per bucket
	// contains filtered or unexported fields
}

DistributionData is the aggregated data for an DistributionAggregation.

Most users won't directly access distribution data.

func (*DistributionData) Sum 

func (a *DistributionData) Sum() float64

Sum returns the sum of all samples collected.

type Exporter 

type Exporter interface {
	Export(viewData *ViewData)
}

Exporter exports the collected records as view data.

The Export method should return quickly; if an Exporter takes a significant amount of time to process a ViewData, that work should be done on another goroutine.

The ViewData should not be modified.

type Interval 

type Interval struct {
	Duration  time.Duration
	Intervals int
}

Interval is a window that indicates that the aggregation occurs over a sliding window of time: last n seconds, minutes, hours.

type MeanAggregation 

type MeanAggregation struct{}

MeanAggregation indicates that collect and aggregate data and maintain the mean value. For example, average latency in milliseconds can be aggregated by using MeanAggregation.

type MeanData 

type MeanData struct {
	Count float64 // number of data points aggregated
	Mean  float64 // mean of all data points
}

MeanData is the aggregated data for a MeanAggregation. A mean aggregation processes data and maintains the mean value.

Most users won't directly access mean data.

func (*MeanData) Sum 

func (a *MeanData) Sum() float64

Sum returns the sum of all samples collected.

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 NewMeasureInt64 and NewMeasureFloat64 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) (m Measure)

FindMeasure returns the registered measure associated with name. If no registered measure is not found, nil is returned.

type MeasureFloat64 

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

MeasureFloat64 is a measure of type float64.

func NewMeasureFloat64 

func NewMeasureFloat64(name, description, unit string) (*MeasureFloat64, error)

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

func (*MeasureFloat64) Description 

func (m *MeasureFloat64) Description() string

Description returns the description of the measure.

func (*MeasureFloat64) M 

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

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

func (*MeasureFloat64) Name 

func (m *MeasureFloat64) Name() string

Name returns the name of the measure.

func (*MeasureFloat64) Unit 

func (m *MeasureFloat64) Unit() string

Unit returns the unit of the measure.

type MeasureInt64 

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

MeasureInt64 is a measure of type int64.

func NewMeasureInt64 

func NewMeasureInt64(name, description, unit string) (*MeasureInt64, error)

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

func (*MeasureInt64) Description 

func (m *MeasureInt64) Description() string

Description returns the description of the measure.

func (*MeasureInt64) M 

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

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

func (*MeasureInt64) Name 

func (m *MeasureInt64) Name() string

Name returns the name of the measure.

func (*MeasureInt64) Unit 

func (m *MeasureInt64) Unit() string

Unit returns the unit of the measure.

type Measurement 

type Measurement interface {
	// contains filtered or unexported methods
}

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

type Row 

type Row struct {
	Tags []tag.Tag
	Data AggregationData
}

Row is the collected value for a specific set of key value pairs a.k.a tags.

func (*Row) Equal 

func (r *Row) Equal(other *Row) bool

Equal returns true if both Rows are equal. Tags are expected to be ordered by the key name. Even both rows have the same tags but the tags appear in different orders it will return false.

func (*Row) String 

func (r *Row) String() string

type SumAggregation 

type SumAggregation struct{}

SumAggregation indicates that data collected and aggregated with this method will be summed up. For example, accumulated request bytes can be aggregated by using SumAggregation.

type SumData 

type SumData float64

SumData is the aggregated data for a SumAggregation. A sum aggregation processes data and sums up the recordings.

Most users won't directly access sum data.

type View 

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

View allows users to filter and aggregate the recorded events over a time window. Each view has to be registered to enable data retrieval. Use NewView to initiate new views. Unregister views once you don't want to collect any more events.

func FindView 

func FindView(name string) (v *View)

FindView returns a registered view associated with this name. If no registered view is found, nil is returned.

func NewView 

func NewView(name, description string, keys []tag.Key, measure Measure, agg Aggregation, window Window) (*View, error)

NewView creates a new view with the given name and description. View names need to be unique globally in the entire system.

Data collection will only filter measurements recorded by the given keys. Collected data will be processed by the given aggregation algorithm for the given time window.

Views need to be subscribed toin order to retrieve collection data.

Once the view is no longer required, the view can be unregistered.

func (*View) Aggregation 

func (v *View) Aggregation() Aggregation

Aggregation returns the data aggregation method used to aggregate the measurements collected by this view.

func (*View) Description 

func (v *View) Description() string

Description returns the name of the view.

func (*View) Measure 

func (v *View) Measure() Measure

Measure returns the measure the view is collecting measurements for.

func (*View) Name 

func (v *View) Name() string

Name returns the name of the view.

func (*View) RetrieveData 

func (v *View) RetrieveData() ([]*Row, error)

RetrieveData returns the current collected data for the view.

func (*View) Subscribe 

func (v *View) Subscribe() error

Subscribe subscribes a view. Once a view is subscribed, it reports data via the exporters. During subscription, if the view wasn't registered, it will be automatically registered. Once the view is no longer needed to export data, user should unsubscribe from the view.

func (*View) TagKeys 

func (v *View) TagKeys() []tag.Key

TagKeys returns the list of tag keys assoicated with this view.

func (*View) Unsubscribe 

func (v *View) Unsubscribe() error

Unsubscribe unsubscribes a previously subscribed channel. Data will not be exported from this view once unsubscription happens. If no more subscriber for v exists and the the ad hoc collection for this view isn't active, data stops being collected for this view.

func (*View) Window 

func (v *View) Window() Window

Window returns the timing window being used to collect metrics from this view.

type ViewData 

type ViewData struct {
	View       *View
	Start, End time.Time
	Rows       []*Row
}

A ViewData is a set of rows about usage of the single measure associated with the given view during a particular window. Each row is specific to a unique set of tags.

type Window 

type Window interface {
	// contains filtered or unexported methods
}

Window represents a time interval or samples count over which the aggregation occurs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.