otel

README

barney.ci/go-otel

This repo contains OpenTelemetry-related code.

OtelSetup

OtelSetup provides boilerplate, slightly Arista-optimized production of Otel TracerProviders.

Typical applications require some environment. Kubernetes example:

kind: Deployment
spec:
  template:
    spec:
      containers:
        env:
        - name: OTEL_SDK_DISABLED
          value: "false"
        - name: OTEL_EXPORTER_OTLP_INSECURE
          value: "true"
        - name: HOST_IP
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: "http://$(HOST_IP):4317"
        - name: OTEL_REMOTE_SAMPLING_URL
          value: "http://$(HOST_IP):5778/sampling"

The old envs OTEL_EXPORTER_JAEGER_AGENT_HOST, OTEL_SAMPLER_JAEGER_CONFIG_URL_TEMPLATE, and JAEGER_ENABLED are no longer used. The grpc otel exporter can be configured through the standard envs described https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc#pkg-overview

EnvironCarrier

EnvironCarrier provides a TextMapCarrier interface to the process environment.

UberTraceContext

UberTraceContext is a propagator that supports the "Jaeger native propagation format", better known as the "uber-trace-id" header.

Documentation

Index

• Constants
• func ContextWithEnvPropagation(parent context.Context) context.Context
• func MapCarrierAsEnviron(mc propagation.MapCarrier) []string
• func NewKafkaCarrier(hdrs []kafka.Header) *kafkaCarrier
• func OtelSetup(ctx context.Context, name string, with ...setupOptionFunc) (tp *trace.TracerProvider, closer closerFunc, err error)
• func WithEnvGate() setupOptionFunc
• func WithGeneralPropagatorSetup() setupOptionFunc
• func WithLogger(logger *slog.Logger) setupOptionFunc
• func WithOtlpExporter() setupOptionFunc
• func WithRemoteSampler() setupOptionFunc
• func WithSampler(s trace.Sampler) setupOptionFunc
• func WithShutdownTimeout(t time.Duration) setupOptionFunc
• type EnvironCarrier
  • func (e EnvironCarrier) Get(key string) string
  • func (e EnvironCarrier) Keys() []string
  • func (e EnvironCarrier) Set(key string, value string)
• type UberTraceContext
  • func (tc UberTraceContext) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
  • func (tc UberTraceContext) Fields() []string
  • func (tc UberTraceContext) Inject(ctx context.Context, carrier propagation.TextMapCarrier)

Constants

const EnvGateCue = "true"

const EnvGateName = "OTEL_SDK_DISABLED"

These envs are standard. See: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/ https://opentelemetry.io/docs/specs/otel/protocol/exporter/

const EnvSamplingUrl = "OTEL_REMOTE_SAMPLING_URL"

const EnvironCarrierPrefix = "OTELTEXTMAP_" // exactly 1 underscore, trailing

EnvironCarrierPrefix defines the prefix we attach to carrier key names to store them in the process environment.

Functions

func ContextWithEnvPropagation

func ContextWithEnvPropagation(parent context.Context) context.Context

ContextWithEnvPropagation returns a copy of a parent Context with trace context propagation from the process environment.

func MapCarrierAsEnviron

func MapCarrierAsEnviron(mc propagation.MapCarrier) []string

MapCarrierAsEnviron returns the contents of a MapCarrier as a slice of "key=value" strings, suitable for e.g. os.exec.Cmd.Env

func NewKafkaCarrier

func NewKafkaCarrier(hdrs []kafka.Header) *kafkaCarrier

func OtelSetup

func OtelSetup(ctx context.Context, name string, with ...setupOptionFunc) (
	tp *trace.TracerProvider, closer closerFunc, err error,
)

OtelSetup returns a otel TracerProvider and a closer function to shut down the provider.

Options order can be important. For example, WithRemoteSampler sets the sampler to one that falls back to any existing sampler, whilst WithSampler sets the sampler to the passed argument and overwrites the existing sampler.

It's a good idea to pass WithLogger first, so errors raised by subsequent options will be sent to that callback.

func WithEnvGate

func WithEnvGate() setupOptionFunc

WithEnvGate causes a call to OtelSetup to be a no-op if the environment variable defined by EnvGatename is set to the value defined by EnvGateCue

func WithGeneralPropagatorSetup

func WithGeneralPropagatorSetup() setupOptionFunc

WithGeneralPropagatorSetup causes OtelSetup to configure the default propagator with some basic propagators

func WithLogger

func WithLogger(logger *slog.Logger) setupOptionFunc

WithLogger configures the given logger to be used for printing errors or info at runtime emitted by the tracer implementation. If unset, a default value of slog.Default() will be used.

func WithOtlpExporter

func WithOtlpExporter() setupOptionFunc

WithOtlpExporter causes OtelSetup to configure an exporter targeting the exporter otlp endpoint

func WithRemoteSampler

func WithRemoteSampler() setupOptionFunc

WithRemoteSampler causes OtelSetup to be configured with a remote sampler URL constructed using the environment variable defined by EnvSamplingUrl, falling back to any previously configured sampler

func WithSampler

func WithSampler(s trace.Sampler) setupOptionFunc

WithSampler causes OtelSetup to configure otel with the provided sampler only

func WithShutdownTimeout

func WithShutdownTimeout(t time.Duration) setupOptionFunc

WithShutdownTimeout limits the amount of time that the close function returned by OtelSetup may wait

Types

type EnvironCarrier

type EnvironCarrier struct{}

EnvironCarrier provides a TextMapCarrier interface to the process environment.

func (EnvironCarrier) Get

func (e EnvironCarrier) Get(key string) string

func (EnvironCarrier) Keys

func (e EnvironCarrier) Keys() []string

func (EnvironCarrier) Set

func (e EnvironCarrier) Set(key string, value string)

type UberTraceContext

type UberTraceContext struct{}

UberTraceContext is a propagator that supports the "Jaeger native propagation format", better known as the "uber-trace-id" header. See: https://www.jaegertracing.io/docs/1.40/client-libraries/#propagation-format

UberTraceContext will propagate the uber-trace-id header to guarantee traces employing this type of header are not broken. It is up to the users of this propagator to choose if they want to participate in a trace by modifying the uber-trace-id header and relevant parts of the uber-trace-id header containing their proprietary information.

UberTraceContext operates on the came principle as the upstream TraceContext propagator, which injects and extracts the "W3C trace context format", better known as the "traceparent" header.

When a CompositeTextMapPropagator combines TraceContext and UberTraceContext propagators, SpanContexts will be propagated forward as both types of header, and both inbound header types will be extractable into a local SpanContext (with the later-defined propagator's header taking overriding precedence).

func (UberTraceContext) Extract

func (tc UberTraceContext) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context

Extract reads uber-trace-id from the carrier into a returned Context.

The returned Context will be a copy of ctx and contain the extracted uber-trace-id as the remote SpanContext. If the extracted uber-trace-id is invalid, the passed ctx will be returned directly instead.

func (UberTraceContext) Fields

func (tc UberTraceContext) Fields() []string

Fields returns the keys whose values are set with Inject.

func (UberTraceContext) Inject

func (tc UberTraceContext) Inject(ctx context.Context, carrier propagation.TextMapCarrier)

Inject sets uber-trace-id from the Context into the carrier.