// This library is not intended to be used standalone, and provides no guarantees of backwards compatibility. // The library’s import path is github.com/uber/jaeger-lib. // [doc-img]: https://godoc.org/github.com/uber/jaeger-lib?status.svg // [doc]: https://godoc.org/github.com/uber/jaeger-lib // [ci-img]: workflows/Unit%20Tests/badge.svg?branch=main // [ci]: actions?query=branch%3Amain // [cov-img]: https://coveralls.io/repos/jaegertracing/jaeger-lib/badge.svg?branch=main&service=github // [cov]: https://coveralls.io/github/jaegertracing/jaeger-lib?branch=main
// This package provides shared infrastructure libraries used by various components of the Jaeger backend and jaeger-client-go. // For the purpose of this document, the term ‘metrics’ refers to the internal structure of the library.
// This outline focuses on the metrics package, which is responsible for handling errors and propagating them appropriately.
// Specifically, it defines a set of interfaces for handling metrics data, such as Counter, Gauge, Timer, and Histogram, and provides concrete implementations of these interfaces using different backends like tally, expvar, etc.
// The metrics package provides a set of interfaces and concrete implementations for handling metrics data.
// The interfaces are defined in metrics/metrics.go.
// The implementations are provided in various sub-packages, like metrics/tally, metrics/expvar, etc.
// To initialize metrics, use Init function in metrics/metrics.go.
// This function accepts a struct containing metrics fields annotated with tags and a factory function to create metrics objects.
// The following sections provide more details about the error handling mechanisms implemented in metrics package:
Metrics Interface
// Counter tracks the number of times an event has occurred
type Counter interface {
// Inc adds the given value to the counter.
Inc(int64)
}
// Gauge tracks the value of a metric
type Gauge interface {
// Update updates the gauge to the given value.
Update(int64)
}
// Timer accumulates observations about how long some operation took,
// and also maintains a historgam of percentiles.
type Timer interface {
// Records the time passed in.
Record(time.Duration)
}
// Histogram tracks the distribution of values
type Histogram interface {
// Record records the given value
Record(float64)
}
Metrics Factory
// Factory is used to create new metrics objects, like counters, gauges, timers, etc.
type Factory interface {
// Counter creates a new Counter
Counter(Options) Counter
// Gauge creates a new Gauge
Gauge(Options) Gauge
// Timer creates a new Timer
Timer(TimerOptions) Timer
// Histogram creates a new Histogram
Histogram(HistogramOptions) Histogram
// Namespace creates a new Factory with the given namespace and tags.
Namespace(NSOptions) Factory
}
Metrics Options
// Options are used to configure a new Counter or Gauge
type Options struct {
// Name is the name of the metric.
Name string
// Tags is a map of tags to be associated with the metric.
Tags map[string]string
// Help is a description of the metric.
Help string
}
// TimerOptions are used to configure a new Timer
type TimerOptions struct {
// Name is the name of the timer
Name string
// Tags is a map of tags to be associated with the timer
Tags map[string]string
// Help is a description of the timer
Help string
// Buckets defines the set of buckets for the histogram
Buckets []time.Duration
}
// HistogramOptions are used to configure a new Histogram
type HistogramOptions struct {
// Name is the name of the histogram
Name string
// Tags is a map of tags to be associated with the histogram
Tags map[string]string
// Help is a description of the histogram
Help string
// Buckets defines the set of buckets for the histogram
Buckets []float64
}
// NSOptions are used to configure a new Factory with the given namespace and tags
type NSOptions struct {
// Name is the namespace of the factory.
Name string
// Tags is a map of tags to be associated with the factory.
Tags map[string]string
}
Metrics Null Factory
// NullFactory is a no-op Factory
var NullFactory Factory = &nullFactory{}
type nullFactory struct{}
func (nullFactory) Counter(Options) Counter {
return &nullCounter{}
}
func (nullFactory) Gauge(Options) Gauge {
return &nullGauge{}
}
func (nullFactory) Timer(TimerOptions) Timer {
return &nullTimer{}
}
func (nullFactory) Histogram(HistogramOptions) Histogram {
return &nullHistogram{}
}
func (nullFactory) Namespace(NSOptions) Factory {
return &nullFactory{}
}
Metrics Null Implementations
// NullCounter is a no-op Counter
type nullCounter struct{}
func (nullCounter) Inc(int64) {}
// NullGauge is a no-op Gauge
type nullGauge struct{}
func (nullGauge) Update(int64) {}
// NullTimer is a no-op Timer
type nullTimer struct{}
func (nullTimer) Record(time.Duration) {}
// NullHistogram is a no-op Histogram
type nullHistogram struct{}
func (nullHistogram) Record(float64) {}
Metrics Wrapping Tally
// Wrap takes a tally Scope and returns jaeger-lib metrics.Factory.
func Wrap(scope tally.Scope) metrics.Factory {
return &factory{
tally: scope,
}
}
// Factory is a wrapper for tally Scope to implement jaeger-lib metrics.Factory interface
type factory struct {
tally tally.Scope
}
Metrics Stopwatch
// A Stopwatch tracks the execution time of a specific event
type Stopwatch struct {
t Timer
start time.Time
}
// Stop stops executing of the stopwatch and records the amount of elapsed time
func (s Stopwatch) Stop() {
s.t.Record(s.ElapsedTime())
}
// This outline focuses on the `metrics` package, which is responsible for handling errors and propagating them appropriately.
// Specifically, it defines a set of interfaces for handling metrics data, such as `Counter`, `Gauge`, `Timer`, and `Histogram`, and provides concrete implementations of these interfaces using different backends like `tally`, `expvar`, etc.
// The `metrics` package provides a set of interfaces and concrete implementations for handling metrics data.
// The interfaces are defined in `metrics/metrics.go`.
// The implementations are provided in various sub-packages, like `metrics/tally`, `metrics/expvar`, etc.
// To initialize metrics, use `Init` function in `metrics/metrics.go`.
// This function accepts a struct containing metrics fields annotated with tags and a factory function to create metrics objects.
// The following sections provide more details about the error handling mechanisms implemented in `metrics` package:
## Metrics Interface
```go
// Counter tracks the number of times an event has occurred
type Counter interface {
// Inc adds the given value to the counter.
Inc(int64)
}
// Gauge tracks the value of a metric
type Gauge interface {
// Update updates the gauge to the given value.
Update(int64)
}
// Timer accumulates observations about how long some operation took,
// and also maintains a historgam of percentiles.
type Timer interface {
// Records the time passed in.
Record(time.Duration)
}
// Histogram tracks the distribution of values
type Histogram interface {
// Record records the given value
Record(float64)
}
Metrics Factory
// Factory is used to create new metrics objects, like counters, gauges, timers, etc.
type Factory interface {
// Counter creates a new Counter
Counter(Options) Counter
// Gauge creates a new Gauge
Gauge(Options) Gauge
// Timer creates a new Timer
Timer(TimerOptions) Timer
// Histogram creates a new Histogram
Histogram(HistogramOptions) Histogram
// Namespace creates a new Factory with the given namespace and tags.
Namespace(NSOptions) Factory
}
Metrics Options
// Options are used to configure a new Counter or Gauge
type Options struct {
// Name is the name of the metric.
Name string
// Tags is a map of tags to be associated with the metric.
Tags map[string]string
// Help is a description of the metric.
Help string
}
// TimerOptions are used to configure a new Timer
type TimerOptions struct {
// Name is the name of the timer
Name string
// Tags is a map of tags to be associated with the timer
Tags map[string]string
// Help is a description of the timer
Help string
// Buckets defines the set of buckets for the histogram
Buckets []time.Duration
}
// HistogramOptions are used to configure a new Histogram
type HistogramOptions struct {
// Name is the name of the histogram
Name string
// Tags is a map of tags to be associated with the histogram
Tags map[string]string
// Help is a description of the histogram
Help string
// Buckets defines the set of buckets for the histogram
Buckets []float64
}
// NSOptions are used to configure a new Factory with the given namespace and tags
type NSOptions struct {
// Name is the namespace of the factory.
Name string
// Tags is a map of tags to be associated with the factory.
Tags map[string]string
}
Metrics Null Factory
// NullFactory is a no-op Factory
var NullFactory Factory = &nullFactory{}
type nullFactory struct{}
func (nullFactory) Counter(Options) Counter {
return &nullCounter{}
}
func (nullFactory) Gauge(Options) Gauge {
return &nullGauge{}
}
func (nullFactory) Timer(TimerOptions) Timer {
return &nullTimer{}
}
func (nullFactory) Histogram(HistogramOptions) Histogram {
return &nullHistogram{}
}
func (nullFactory) Namespace(NSOptions) Factory {
return &nullFactory{}
}
Metrics Null Implementations
// NullCounter is a no-op Counter
type nullCounter struct{}
func (nullCounter) Inc(int64) {}
// NullGauge is a no-op Gauge
type nullGauge struct{}
func (nullGauge) Update(int64) {}
// NullTimer is a no-op Timer
type nullTimer struct{}
func (nullTimer) Record(time.Duration) {}
// NullHistogram is a no-op Histogram
type nullHistogram struct{}
func (nullHistogram) Record(float64) {}
Metrics Wrapping Tally
// Wrap takes a tally Scope and returns jaeger-lib metrics.Factory.
func Wrap(scope tally.Scope) metrics.Factory {
return &factory{
tally: scope,
}
}
// Factory is a wrapper for tally Scope to implement jaeger-lib metrics.Factory interface
type factory struct {
tally tally.Scope
}
Metrics Stopwatch
// A Stopwatch tracks the execution time of a specific event
type Stopwatch struct {
t Timer
start time.Time
}
// Stop stops executing of the stopwatch and records the amount of elapsed time
func (s Stopwatch) Stop() {
s.t.Record(s.ElapsedTime())
}
// This library is not intended to be used standalone, and provides no guarantees of backwards compatibility.
// The library's import path is github.com/uber/jaeger-lib.
// [doc-img]: https://godoc.org/github.com/uber/jaeger-lib?status.svg
// [doc]: https://godoc.org/github.com/uber/jaeger-lib
// [ci-img]: https://github.com/jaegertracing/jaeger-lib/workflows/Unit%20Tests/badge.svg?branch=main
// [ci]: https://github.com/jaegertracing/jaeger-lib/actions?query=branch%3Amain
// [cov-img]: https://coveralls.io/repos/jaegertracing/jaeger-lib/badge.svg?branch=main&service=github
// [cov]: https://coveralls.io/github/jaegertracing/jaeger-lib?branch=main
// This package provides shared infrastructure libraries used by various components of the Jaeger backend and jaeger-client-go.
// For the purpose of this document, the term 'metrics' refers to the internal structure of the library.
// This outline focuses on the `metrics` package, which is responsible for handling errors and propagating them appropriately.
// Specifically, it defines a set of interfaces for handling metrics data, such as `Counter`, `Gauge`, `Timer`, and `Histogram`, and provides concrete implementations of these interfaces using different backends like `tally`, `expvar`, etc.
// The `metrics` package provides a set of interfaces and concrete implementations for handling metrics data.
// The interfaces are defined in `metrics/metrics.go`.
// The implementations are provided in various sub-packages, like `metrics/tally`, `metrics/expvar`, etc.
// To initialize metrics, use `Init` function in `metrics/metrics.go`.
// This function accepts a struct containing metrics fields annotated with tags and a factory function to create metrics objects.
// The following sections provide more details about the error handling mechanisms implemented in `metrics` package:
## Metrics Interface
```go
// Counter tracks the number of times an event has occurred
type Counter interface {
// Inc adds the given value to the counter.
Inc(int64)
}
// Gauge tracks the value of a metric
type Gauge interface {
// Update updates the gauge to the given value.
Update(int64)
}
// Timer accumulates observations about how long some operation took,
// and also maintains a historgam of percentiles.
type Timer interface {
// Records the time passed in.
Record(time.Duration)
}
// Histogram tracks the distribution of values
type Histogram interface {
// Record records the given value
Record(float64)
}
Metrics Factory
// Factory is used to create new metrics objects, like counters, gauges, timers, etc.
type Factory interface {
// Counter creates a new Counter
Counter(Options) Counter
// Gauge creates a new Gauge
Gauge(Options) Gauge
// Timer creates a new Timer
Timer(TimerOptions) Timer
// Histogram creates a new Histogram
Histogram(HistogramOptions) Histogram
// Namespace creates a new Factory with the given namespace and tags.
Namespace(NSOptions) Factory
}
Metrics Options
// Options are used to configure a new Counter or Gauge
type Options struct {
// Name is the name of the metric.
Name string
// Tags is a map of tags to be associated with the metric.
Tags map[string]string
// Help is a description of the metric.
Help string
}
// TimerOptions are used to configure a new Timer
type TimerOptions struct {
// Name is the name of the timer
Name string
// Tags is a map of tags to be associated with the timer
Tags map[string]string
// Help is a description of the timer
Help string
// Buckets defines the set of buckets for the histogram
Buckets []time.Duration
}
// HistogramOptions are used to configure a new Histogram
type HistogramOptions struct {
// Name is the name of the histogram
Name string
// Tags is a map of tags to be associated with the histogram
Tags map[string]string
// Help is a description of the histogram
Help string
// Buckets defines the set of buckets for the histogram
Buckets []float64
}
// NSOptions are used to configure a new Factory with the given namespace and tags
type NSOptions struct {
// Name is the namespace of the factory.
Name string
// Tags is a map of tags to be associated with the factory.
Tags map[string]string
}
Metrics Null Factory
// NullFactory is a no-op Factory
var NullFactory Factory = &nullFactory{}
type nullFactory struct{}
func (nullFactory) Counter(Options) Counter {
return &nullCounter{}
}
func (nullFactory) Gauge(Options) Gauge {
return &nullGauge{}
}
func (nullFactory) Timer(TimerOptions) Timer {
return &nullTimer{}
}
func (nullFactory) Histogram(HistogramOptions) Histogram {
return &nullHistogram{}
}
func (nullFactory) Namespace(NSOptions) Factory {
return &nullFactory{}
}
Metrics Null Implementations
// NullCounter is a no-op Counter
type nullCounter struct{}
func (nullCounter) Inc(int64) {}
// NullGauge is a no-op Gauge
type nullGauge struct{}
func (nullGauge) Update
## Top-Level Directory Explanations
<a class='local-link directory-link' data-ref="metrics/" href="#metrics/">metrics/</a> - This directory contains the metrics implementation for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="metrics/adapters/" href="#metrics/adapters/">metrics/adapters/</a> - This subdirectory contains the various metric adapters for different backends.
<a class='local-link directory-link' data-ref="metrics/expvar/" href="#metrics/expvar/">metrics/expvar/</a> - This subdirectory contains the implementation for exposing metrics as HTTP endpoints using the expvar package.
<a class='local-link directory-link' data-ref="metrics/fork/" href="#metrics/fork/">metrics/fork/</a> - This subdirectory contains the implementation for forking metrics between processes.
<a class='local-link directory-link' data-ref="metrics/go-kit/" href="#metrics/go-kit/">metrics/go-kit/</a> - This subdirectory contains the Go-Kit integration for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="metrics/go-kit/expvar/" href="#metrics/go-kit/expvar/">metrics/go-kit/expvar/</a> - This subdirectory contains the expvar implementation for the Go-Kit integration.
<a class='local-link directory-link' data-ref="metrics/go-kit/influx/" href="#metrics/go-kit/influx/">metrics/go-kit/influx/</a> - This subdirectory contains the InfluxDB implementation for the Go-Kit integration.
<a class='local-link directory-link' data-ref="metrics/metricstest/" href="#metrics/metricstest/">metrics/metricstest/</a> - This subdirectory contains the testing implementation for the metrics.
<a class='local-link directory-link' data-ref="metrics/multi/" href="#metrics/multi/">metrics/multi/</a> - This subdirectory contains the implementation for collecting metrics from multiple sources.
<a class='local-link directory-link' data-ref="metrics/prometheus/" href="#metrics/prometheus/">metrics/prometheus/</a> - This subdirectory contains the Prometheus implementation for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="metrics/tally/" href="#metrics/tally/">metrics/tally/</a> - This subdirectory contains the implementation for counting metrics using the tally package.
<a class='local-link directory-link' data-ref="sample/" href="#sample/">sample/</a> - This directory contains a sample implementation for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="utils/" href="#utils/">utils/</a> - This directory contains various utility functions for the project.
