view

Documentation

Overview

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

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

package main

import (
	"log"

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

func main() {
	m, _ := stats.Int64("my.org/measure/openconns", "open connections", "")

	if err := view.Subscribe(&view.View{
		Name:        "my.org/views/openconns",
		Description: "open connections",
		Measure:     m,
		Aggregation: view.Distribution(0, 1000, 2000),
	}); err != nil {
		log.Fatal(err)
	}

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

Index

• func Register(_ *View) error
• func RegisterExporter(e Exporter)
• func SetReportingPeriod(d time.Duration)
• func Subscribe(views ...*View) error
• func Unregister(_ *View) error
• func UnregisterExporter(e Exporter)
• func Unsubscribe(views ...*View)
• type AggType
  • func (i AggType) String() string
• type Aggregation
  • func Count() *Aggregation
  • func Distribution(bounds ...float64) *Aggregation
  • func Mean() *Aggregation
  • func Sum() *Aggregation
• type AggregationData
• type CountData
• type Data
• type DistributionData
  • func (a *DistributionData) Sum() float64
• type Exporter
• type MeanData
  • func (a *MeanData) Sum() float64
• type Row
  • func RetrieveData(viewName string) ([]*Row, error)
  • func (r *Row) Equal(other *Row) bool
  • func (r *Row) String() string
• type SumData
• type View
  • func Find(name string) (v *View)
  • func New(name, description string, keys []tag.Key, measure stats.Measure, ...) (*View, error)
  • func (v *View) Subscribe() error
  • func (v *View) Unsubscribe() error
  • func (v *View) WithName(name string) *View

Examples

• Package

Functions

func Register

func Register(_ *View) error

Deprecated: Registering is a no-op. Use the Subscribe function.

func RegisterExporter

func RegisterExporter(e Exporter)

RegisterExporter registers an exporter. Collected data will be reported via all the registered exporters. Once you no longer want data to be exported, invoke UnregisterExporter with the previously registered exporter.

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 Subscribe

func Subscribe(views ...*View) error

Subscribe begins collecting data for the given views. Once a view is subscribed, it reports data to the registered exporters.

func Unregister

func Unregister(_ *View) error

Deprecated: Unregistering is a no-op, see: Unsubscribe.

func UnregisterExporter

func UnregisterExporter(e Exporter)

UnregisterExporter unregisters an exporter.

func Unsubscribe

func Unsubscribe(views ...*View)

Unsubscribe the given views. Data will not longer be exported for these views after Unsubscribe returns. It is not necessary to unsubscribe from views you expect to collect for the duration of your program execution.

Types

type AggType

type AggType int

AggType represents the type of aggregation function used on a View.

const (
	AggTypeNone         AggType = iota // no aggregation; reserved for future use.
	AggTypeCount                       // the count aggregation, see Count.
	AggTypeSum                         // the sum aggregation, see Sum.
	AggTypeMean                        // the mean aggregation, see Mean.
	AggTypeDistribution                // the distribution aggregation, see Distribution.
)

func (AggType) String

func (i AggType) String() string

type Aggregation

type Aggregation struct {
	Type    AggType   // Type is the AggType of this Aggregation.
	Buckets []float64 // Buckets are the bucket endpoints if this Aggregation represents a distribution, see Distribution.
	// contains filtered or unexported fields
}

Aggregation represents a data aggregation method. Use one of the functions: Count, Sum, Mean, or Distribution to construct an Aggregation.

func Count

func Count() *Aggregation

Count 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 Count.

func Distribution

func Distribution(bounds ...float64) *Aggregation

Distribution 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 the bounds. This defines len(bounds)+1 buckets.

If len(bounds) >= 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 len(bounds) is 0 then there is no histogram associated with the distribution. There will be a single bucket with boundaries (-infinity, +infinity).

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

func Mean

func Mean() *Aggregation

Mean indicates that collect and aggregate data and maintain the mean value. For example, average latency in milliseconds can be aggregated by using Mean, although in most cases it is preferable to use a Distribution.

func Sum

func Sum() *Aggregation

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

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 CountData

type CountData int64

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

Most users won't directly access count data.

type Data

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

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

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 the Distribution aggregation.

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 {
	ExportView(viewData *Data)
}

Exporter exports the collected records as view data.

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

The Data should not be modified.

type MeanData

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

MeanData is the aggregated data for the Mean aggregation. 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 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 RetrieveData

func RetrieveData(viewName string) ([]*Row, error)

func (*Row) Equal

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

same 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 SumData

type SumData float64

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

Most users won't directly access sum data.

type View

type View struct {
	Name        string // Name of View. Must be unique. If unset, will default to the name of the Measure.
	Description string // Description is a human-readable description for this view.

	// TagKeys are the tag keys describing the grouping of this view.
	// A single Row will be produced for each combination of associated tag values.
	TagKeys []tag.Key

	// Measure is a stats.Measure to aggregate in this view.
	Measure stats.Measure

	// Aggregation is the aggregation function tp apply to the set of Measurements.
	Aggregation *Aggregation
}

View allows users to aggregate the recorded stats.Measurements. Views need to be passed to the Subscribe function to be before data will be collected and sent to Exporters.

func Find

func Find(name string) (v *View)

Find returns a subscribed view associated with this name. If no subscribed view is found, nil is returned.

func New

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

Deprecated: Use &View{}.

func (*View) Subscribe

func (v *View) Subscribe() error

Deprecated: Use the Subscribe function.

func (*View) Unsubscribe

func (v *View) Unsubscribe() error

Deprecated: Use the Unsubscribe function instead.

func (*View) WithName

func (v *View) WithName(name string) *View

WithName returns a copy of the View with a new name. This is useful for renaming views to cope with limitations placed on metric names by various backends.