github.com/uber-go/tally/v4@v4.1.17/prometheus/README.md (about)

     1  # A buffered Prometheus reporter
     2  
     3  See `examples/prometheus_main.go` for an end to end example.
     4  
     5  ## Options
     6  
     7  You can use a specific Prometheus registry, and you can use
     8  either summaries or histograms for timers.
     9  
    10  The reporter options are:
    11  
    12  ```go
    13  // Options is a set of options for the tally reporter.
    14  type Options struct {
    15  	// Registerer is the prometheus registerer to register
    16  	// metrics with. Use nil to specify the default registerer.
    17  	Registerer prom.Registerer
    18  
    19  	// DefaultTimerType is the default type timer type to create
    20  	// when using timers. It's default value is a histogram timer type.
    21  	DefaultTimerType TimerType
    22  
    23  	// DefaultHistogramBuckets is the default histogram buckets
    24  	// to use. Use nil to specify the default histogram buckets.
    25  	DefaultHistogramBuckets []float64
    26  
    27  	// DefaultSummaryObjectives is the default summary objectives
    28  	// to use. Use nil to specify the default summary objectives.
    29  	DefaultSummaryObjectives map[float64]float64
    30  
    31  	// OnRegisterError defines a method to call to when registering
    32  	// a metric with the registerer fails. Use nil to specify
    33  	// to panic by default when registering a metric fails.
    34  	OnRegisterError func(err error)
    35  }
    36  ```
    37  
    38  The timer types are:
    39  
    40  ```go
    41  // TimerType describes a type of timer
    42  type TimerType int
    43  
    44  const (
    45  	// SummaryTimerType is a timer type that reports into a summary
    46  	SummaryTimerType TimerType = iota
    47  
    48  	// HistogramTimerType is a timer type that reports into a histogram
    49  	HistogramTimerType
    50  )
    51  ```
    52  
    53  You can also pre-register help description text ahead of using a metric
    54  that will be named and tagged identically with `tally`. You can also
    55  access the Prometheus HTTP handler directly.
    56  
    57  The returned reporter interface:
    58  
    59  ```go
    60  // Reporter is a Prometheus backed tally reporter.
    61  type Reporter interface {
    62  	tally.CachedStatsReporter
    63  
    64  	// HTTPHandler provides the Prometheus HTTP scrape handler.
    65  	HTTPHandler() http.Handler
    66  
    67  	// RegisterCounter is a helper method to initialize a counter
    68  	// in the Prometheus backend with a given help text.
    69  	// If not called explicitly, the Reporter will create one for
    70  	// you on first use, with a not super helpful HELP string.
    71  	RegisterCounter(
    72  		name string,
    73  		tagKeys []string,
    74  		desc string,
    75  	) (*prom.CounterVec, error)
    76  
    77  	// RegisterGauge is a helper method to initialize a gauge
    78  	// in the prometheus backend with a given help text.
    79  	// If not called explicitly, the Reporter will create one for
    80  	// you on first use, with a not super helpful HELP string.
    81  	RegisterGauge(
    82  		name string,
    83  		tagKeys []string,
    84  		desc string,
    85  	) (*prom.GaugeVec, error)
    86  
    87  	// RegisterTimer is a helper method to initialize a timer
    88  	// summary or histogram vector in the prometheus backend
    89  	// with a given help text.
    90  	// If not called explicitly, the Reporter will create one for
    91  	// you on first use, with a not super helpful HELP string.
    92  	// You may pass opts as nil to get the default timer type
    93  	// and objectives/buckets.
    94  	// You may also pass objectives/buckets as nil in opts to
    95  	// get the default objectives/buckets for the specified
    96  	// timer type.
    97  	RegisterTimer(
    98  		name string,
    99  		tagKeys []string,
   100  		desc string,
   101  		opts *RegisterTimerOptions,
   102  	) (TimerUnion, error)
   103  }
   104  ```
   105  
   106  The register timer options:
   107  
   108  ```go
   109  // RegisterTimerOptions provides options when registering a timer on demand.
   110  // By default you can pass nil for the options to get the reporter defaults.
   111  type RegisterTimerOptions struct {
   112  	TimerType         TimerType
   113  	HistogramBuckets  []float64
   114  	SummaryObjectives map[float64]float64
   115  }
   116  ```
   117  
   118