telemetry

README

Telemetry

The metrics utility for offchain-sdk.

types.go defines the interface for the supported metrics methods.

By specifying the configuration, the metrics can be emitted via Datadog and/or Prometheus. Please see the following subsections for detailed configurations.

Datadog

Configuration

The first step is adding a section in your config file. See following subsection for details. The source code defining those configs can be found in config.go.

Datadog Configs

• Enabled: Set to true to enable metrics emission to Datadog.

• StatsdAddr: The address of the Datadog StatsD client. This is needed if the metrics should be emitted from Datadog.

• Namespace: This will appear as the Namespace tag in Datadog.

Datadog Methods

metrics.go implements the Datadog version of the supported metrics methods defined in types.go. All implementations are simple wrappers around the native methods provided by the Datadog statsd client.

Prometheus

Configuration

The first step is to add a section in your config file. The source code defining these configs can be found in config.go.

Prometheus Configs

• Enabled: Set to true to enable metrics emission to Prometheus.

• Namespace and Subsystem: These fields will be added as prefixes to the metrics name. For example, if Namespace is app and Subsystem is api, then the full metrics name of request_success will be app_api_request_success.

• HistogramBucketCount: The number of buckets used for Histogram typed metrics. Default is 10.

  • Note: Each bucket represents an observation that Prometheus scrapes. Therefore, it's recommended to keep the number of buckets within a manageable scale, typically in the tens.

Prometheus Methods

Different from Datadog, Prometheus only provides 4 basic metrics type. As a result, metrics.go implements the metrics methods defined in type.go using these four basic Prometheus metrics. The following subsection documents the methods with implementation notes. For more information on the four basic Prometheus metrics, please see here.

• Gauge: This method wraps the Gauge metrics of Prometheus.

• Decr and Incr: Implemented using the Gauge metrics of Prometheus.

• Count: This method wraps the Count metrics of Prometheus. Note that after deployment or instance restart, Count will reset to 0. This is by design in Prometheus.

• IncMonotonic and Error: Implemented using the Count metrics of Prometheus.

• Histogram: This method wraps the Histogram metrics of Prometheus with linear buckets.

  • Note: The maximum value covered is determined by the product of BucketCount and the rate parameter.
  • TODO: Support different types of buckets beyond linear buckets in future implementations.

• Time and Latency: Implemented using the Summary metrics of Prometheus, with pre-defined quantile observations: p50, p90, and p99.

Documentation

Index

• func ParseLabelPairsToTags(labels, labelValues []string) []string
• func WrapHTTPHandler(m Metrics, log log.Logger) func(http.Handler) http.Handler
• func WrapMicroServerHandler(m Metrics, log log.Logger) server.HandlerWrapper
• type Config
• type Metrics
  • func NewMetrics(cfg *Config) (Metrics, error)
  • func NewNoopMetrics() Metrics

Functions

func ParseLabelPairsToTags

func ParseLabelPairsToTags(labels, labelValues []string) []string

ParseLabelPairsToTags converts a list of label names and values to a list of tags, in format of "name:value".

func WrapHTTPHandler

func WrapHTTPHandler(m Metrics, log log.Logger) func(http.Handler) http.Handler

WrapHTTPHandler wraps a HTTP server with the given Metrics instance. to collect telemetry for every request/response.

func WrapMicroServerHandler

func WrapMicroServerHandler(m Metrics, log log.Logger) server.HandlerWrapper

WrapMicroServerHandler wraps a Micro server with the given Metrics instance to collect telemetry for every request/response.

Types

type Config

type Config struct {
	HealthReportInterval time.Duration

	Datadog    datadog.Config
	Prometheus prometheus.Config
}

Config serves as a global telemetry configuration. Provide the required config for the desired telemetry backend(s).

type Metrics

type Metrics interface {
	Gauge(name string, value float64, rate float64, tags ...string)

	Incr(name string, tags ...string) // should be used if the metric can go up or down
	Decr(name string, tags ...string) // should be used if the metric can go up or down

	Count(name string, value int64, tags ...string)

	IncMonotonic(name string, tags ...string) // should be used if the metric can go up only

	Error(errName string)

	Histogram(name string, value float64, rate float64, tags ...string)

	Time(name string, value time.Duration, tags ...string)
	Latency(jobName string, start time.Time, tags ...string)

	Close() error
}

Metrics are used to record telemetry data. The primary types of telemetry data supported are Gauges, Counters, and Histograms; the rest are convenience wrappers around these.

func NewMetrics

func NewMetrics(cfg *Config) (Metrics, error)

NewMetrics returns a new Metrics instance based on the given configuration. Enables only the telemetry backend(s) which is/are specified as enabled.

func NewNoopMetrics

func NewNoopMetrics() Metrics

NewNoopMetrics returns a new Metrics instance with no-op implementations.