telemetry

README

telemetry

Common library for any Go code that wants to interface with telemetry.

telemetry expects everything to be configured via default otel environment variables to maximize portability and flexibility.

To modify the sample rate and sampling strategy, for example, you can use:

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.001

See https://opentelemetry-python.readthedocs.io/en/latest/sdk/trace.sampling.html

Setup

telemetry is designed to minimize the boilerplate needed to get up and running quickly. To enable it, you simply add the following:

ctx := context.Background()
closeFunc := telemetry.EnableOTELTracing(ctx)
defer func() { _ = closeFunc(ctx) }()

From that point on, tracing is configured for you, and you can use it as normal. For example, you can run:

tracer := otel.Tracer("my-tracer")

Sampling

This library also contains convenience functions for forcing certain traces to be sampled. For example, to always sample HTTP requests with a specific HTTP header and value, you can run:

telemetry.AlwaysSampleHeaderHandler("name", "value", otelhttp.NewHandler(...)))

If the value is "*", then it will always sample requests that have the header set to any value.

telemetry includes this ability to force traces to be sampled more generally, though. If you want to force a trace to be sampled, you can call the following to add forced sampling to its context:

ctx := telemetry.AlwaysSample(r.Context())

That should be done for the root span.

Documentation

Index

• func AlwaysSample(ctx context.Context) context.Context
• func AlwaysSampleHeaderHandler(header string, value string, handler http.Handler) http.Handler
• func EnableOTELMetrics(ctx context.Context) func(context.Context) error
• func EnableOTELTracing(ctx context.Context) func(context.Context) error
• func ForceableSampler(wrapped sdktrace.Sampler) sdktrace.Sampler
• func NewHandler(handler http.Handler, filters ...ForceSampleFilter) http.Handler
• type ForceSampleFilter
  • func AlwaysSampleHTTPHeader(header string, value string) ForceSampleFilter

Functions

func AlwaysSample

func AlwaysSample(ctx context.Context) context.Context

AlwaysSample returns a context that will always be sampled by the sampler.

func AlwaysSampleHeaderHandler

func AlwaysSampleHeaderHandler(header string, value string, handler http.Handler) http.Handler

AlwaysSampleHeaderHandler wraps the passed handler and always samples requests that have the specified header set to the specified value.

func EnableOTELMetrics

func EnableOTELMetrics(ctx context.Context) func(context.Context) error

EnableOTELMetrics enables OTEL metrics, configuring the OTEL provider using environment variables.

func EnableOTELTracing

func EnableOTELTracing(ctx context.Context) func(context.Context) error

Sample rates should be configured via environment variables. See https://opentelemetry-python.readthedocs.io/en/latest/sdk/trace.sampling.html For example: OTEL_TRACES_SAMPLER=traceidratio OTEL_TRACES_SAMPLER_ARG=0.001

func ForceableSampler

func ForceableSampler(wrapped sdktrace.Sampler) sdktrace.Sampler

ForceableSampler returns a Sampler that uses the sampler from the environment but that checks the parent context for a special key that overrides the sampler to always sample.

func NewHandler

func NewHandler(handler http.Handler, filters ...ForceSampleFilter) http.Handler

NewHandler wraps the passed handler and allows callers to set rules for things that should always be sampled.

Types

type ForceSampleFilter

type ForceSampleFilter interface {
	ForceSample(r *http.Request) bool
}

func AlwaysSampleHTTPHeader

func AlwaysSampleHTTPHeader(header string, value string) ForceSampleFilter

AlwaysSampleHTTPHeader returns a ForceSampleFilter that will always sample requests that have the specified header set to the specified value. If the value is "*", then it will always sample requests that have the header set to any value.