1// Copyright 2018, 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// Package exemplar implements support for exemplars. Exemplars are additional
16// data associated with each measurement.
17//
18// Their purpose it to provide an example of the kind of thing
19// (request, RPC, trace span, etc.) that resulted in that measurement.
20package exemplar
21
22import (
23	"context"
24	"time"
25)
26
27// Exemplars keys.
28const (
29	KeyTraceID   = "trace_id"
30	KeySpanID    = "span_id"
31	KeyPrefixTag = "tag:"
32)
33
34// Exemplar is an example data point associated with each bucket of a
35// distribution type aggregation.
36type Exemplar struct {
37	Value       float64     // the value that was recorded
38	Timestamp   time.Time   // the time the value was recorded
39	Attachments Attachments // attachments (if any)
40}
41
42// Attachments is a map of extra values associated with a recorded data point.
43// The map should only be mutated from AttachmentExtractor functions.
44type Attachments map[string]string
45
46// AttachmentExtractor is a function capable of extracting exemplar attachments
47// from the context used to record measurements.
48// The map passed to the function should be mutated and returned. It will
49// initially be nil: the first AttachmentExtractor that would like to add keys to the
50// map is responsible for initializing it.
51type AttachmentExtractor func(ctx context.Context, a Attachments) Attachments
52
53var extractors []AttachmentExtractor
54
55// RegisterAttachmentExtractor registers the given extractor associated with the exemplar
56// type name.
57//
58// Extractors will be used to attempt to extract exemplars from the context
59// associated with each recorded measurement.
60//
61// Packages that support exemplars should register their extractor functions on
62// initialization.
63//
64// RegisterAttachmentExtractor should not be called after any measurements have
65// been recorded.
66func RegisterAttachmentExtractor(e AttachmentExtractor) {
67	extractors = append(extractors, e)
68}
69
70// AttachmentsFromContext extracts exemplars from the given context.
71// Each registered AttachmentExtractor (see RegisterAttachmentExtractor) is called in an
72// unspecified order to add attachments to the exemplar.
73func AttachmentsFromContext(ctx context.Context) Attachments {
74	var a Attachments
75	for _, extractor := range extractors {
76		a = extractor(ctx, a)
77	}
78	return a
79}
80