metrics

README

Metrics Package

The metrics package contains standard drivers for opentracing, profiling and metrics.You can enable this in your appplication by calling metrics.Setup(). This will start the metric handler defined in the METRICS_HANDLER environment variable. The default is null which is a no-op handler.

METRICS_HANDLER env	Description	Supports Traces	Supports Span Events	Supports Profiling
Datadog	Datadog go integration using opentracing bridge	✅	❌	✅
OTLP	OTLP Exporter protocol. Supported by various external providers including New Relic, Signoz, Grafana and more	✅	✅	❌ (but it can through pyroscope, by specifying the PYROSCOPE_ENDPOINT enviornment variable)
Jaeger	Jaeger Client Clibrary, will soon be deprecated in favor of OTLP exports to jaeger as per this deprecation notice	✅	✅	❌ (but it can through pyroscope, by specifying the PYROSCOPE_ENDPOINT enviornment variable)

Datadog:

By default the cpu and heap profile are enabled, however any profile can be enabled by passing in a comma seperated DD_PROFILES using the names here

OTLP

We do our best to support enviornment variables specified in the Otel Spec and have added a few of our own. Key ones to note are:

Jaeger

Pass in the JAEGER_ENDPOINT enviornment variable

Pyroscope

Pass in the PYROSCOPE_ENDPOINT environment variable

Documentation

Overview

Package metrics implements a metrics dashboard with either datadog or prometheus (coming soon)

Index

• Constants
• Variables
• func EndSpan(span trace.Span)
• func EndSpanWithErr(span trace.Span, err error)
• func NewNoOpExporter() metric.Exporter
• func PyroscopeWrapTracerProvider(provider trace.TracerProvider, buildInfo config.BuildInfo, ...) trace.TracerProvider
• func RPCClient(ctx context.Context, metrics Handler, url string, client *http.Client, ...) (*rpc.Client, error)
• func Setup(ctx context.Context, buildInfo config.BuildInfo) error
• func StartPyroscope(info config.BuildInfo) *pyroscope.Profiler
• type Handler
  • func Get() Handler
  • func NewByType(ctx context.Context, buildInfo config.BuildInfo, ht HandlerType) (handler Handler, err error)
  • func NewDatadogMetricsHandler(buildInfo config.BuildInfo) Handler
  • func NewFromEnv(ctx context.Context, buildInfo config.BuildInfo) (handler Handler, err error)
  • func NewJaegerHandler(buildInfo config.BuildInfo) Handler
  • func NewNullHandler() Handler
  • func NewOTLPMetricsHandler(buildInfo config.BuildInfo) Handler
• type HandlerType
  • func (i HandlerType) Lower() string
  • func (i HandlerType) String() string
• type Meter
• type MeterImpl
  • func NewOtelMeter(serviceName string, interval time.Duration, exporter sdkmetric.Exporter) (*MeterImpl, error)
  • func (m *MeterImpl) NewCounter(meterName string, counterName string, desc string, units string) (metric.Int64Counter, error)
  • func (m *MeterImpl) NewHistogram(meterName string, histName string, desc string, units string) (metric.Int64Histogram, error)
• type NullCounter
  • func (n *NullCounter) Add(_ context.Context, _ int64, _ ...metric.AddOption)
• type NullHistogram
  • func (n *NullHistogram) Record(_ context.Context, _ int64, _ ...metric.RecordOption)
• type NullMeterImpl
  • func (m *NullMeterImpl) NewCounter(_ string, _ string, _ string, _ string) (metric.Int64Counter, error)
  • func (m *NullMeterImpl) NewHistogram(_ string, _ string, _ string, _ string) (metric.Int64Histogram, error)
• type TestHandler
  • func NewTestTracer(ctx context.Context, tb testing.TB) TestHandler

Constants

