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 AppendServerInterceptors(unaries []grpc.UnaryServerInterceptor, streams []grpc.StreamServerInterceptor, ...) ([]grpc.UnaryServerInterceptor, []grpc.StreamServerInterceptor)
• func InitializeTracing(cfg TracingConfig) (propagation.TextMapPropagator, trace.TracerProvider, error)
• func NewChildSpan(ctx context.Context, name string) (context.Context, trace.Span)
• func NewClientInterceptor(p propagation.TextMapPropagator, tp trace.TracerProvider) (grpc.UnaryClientInterceptor, grpc.StreamClientInterceptor)
• func NewJaegerPropagator() jaegerPropagator.Jaeger
• func NewJaegerTracerProviderAgent(service, host, port, environment string) (trace.TracerProvider, error)
• func NewJaegerTracerProviderCollector(service, url, environment string) (trace.TracerProvider, error)
• func NewServerInterceptor(p propagation.TextMapPropagator, tp trace.TracerProvider) (grpc.UnaryServerInterceptor, grpc.StreamServerInterceptor)
• func NewSpan(ctx context.Context) trace.Span
• 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 unary and stream interceptors 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 AppendServerInterceptors

func AppendServerInterceptors(unaries []grpc.UnaryServerInterceptor, streams []grpc.StreamServerInterceptor,
	p propagation.TextMapPropagator, tp trace.TracerProvider) ([]grpc.UnaryServerInterceptor, []grpc.StreamServerInterceptor)

AppendServerInterceptors appends unary and stream interceptors using the given propagator and tracer provider. If either propagator or tracerProvider are nil, this function returns the given streams and unaries 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 NewClientInterceptor

func NewClientInterceptor(p propagation.TextMapPropagator, tp trace.TracerProvider) (grpc.UnaryClientInterceptor, grpc.StreamClientInterceptor)

NewClientInterceptor initializes a new client interceptor 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 NewJaegerTracerProviderAgent

func NewJaegerTracerProviderAgent(service, host, port, environment string) (trace.TracerProvider, error)

NewJaegerTracerProviderAgent initializes a new Open Telemetry tracer provider for Jaeger using a Jaeger Agent.

service: Describes the service that will be exporting traces into Jaeger. Usually contains the service name.
host: Contains the address where to publish traces to. For Jaeger, it's the agent's endpoint.
port: Contains the port used alongside host to publish traces to. For Jaeger, it's the agent's port.
environment: Used to identify the environment that a certain service is publishing traces from. Defaults to "development".

func NewJaegerTracerProviderCollector

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

NewJaegerTracerProviderCollector initializes a new Open Telemetry tracer provider for Jaeger using a Jaeger Collector.

service: Describes the service that will be exporting traces into Jaeger. Usually contains the service name.
url: Contains the endpoint where to publish traces to. For Jaeger, it's the collector's endpoint.
environment: Used to identify the environment that a certain service is publishing traces from. Defaults to "development".

func NewServerInterceptor

func NewServerInterceptor(p propagation.TextMapPropagator, tp trace.TracerProvider) (grpc.UnaryServerInterceptor, grpc.StreamServerInterceptor)

NewServerInterceptor initializes a new server interceptor for gRPC 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 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
}

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"`

	// ExportingStrategy contains the name of the strategy used to export traces. Defaults to collector.
	// Possible values: collector, agent.
	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"`

	// AgentHost defines the address this service should send traces to. If Enabled is true, this value
	// must be set.
	AgentHost string `env:"AGENT_HOST" envDefault:"localhost"`

	// AgentPort defines the port used alongside AgentHost. If Enabled is true, this value must be set.
	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.