1// Copyright 2017, OpenCensus Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15
16/*
17Package stats contains support for OpenCensus stats recording.
18
19OpenCensus allows users to create typed measures, record measurements,
20aggregate the collected data, and export the aggregated data.
21
22Measures
23
24A measure represents a type of data point to be tracked and recorded.
25For example, latency, request Mb/s, and response Mb/s are measures
26to collect from a server.
27
28Measure constructors such as Int64 and Float64 automatically
29register the measure by the given name. Each registered measure needs
30to be unique by name. Measures also have a description and a unit.
31
32Libraries can define and export measures. Application authors can then
33create views and collect and break down measures by the tags they are
34interested in.
35
36Recording measurements
37
38Measurement is a data point to be collected for a measure. For example,
39for a latency (ms) measure, 100 is a measurement that represents a 100ms
40latency event. Measurements are created from measures with
41the current context. Tags from the current context are recorded with the
42measurements if they are any.
43
44Recorded measurements are dropped immediately if no views are registered for them.
45There is usually no need to conditionally enable and disable
46recording to reduce cost. Recording of measurements is cheap.
47
48Libraries can always record measurements, and applications can later decide
49on which measurements they want to collect by registering views. This allows
50libraries to turn on the instrumentation by default.
51
52Exemplars
53
54For a given recorded measurement, the associated exemplar is a diagnostic map
55that gives more information about the measurement.
56
57When aggregated using a Distribution aggregation, an exemplar is kept for each
58bucket in the Distribution. This allows you to easily find an example of a
59measurement that fell into each bucket.
60
61For example, if you also use the OpenCensus trace package and you
62record a measurement with a context that contains a sampled trace span,
63then the trace span will be added to the exemplar associated with the measurement.
64
65When exported to a supporting back end, you should be able to easily navigate
66to example traces that fell into each bucket in the Distribution.
67
68*/
69package stats // import "go.opencensus.io/stats"
70