const (
	// ChainID is the metric name for the chain ID.
	ChainID = "chain_id"
	// ContractAddress is the metric name for the contract address.
	ContractAddress = "contract_address"
	// Origin is the metric name for the origin chain ID.
	Origin = "origin_chain_id"
	// Destination is the metric name for the destination chain ID.
	Destination = "destination_chain_id"
	// Nonce is the metric name for the nonce.
	Nonce = "nonce"
	// TxHash is the metric name for the transaction hash.
	TxHash = "tx_hash"
	// Page is the metric name for the page.
	Page = "page"
	// Contract is the metric name for the contract.
	Contract = "contract"
	// MessageExecuted is the metric name for the message executed.
	MessageExecuted = "message_executed"
)

const DDProfileEnv = "DD_PROFILES"

DDProfileEnv is the data daog profile neviornment variable.

const HandlerEnv = "METRICS_HANDLER"

HandlerEnv is the driver to use for metrics.

Variables

var AllHandlerTypes []HandlerType

AllHandlerTypes is a list of all contract types. Since we use stringer and this is a testing library, instead of manually copying all these out we pull the names out of stringer. In order to make sure stringer is updated, we panic on any method called where the index is higher than the stringer array length.

Functions

func EndSpan

func EndSpan(span trace.Span)

EndSpan ends a span.

func EndSpanWithErr

func EndSpanWithErr(span trace.Span, err error)

EndSpanWithErr ends a span and records an error if one is present.

func NewNoOpExporter

func NewNoOpExporter() metric.Exporter

NewNoOpExporter creates a new no-op metric exporter.

func PyroscopeWrapTracerProvider

func PyroscopeWrapTracerProvider(provider trace.TracerProvider, buildInfo config.BuildInfo, extraOpts ...otelpyroscope.Option) trace.TracerProvider

PyroscopeWrapTracerProvider wraps the tracer provider with pyroscope. The traceProvider is not affected if the pyroscope endpoint is not set.

func RPCClient

func RPCClient(ctx context.Context, metrics Handler, url string, client *http.Client, opts ...otelhttp.Option) (*rpc.Client, error)

RPCClient is a wrapper around rpc.Client that adds metrics/tracing.

func Setup

func Setup(ctx context.Context, buildInfo config.BuildInfo) error

Setup sets up the global metrics handler. In general, we discourage globals but because of the ubiquitiy of global variables and the tangential nature of metrics, we allow this.

func StartPyroscope

func StartPyroscope(info config.BuildInfo) *pyroscope.Profiler

StartPyroscope starts the pyroscope profiler. this will not run if the pyroscope endpoint is not set.

Types

type Handler

type Handler interface {
	Start(ctx context.Context) error
	// Gin gets a gin middleware for tracing.
	Gin() gin.HandlerFunc
	// ConfigureHTTPClient configures tracing on an http client
	ConfigureHTTPClient(client *http.Client, opts ...otelhttp.Option)
	// AddGormCallbacks adds gorm callbacks for tracing.
	AddGormCallbacks(db *gorm.DB)
	// GetTracerProvider returns the tracer provider.
	GetTracerProvider() trace.TracerProvider
	// Tracer returns the tracer provider.
	Tracer() trace.Tracer
	// Propagator returns the propagator.
	Propagator() propagation.TextMapPropagator
	// Type returns the handler type.
	Type() HandlerType
	// Meter returns an otel meter provider
	Meter() Meter
}

Handler collects metrics.

func Get

func Get() Handler

Get gets the global handler.

func NewByType

func NewByType(ctx context.Context, buildInfo config.BuildInfo, ht HandlerType) (handler Handler, err error)

NewByType sets up a metrics handler by type.

func NewDatadogMetricsHandler

func NewDatadogMetricsHandler(buildInfo config.BuildInfo) Handler

NewDatadogMetricsHandler creates a new datadog metrics handler.

func NewFromEnv

func NewFromEnv(ctx context.Context, buildInfo config.BuildInfo) (handler Handler, err error)

NewFromEnv sets up a metrics handler from environment variable. this will not set the global and generally, SetupFromEnv should be used instead.

func NewJaegerHandler

func NewJaegerHandler(buildInfo config.BuildInfo) Handler

