telemetry

README

Telemetry

Tracing

You can use this package to enable tracing in your project. The current implementation was designed using OpenTelemetry and Jaeger.

Quickstart

Configuration

// Embed telemetry.TracingConfig to your configuration struct
type MyAwesomeProject struct {
    Tracing telemetry.TracingConfig
}

// Or use telemetry.ParseTracingConfig()
cfg, err := telemetry.ParseTracingConfig()
if err != nil {
    // Handle error
}

Initialize tracing components

// Using the config parsed in the previous step:
propagator, tracerProvider, err := telemetry.InitializeTracing(cfg)
if err != nil {
    // Handle error
}

HTTP

In order to use tracing for your HTTP endpoints, you can wrap the given endpoint with tracing:

endpoint = telemetry.WrapHandlerHTTP(endpoint, "http.CreateUser", propagator, tracerProvider)

NOTE: As it is right now, each endpoint needs to be wrapped independently. Support for HTTP routers will be added in future iterations.

gRPC

Client

// Initialize interceptors to add to your gRPC client:
unaryInterceptor, streamInterceptor := telemetry.NewClientInterceptor(propagator, tracerProvider)

Server

// We can also add interceptors to our gRPC server:
unaryInterceptor, streamInterceptor := telemetry.NewServerInterceptor(propagator, tracerProvider)

This package also includes some helper functions to make you tracing initialization easier when adding middlewares to your gRPC servers and clients.

Documentation

Index

• func AppendDialOptions(opts []grpc.DialOption, propagator propagation.TextMapPropagator, ...) []grpc.DialOption
• func AppendServerOptions(opts []grpc.ServerOption, propagator propagation.TextMapPropagator, ...) []grpc.ServerOption
• func InitializeTracing(cfg TracingConfig) (propagation.TextMapPropagator, trace.TracerProvider, error)
• func NewChildSpan(ctx context.Context, name string) (context.Context, trace.Span)
• func NewClientStatsHandler(p propagation.TextMapPropagator, tp trace.TracerProvider) grpc.DialOption
• func NewJaegerPropagator() jaegerPropagator.Jaeger
• func NewServerStatsHandler(p propagation.TextMapPropagator, tp trace.TracerProvider) grpc.ServerOption
• func NewSpan(ctx context.Context) trace.Span
• func NewTracerProviderCollector(service, url, environment string) (trace.TracerProvider, error)
• func WrapHandlerHTTP(handler http.Handler, spanName string, ...) http.Handler
• type TestSpan
  • func NewTestSpan() *TestSpan
  • func (t *TestSpan) AddEvent(name string, options ...trace.EventOption)
  • func (t *TestSpan) End(options ...trace.SpanEndOption)
  • func (t *TestSpan) IsRecording() bool
  • func (t *TestSpan) RecordError(err error, options ...trace.EventOption)
  • func (t *TestSpan) SetAttributes(kv ...attribute.KeyValue)
  • func (t *TestSpan) SetName(name string)
  • func (t *TestSpan) SetStatus(code codes.Code, description string)
  • func (t *TestSpan) SpanContext() trace.SpanContext
  • func (t *TestSpan) TracerProvider() trace.TracerProvider
• type TracingConfig
  • func ParseTracingConfig() (TracingConfig, error)

Functions

func AppendDialOptions

func AppendDialOptions(opts []grpc.DialOption, propagator propagation.TextMapPropagator, tracerProvider trace.TracerProvider) []grpc.DialOption

AppendDialOptions appends dial options using the given propagator and tracer provider. If either propagator or tracerProvider are nil, this function returns the given opts as they were provided.

func AppendServerOptions

func AppendServerOptions(opts []grpc.ServerOption, propagator propagation.TextMapPropagator, tracerProvider trace.TracerProvider) []grpc.ServerOption

AppendServerOptions appends server options using the given propagator and tracer provider. If either propagator or tracerProvider are nil, this function returns the given opts as they were provided.

func InitializeTracing

func InitializeTracing(cfg TracingConfig) (propagation.TextMapPropagator, trace.TracerProvider, error)

InitializeTracing initializes the components used for exporting traces in a project using the config defined by TracingConfig. If TracingConfig.Enabled is set to false, it returns nil values.

func NewChildSpan

func NewChildSpan(ctx context.Context, name string) (context.Context, trace.Span)

NewChildSpan initializes a new child span.

func NewClientStatsHandler

func NewClientStatsHandler(p propagation.TextMapPropagator, tp trace.TracerProvider) grpc.DialOption

NewClientStatsHandler initializes a new dial option for gRPC using the given propagator and tracer provider.

func NewJaegerPropagator

func NewJaegerPropagator() jaegerPropagator.Jaeger

NewJaegerPropagator initializes a new Open Telemetry traces propagator for Jaeger. The propagator serializes and deserializes Jaeger headers to/from a context.Context.

