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.
All recorded measurements can be grouped by a list of tags.
OpenCensus provides several aggregation methods: Count, Distribution and Sum.
Count only counts the number of measurement points recorded. Distribution provides statistical summary of the aggregated data by counting how many recorded measurements fall into each bucket. Sum adds up the measurement values. LastValue just keeps track of the most recently recorded measurement value. All aggregations are cumulative.
Views can be registered and unregistered at any time during program execution.
Libraries can define views but it is recommended that in most cases registering views be left up to applications.
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 back ends.
Example ¶
package main
import (
"log"
"go.opencensus.io/stats"
"go.opencensus.io/stats/view"
)
func main() {
// Measures are usually declared and used by instrumented packages.
m := stats.Int64("example.com/measure/openconns", "open connections", stats.UnitDimensionless)
// Views are usually registered in your application main function.
if err := view.Register(&view.View{
Name: "example.com/views/openconns",
Description: "open connections",
Measure: m,
Aggregation: view.Distribution(0, 1000, 2000),
}); err != nil {
log.Fatal(err)
}
// Use view.RegisterExporter to export collected data.
}
Output:
Index ¶
- Variables
- func ClearStart(data AggregationData)
- func Register(views ...*View) error
- func RegisterExporter(e Exporter)
- func SetReportingPeriod(d time.Duration)
- func Stop()
- func Unregister(views ...*View)
- func UnregisterExporter(e Exporter)
- type AggType
- type Aggregation
- type AggregationData
- type CountData
- type Data
- type DistributionData
- type Exporter
- type LastValueData
- type Meter
- type Row
- type SumData
- type View
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNegativeBucketBounds = errors.New("negative bucket bounds not supported")
ErrNegativeBucketBounds error returned if histogram contains negative bounds.
Deprecated: this should not be public.
Functions ¶
func ClearStart ¶ added in v0.22.5
func ClearStart(data AggregationData)
ClearStart clears the Start field from data if present. Useful for testing in cases where the start time will be nondeterministic.
func Register ¶
Register begins collecting data for the given views. Once a view is registered, it reports data to the registered exporters.
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.
Binaries can register exporters, libraries shouldn't register exporters.
func SetReportingPeriod ¶
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.
Note: each exporter makes different promises about what the lowest supported duration is. For example, the Stackdriver exporter recommends a value no lower than 1 minute. Consult each exporter per your needs.
func Unregister ¶
func Unregister(views ...*View)
Unregister the given views. Data will not longer be exported for these views after Unregister returns. It is not necessary to unregister from views you expect to collect for the duration of your program execution.
func UnregisterExporter ¶
func UnregisterExporter(e Exporter)
UnregisterExporter unregisters an exporter.
Types ¶
type AggType ¶ added in v0.6.0
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. AggTypeDistribution // the distribution aggregation, see Distribution. AggTypeLastValue // the last value aggregation, see LastValue. )
All available aggregation types.
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, or Distribution to construct an Aggregation.
func Count ¶ added in v0.6.0
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 ¶ added in v0.6.0
func Distribution(bounds ...float64) *Aggregation
Distribution indicates that the desired aggregation is a histogram distribution.
A 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 LastValue ¶ added in v0.7.0
func LastValue() *Aggregation
LastValue only reports the last value recorded using this aggregation. All other measurements will be dropped.
func Sum ¶ added in v0.6.0
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 ¶
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 ¶
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 ¶
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
// ExemplarsPerBucket is slice the same length as CountPerBucket containing
// an exemplar for the associated bucket, or nil.
ExemplarsPerBucket []*metricdata.Exemplar
Start time.Time
// contains filtered or unexported fields
}
DistributionData is the aggregated data for the Distribution aggregation.
Most users won't directly access distribution data.
For a distribution with N bounds, the associated DistributionData will have N+1 buckets.
func (*DistributionData) StartTime ¶ added in v0.22.5
func (a *DistributionData) StartTime() time.Time
StartTime returns the start time of the data being aggregated by DistributionData.
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.
It is safe to assume that ExportView will not be called concurrently from multiple goroutines.
The Data should not be modified.
type LastValueData ¶ added in v0.7.0
type LastValueData struct {
Value float64
}
LastValueData returns the last value recorded for LastValue aggregation.
func (*LastValueData) StartTime ¶ added in v0.22.5
func (l *LastValueData) StartTime() time.Time
StartTime returns an empty time value as start time is not recorded when using last value aggregation.
type Meter ¶ added in v0.22.4
type Meter interface {
stats.Recorder
// Find returns a registered view associated with this name.
// If no registered view is found, nil is returned.
Find(name string) *View
// Register begins collecting data for the given views.
// Once a view is registered, it reports data to the registered exporters.
Register(views ...*View) error
// Unregister the given views. Data will not longer be exported for these views
// after Unregister returns.
// It is not necessary to unregister from views you expect to collect for the
// duration of your program execution.
Unregister(views ...*View)
// 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.
//
// Note: each exporter makes different promises about what the lowest supported
// duration is. For example, the Stackdriver exporter recommends a value no
// lower than 1 minute. Consult each exporter per your needs.
SetReportingPeriod(time.Duration)
// 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.
//
// Binaries can register exporters, libraries shouldn't register exporters.
RegisterExporter(Exporter)
// UnregisterExporter unregisters an exporter.
UnregisterExporter(Exporter)
// SetResource may be used to set the Resource associated with this registry.
// This is intended to be used in cases where a single process exports metrics
// for multiple Resources, typically in a multi-tenant situation.
SetResource(*resource.Resource)
// Start causes the Meter to start processing Record calls and aggregating
// statistics as well as exporting data.
Start()
// Stop causes the Meter to stop processing calls and terminate data export.
Stop()
// RetrieveData gets a snapshot of the data collected for the the view registered
// with the given name. It is intended for testing only.
RetrieveData(viewName string) ([]*Row, error)
}
Meter defines an interface which allows a single process to maintain multiple sets of metrics exports (intended for the advanced case where a single process wants to report metrics about multiple objects, such as multiple databases or HTTP services).
Note that this is an advanced use case, and the static functions in this module should cover the common use cases.
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 ¶ added in v0.4.0
RetrieveData gets a snapshot of the data collected for the the view registered with the given name. It is intended for testing only.
type SumData ¶
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 to apply to the set of Measurements.
Aggregation *Aggregation
}
View allows users to aggregate the recorded stats.Measurements. Views need to be passed to the Register function before data will be collected and sent to Exporters.
Source Files