NewJaegerHandler creates a new jaeger handler for handling jaeger traces. the JAEGER_ENDPOINT environment variable must be set for this to work. Note: currently, this is only suitable for local runs, because of default options we've put in place This can be fixed in a future version through an option builder. TODO: this should extend the baseHandler, but we need to figure out how to do that with the jaeger exporter.

func NewNullHandler

func NewNullHandler() Handler

NewNullHandler creates a new null transaction handler.

func NewOTLPMetricsHandler

func NewOTLPMetricsHandler(buildInfo config.BuildInfo) Handler

NewOTLPMetricsHandler creates a new newrelic metrics handler.

type HandlerType

type HandlerType uint8

HandlerType is the handler type to use

const (
	// DataDog is the datadog driver.
	DataDog HandlerType = iota + 1 // Datadog
	// OTLP is the new relic driver.t.
	OTLP // OTLP
	// Jaeger is the jaeger driver.
	Jaeger // Jaeger
	// Null is a null data type handler.
	Null // Null
)

func (HandlerType) Lower

func (i HandlerType) Lower() string

Lower gets the lowercase version of the handler type. Useful for comparison in switch.

func (HandlerType) String

func (i HandlerType) String() string

type Meter

type Meter interface {
	// NewCounter creates a new meter counter instrument.
	NewCounter(meterName string, counterName string, desc string, units string) (metric.Int64Counter, error)
	// NewHistogram creates a new meter histogram instrument.
	NewHistogram(meterName string, histName string, desc string, units string) (metric.Int64Histogram, error)
}

Meter is an interface for counter and histogram.

type MeterImpl

type MeterImpl struct {
	// contains filtered or unexported fields
}

MeterImpl is an implementation of the MeterProvider interface.

func NewOtelMeter

func NewOtelMeter(serviceName string, interval time.Duration, exporter sdkmetric.Exporter) (*MeterImpl, error)

NewOtelMeter creates a new meter provider.

func (*MeterImpl) NewCounter

func (m *MeterImpl) NewCounter(meterName string, counterName string, desc string, units string) (metric.Int64Counter, error)

NewCounter creates a new meter counter instrument. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#counter

func (*MeterImpl) NewHistogram

func (m *MeterImpl) NewHistogram(meterName string, histName string, desc string, units string) (metric.Int64Histogram, error)

NewHistogram creates a new meter histogram instrument. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#histogram

type NullCounter

type NullCounter struct {
	embedded.Int64Counter
}

NullCounter is a no-op implementation of the metric.Int64Counter.

func (*NullCounter) Add

func (n *NullCounter) Add(_ context.Context, _ int64, _ ...metric.AddOption)

Add is a no-op implementation of Int64Counter Add() function.

type NullHistogram

type NullHistogram struct {
	embedded.Int64Histogram
}

NullHistogram is a no-op implementation of the metric.Int64Histogram.

func (*NullHistogram) Record

func (n *NullHistogram) Record(_ context.Context, _ int64, _ ...metric.RecordOption)

Record is a no-op implementation of RecordOption Record() function.

type NullMeterImpl

type NullMeterImpl struct{}

NullMeterImpl is a no-op implementation of the Meter interface.

func (*NullMeterImpl) NewCounter

func (m *NullMeterImpl) NewCounter(_ string, _ string, _ string, _ string) (metric.Int64Counter, error)

NewCounter creates a new meter counter instrument.

func (*NullMeterImpl) NewHistogram

func (m *NullMeterImpl) NewHistogram(_ string, _ string, _ string, _ string) (metric.Int64Histogram, error)

NewHistogram creates a new meter histogram instrument.

type TestHandler

type TestHandler interface {
	Handler
	// GetSpansByName returns all spans with the given name.
	GetSpansByName(name string) (spans []tracetest.SpanStub)
}

TestHandler is a handler that can be used for testing traces.

func NewTestTracer

func NewTestTracer(ctx context.Context, tb testing.TB) TestHandler

NewTestTracer returns a new test tracer.