vendor/go.opencensus.io/exemplar/exemplar.go

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