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