metrics.go raw

   1  // Package metrics defines the metrics APIs used by Smithy clients.
   2  package metrics
   3  
   4  import (
   5  	"context"
   6  
   7  	"github.com/aws/smithy-go"
   8  )
   9  
  10  // MeterProvider is the entry point for creating a Meter.
  11  type MeterProvider interface {
  12  	Meter(scope string, opts ...MeterOption) Meter
  13  }
  14  
  15  // MeterOption applies configuration to a Meter.
  16  type MeterOption func(o *MeterOptions)
  17  
  18  // MeterOptions represents configuration for a Meter.
  19  type MeterOptions struct {
  20  	Properties smithy.Properties
  21  }
  22  
  23  // Meter is the entry point for creation of measurement instruments.
  24  type Meter interface {
  25  	// integer/synchronous
  26  	Int64Counter(name string, opts ...InstrumentOption) (Int64Counter, error)
  27  	Int64UpDownCounter(name string, opts ...InstrumentOption) (Int64UpDownCounter, error)
  28  	Int64Gauge(name string, opts ...InstrumentOption) (Int64Gauge, error)
  29  	Int64Histogram(name string, opts ...InstrumentOption) (Int64Histogram, error)
  30  
  31  	// integer/asynchronous
  32  	Int64AsyncCounter(name string, callback Int64Callback, opts ...InstrumentOption) (AsyncInstrument, error)
  33  	Int64AsyncUpDownCounter(name string, callback Int64Callback, opts ...InstrumentOption) (AsyncInstrument, error)
  34  	Int64AsyncGauge(name string, callback Int64Callback, opts ...InstrumentOption) (AsyncInstrument, error)
  35  
  36  	// floating-point/synchronous
  37  	Float64Counter(name string, opts ...InstrumentOption) (Float64Counter, error)
  38  	Float64UpDownCounter(name string, opts ...InstrumentOption) (Float64UpDownCounter, error)
  39  	Float64Gauge(name string, opts ...InstrumentOption) (Float64Gauge, error)
  40  	Float64Histogram(name string, opts ...InstrumentOption) (Float64Histogram, error)
  41  
  42  	// floating-point/asynchronous
  43  	Float64AsyncCounter(name string, callback Float64Callback, opts ...InstrumentOption) (AsyncInstrument, error)
  44  	Float64AsyncUpDownCounter(name string, callback Float64Callback, opts ...InstrumentOption) (AsyncInstrument, error)
  45  	Float64AsyncGauge(name string, callback Float64Callback, opts ...InstrumentOption) (AsyncInstrument, error)
  46  }
  47  
  48  // InstrumentOption applies configuration to an instrument.
  49  type InstrumentOption func(o *InstrumentOptions)
  50  
  51  // InstrumentOptions represents configuration for an instrument.
  52  type InstrumentOptions struct {
  53  	UnitLabel   string
  54  	Description string
  55  }
  56  
  57  // Int64Counter measures a monotonically increasing int64 value.
  58  type Int64Counter interface {
  59  	Add(context.Context, int64, ...RecordMetricOption)
  60  }
  61  
  62  // Int64UpDownCounter measures a fluctuating int64 value.
  63  type Int64UpDownCounter interface {
  64  	Add(context.Context, int64, ...RecordMetricOption)
  65  }
  66  
  67  // Int64Gauge samples a discrete int64 value.
  68  type Int64Gauge interface {
  69  	Sample(context.Context, int64, ...RecordMetricOption)
  70  }
  71  
  72  // Int64Histogram records multiple data points for an int64 value.
  73  type Int64Histogram interface {
  74  	Record(context.Context, int64, ...RecordMetricOption)
  75  }
  76  
  77  // Float64Counter measures a monotonically increasing float64 value.
  78  type Float64Counter interface {
  79  	Add(context.Context, float64, ...RecordMetricOption)
  80  }
  81  
  82  // Float64UpDownCounter measures a fluctuating float64 value.
  83  type Float64UpDownCounter interface {
  84  	Add(context.Context, float64, ...RecordMetricOption)
  85  }
  86  
  87  // Float64Gauge samples a discrete float64 value.
  88  type Float64Gauge interface {
  89  	Sample(context.Context, float64, ...RecordMetricOption)
  90  }
  91  
  92  // Float64Histogram records multiple data points for an float64 value.
  93  type Float64Histogram interface {
  94  	Record(context.Context, float64, ...RecordMetricOption)
  95  }
  96  
  97  // AsyncInstrument is the universal handle returned for creation of all async
  98  // instruments.
  99  //
 100  // Callers use the Stop() API to unregister the callback passed at instrument
 101  // creation.
 102  type AsyncInstrument interface {
 103  	Stop()
 104  }
 105  
 106  // Int64Callback describes a function invoked when an async int64 instrument is
 107  // read.
 108  type Int64Callback func(context.Context, Int64Observer)
 109  
 110  // Int64Observer is the interface passed to async int64 instruments.
 111  //
 112  // Callers use the Observe() API of this interface to report metrics to the
 113  // underlying collector.
 114  type Int64Observer interface {
 115  	Observe(context.Context, int64, ...RecordMetricOption)
 116  }
 117  
 118  // Float64Callback describes a function invoked when an async float64
 119  // instrument is read.
 120  type Float64Callback func(context.Context, Float64Observer)
 121  
 122  // Float64Observer is the interface passed to async int64 instruments.
 123  //
 124  // Callers use the Observe() API of this interface to report metrics to the
 125  // underlying collector.
 126  type Float64Observer interface {
 127  	Observe(context.Context, float64, ...RecordMetricOption)
 128  }
 129  
 130  // RecordMetricOption applies configuration to a recorded metric.
 131  type RecordMetricOption func(o *RecordMetricOptions)
 132  
 133  // RecordMetricOptions represents configuration for a recorded metric.
 134  type RecordMetricOptions struct {
 135  	Properties smithy.Properties
 136  }
 137