func NewServerStatsHandler

func NewServerStatsHandler(p propagation.TextMapPropagator, tp trace.TracerProvider) grpc.ServerOption

NewServerStatsHandler initializes a new server option using the given propagator and tracer provider.

func NewSpan

func NewSpan(ctx context.Context) trace.Span

NewSpan initializes a new span from the given context. Span is the individual component of a trace. It represents a single named and timed operation of a workflow that is traced. A Tracer is used to create a Span, and it is then up to the operation the Span represents to properly end the Span when the operation itself ends. If no Span is currently set in ctx a NoOp span is returned instead.

func NewTracerProviderCollector

func NewTracerProviderCollector(service, url, environment string) (trace.TracerProvider, error)

NewTracerProviderCollector initializes a new Open Telemetry tracer provider using a Jaeger Collector.

service: Describes the service that will be exporting traces. Usually contains the service name.
url: Contains the endpoint where to publish traces to.
environment: Used to identify the environment that a certain service is publishing traces from. Defaults to "development".

func WrapHandlerHTTP

func WrapHandlerHTTP(handler http.Handler, spanName string, propagator propagation.TextMapPropagator, provider trace.TracerProvider) http.Handler

WrapHandlerHTTP wraps the given handler with OpenTelemetry interceptors for HTTP endpoints. It returns the original handler if propagator or provider are nil.

Types

type TestSpan

type TestSpan struct {
	mock.Mock
	noop.Span
}

TestSpan is a trace.Span used for testing.

func NewTestSpan

func NewTestSpan() *TestSpan

NewTestSpan initializes a new span used for testing purposes.

func (*TestSpan) AddEvent

func (t *TestSpan) AddEvent(name string, options ...trace.EventOption)

AddEvent mocks the AddEvent method.

func (*TestSpan) End

func (t *TestSpan) End(options ...trace.SpanEndOption)

End mocks the End method.

func (*TestSpan) IsRecording

func (t *TestSpan) IsRecording() bool

IsRecording mocks the IsRecording method.

func (*TestSpan) RecordError

func (t *TestSpan) RecordError(err error, options ...trace.EventOption)

RecordError mocks the RecordError method.

func (*TestSpan) SetAttributes

func (t *TestSpan) SetAttributes(kv ...attribute.KeyValue)

SetAttributes mocks the SetAttributes method.

func (*TestSpan) SetName

func (t *TestSpan) SetName(name string)

SetName mocks the SetName method.

func (*TestSpan) SetStatus

func (t *TestSpan) SetStatus(code codes.Code, description string)

SetStatus mocks the SetStatus method.

func (*TestSpan) SpanContext

func (t *TestSpan) SpanContext() trace.SpanContext

SpanContext mocks the SpanContext method.

func (*TestSpan) TracerProvider

func (t *TestSpan) TracerProvider() trace.TracerProvider

TracerProvider mocks the TracerProvider method.

type TracingConfig

type TracingConfig struct {
	// Service contains the service name that will be used when generating traces. It's usually the name of the service
	// that's using this library.
	Service string `env:"SERVICE,notEmpty"`

	// Environment defines the environment being traced. Defaults to staging.
	Environment string `env:"ENVIRONMENT" envDefault:"development"`

	// Enabled defines if tracing should be enabled.
	Enabled bool `env:"ENABLED" envDefault:"false"`

	// Deprecated: ExportingStrategy contains the name of the strategy used to export traces. Defaults to collector.
	// Possible values: collector, agent.
	// This field was deprecated since the agent strategy is no longer supported
	// after upgrading a newer Open Telemetry SDK version.
	ExportingStrategy string `env:"EXPORTING_STRATEGY" envDefault:"collector"`

	// CollectorURL defines the URL traces should be sent to. If Enabled is true, this value
	// must be set.
	CollectorURL string `env:"COLLECTOR_URL" envDefault:"http://localhost:14268/api/traces"`

	// Deprecated: AgentHost defines the address this service should send traces to. If Enabled is true, this value
	// must be set.
	// This field was deprecated since the agent strategy is no longer supported
	// after upgrading a newer Open Telemetry SDK version.
	// Use CollectorURL instead.
	AgentHost string `env:"AGENT_HOST" envDefault:"localhost"`

	// Deprecated: AgentPort defines the port used alongside AgentHost. If Enabled is true, this value must be set.
	// This field was deprecated since the agent strategy is no longer supported
	// after upgrading a newer Open Telemetry SDK version.
	// Use CollectorURL instead.
	AgentPort string `env:"AGENT_PORT" envDefault:"6831"`
}

TracingConfig defines configuration values to customize how Tracing is initialized for different services.

func ParseTracingConfig

func ParseTracingConfig() (TracingConfig, error)

ParseTracingConfig parses TracingConfig from environment variables. All the environment variables specified in TracingConfig are prepend with the TRACING_ prefix.