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 (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)
}
v, err := view.New(
"my.org/views/openconns",
"open connections distribution over one second time window",
nil,
m,
view.DistributionAggregation([]float64{0, 1000, 2000}),
)
if err != nil {
log.Fatal(err)
}
if err := v.Subscribe(); err != nil {
log.Fatal(err)
}
// Use stats.RegisterExporter to export collected data.
}
Output:
Index ¶
- func Register(v *View) error
- func RegisterExporter(e Exporter)
- func SetReportingPeriod(d time.Duration)
- func Unregister(v *View) error
- func UnregisterExporter(e Exporter)
- type Aggregation
- type AggregationData
- type CountAggregation
- type CountData
- type Data
- type DistributionAggregation
- type DistributionData
- type Exporter
- type MeanAggregation
- type MeanData
- type Row
- type SumAggregation
- type SumData
- type View
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Register ¶
Register 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. Registration can be used by libraries to claim a view name.
Unregister the view once the view is not required anymore.
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 ¶
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 Unregister ¶
Unregister 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.
func UnregisterExporter ¶
func UnregisterExporter(e Exporter)
UnregisterExporter unregisters an exporter.
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 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 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 {
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 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.
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.
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. Each view has to be registered to enable data retrieval. Use New to initiate new views. Unregister views once you don't want to collect any more events.
func Find ¶
FindMeasure returns a registered view associated with this name. If no registered view is found, nil is returned.
func New ¶
func New(name, description string, keys []tag.Key, measure stats.Measure, agg Aggregation) (*View, error)
New 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.
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 ¶
Description returns the name of the view.
func (*View) RetrieveData ¶
RetrieveData returns the current collected data for the view.
func (*View) Subscribe ¶
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) Unsubscribe ¶
Unsubscribe unsubscribes a previously subscribed view. Data will not be exported from this view once unsubscription happens.
Source Files