auto

README

OpenTelemetry Go Automatic Instrumentation

This repository provides OpenTelemetry tracing instrumentation for Go libraries using eBPF.

🚧 This project is currently work in progress.

Compatibility

OpenTelemetry Go Automatic Instrumentation is compatible with all current supported versions of the Go language.

Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release.

For versions of Go that are no longer supported upstream, this repository will stop ensuring compatibility with these versions in the following manner:

• A minor release will be made to add support for the new supported release of Go.
• The following minor release will remove compatibility testing for the oldest (now archived upstream) version of Go. This, and future, releases may include features only supported by the currently supported versions of Go.

Currently, OpenTelemetry Go Automatic Instrumentation is tested for the following environments.

OS	Go Version	Architecture
Ubuntu	1.25	amd64
Ubuntu	1.24	amd64
Ubuntu	1.23	amd64
Ubuntu	1.25	arm64
Ubuntu	1.24	arm64
Ubuntu	1.23	arm64

Automatic instrumentation should work on any Linux kernel above 4.4.

OpenTelemetry Go Automatic Instrumentation supports the arm64 architecture. However, there is no automated testing for this platform. Be sure to validate support on your own ARM based system.

Users of non-Linux operating systems can use the Docker images or create a virtual machine to compile and run OpenTelemetry Go Automatic Instrumentation.

See COMPATIBILITY.md for information about what Go packages this project provides instrumentation for.

Get started

See Getting started for setup, deployment, and configuration steps.

You can also try the Tutorial for a guide on setting up a sample Emojivoto application.

For technical and design info, see How it works.

Configuration

See the configuration documentation.

Contributing

See the contributing documentation.

License

OpenTelemetry Go Automatic Instrumentation is licensed under the terms of the Apache Software License version 2.0. See the license file for more details.

Third-party licenses and copyright notices can be found in the LICENSES directory.

Documentation

Overview

Package auto provides OpenTelemetry automatic tracing instrumentation for Go packages using eBPF.

Index

• func Version() string
• type AlwaysOffSampler
• type AlwaysOnSampler
• type ConfigProvider
• type Instrumentation
  • func NewInstrumentation(ctx context.Context, opts ...InstrumentationOption) (*Instrumentation, error)
  • func (i *Instrumentation) Close() error
  • func (i *Instrumentation) Load(ctx context.Context) error
  • func (i *Instrumentation) Run(ctx context.Context) error
• type InstrumentationConfig
• type InstrumentationLibrary
• type InstrumentationLibraryID
• type InstrumentationOption
  • func WithConfigProvider(cp ConfigProvider) InstrumentationOption
  • func WithEnv() InstrumentationOption
  • func WithHandler(h *pipeline.Handler) InstrumentationOption
  • func WithLogger(logger *slog.Logger) InstrumentationOption
  • func WithPID(pid int) InstrumentationOption
  • func WithSampler(sampler Sampler) InstrumentationOption
• type ParentBasedSampler
• type Sampler
  • func DefaultSampler() Sampler
• type TraceIDRatioSampler

Functions

func Version

func Version() string

Version is the current release version of OpenTelemetry Go auto-instrumentation in use.

Types

type AlwaysOffSampler

type AlwaysOffSampler struct{}

AlwaysOffSampler returns a Sampler that samples no traces.

type AlwaysOnSampler

type AlwaysOnSampler struct{}

AlwaysOnSampler is a Sampler that samples every trace. Be careful about using this sampler in a production application with significant traffic: a new trace will be started and exported for every request.

type ConfigProvider

type ConfigProvider interface {
	// InitialConfig returns the initial instrumentation configuration.
	InitialConfig(ctx context.Context) InstrumentationConfig
	// Watch returns a channel that receives updates to the instrumentation configuration.
	Watch() <-chan InstrumentationConfig
	// Shutdown releases any resources held by the provider.
	// It is an error to send updates after Shutdown is called.
	Shutdown(ctx context.Context) error
}

ConfigProvider provides the initial configuration and updates to the instrumentation configuration.

type Instrumentation

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

Instrumentation manages and controls all OpenTelemetry Go auto-instrumentation.

func NewInstrumentation

func NewInstrumentation(
	ctx context.Context,
	opts ...InstrumentationOption,
) (*Instrumentation, error)

NewInstrumentation returns a new Instrumentation configured with the provided opts.

If conflicting or duplicate options are provided, the last one will have precedence and be used.

func (*Instrumentation) Close

func (i *Instrumentation) Close() error

Close closes the Instrumentation, cleaning up all used resources.

func (*Instrumentation) Load

func (i *Instrumentation) Load(ctx context.Context) error

Load loads and attaches the relevant probes to the target process.

func (*Instrumentation) Run

func (i *Instrumentation) Run(ctx context.Context) error

Run starts the instrumentation. It must be called after Instrumentation.Load.

This function will not return until either ctx is done, an unrecoverable error is encountered, or Close is called.

type InstrumentationConfig

type InstrumentationConfig struct {
	// InstrumentationLibraryConfigs defines library-specific configuration.
	// If a package is referenced by more than one key, the most specific key is used.
	// For example, if ("net/http", unspecified) and ("net/http", client) are both present,
	// the configuration for ("net/http", client) is used for client spans and the configuration for ("net/http", unspecified) is used for server spans.
	InstrumentationLibraryConfigs map[InstrumentationLibraryID]InstrumentationLibrary

	// DefaultTracesDisabled determines whether traces are disabled by default.
	// If set to true, traces are disabled by default for all libraries, unless the library is explicitly enabled.
	// If set to false, traces are enabled by default for all libraries, unless the library is explicitly disabled.
	// default is false - traces are enabled by default.
	DefaultTracesDisabled bool

	// Sampler is used to determine whether a trace should be sampled and exported.
	Sampler Sampler
}

InstrumentationConfig is used to configure instrumentation.

type InstrumentationLibrary

type InstrumentationLibrary struct {
	// TracesEnabled determines whether traces are enabled for the instrumentation library.
	// if nil - take DefaultTracesDisabled value.
	TracesEnabled *bool
}

InstrumentationLibrary is used to configure instrumentation for a specific library.

type InstrumentationLibraryID

type InstrumentationLibraryID struct {
	// Name of the instrumentation pkg (e.g. "net/http").
	InstrumentedPkg string
	// SpanKind is the relevant span kind for the instrumentation.
	// This can be used to configure server-only, client-only spans.
	// If not set, the identifier is assumed to be applicable to all span kinds relevant to the instrumented package.
	SpanKind trace.SpanKind
}

InstrumentationLibraryID is used to identify an instrumentation library.

type InstrumentationOption

type InstrumentationOption interface {
	// contains filtered or unexported methods
}

InstrumentationOption applies a configuration option to Instrumentation.

func WithConfigProvider

func WithConfigProvider(cp ConfigProvider) InstrumentationOption

WithConfigProvider returns an InstrumentationOption that will configure an Instrumentation to use the provided ConfigProvider. The ConfigProvider is used to provide the initial configuration and update the configuration of the instrumentation in runtime.

func WithEnv

func WithEnv() InstrumentationOption

WithEnv returns an InstrumentationOption that will configure Instrumentation using the values defined by the following environment variables:

• OTEL_LOG_LEVEL: sets the default logger's minimum logging level
• OTEL_TRACES_SAMPLER: sets the trace sampler
• OTEL_TRACES_SAMPLER_ARG: optionally sets the trace sampler argument

This option may conflict with WithSampler if their respective environment variable is defined. If more than one of these options are used, the last one provided to an Instrumentation will be used.

If WithLogger is used, OTEL_LOG_LEVEL will not be used for the Instrumentation logger. Instead, the slog.Logger passed to that option will be used as-is.

If WithLogger is not used, OTEL_LOG_LEVEL will be parsed and the default logger used by the configured Instrumentation will use that level as its minimum logging level.

func WithHandler

func WithHandler(h *pipeline.Handler) InstrumentationOption

WithHandler returns an InstrumentationOption that will configure an Instrumentation to use h to handle generated telemetry.

If this options is not used, the Handler returned from otelsdk.NewHandler with environment configuration will be used.

func WithLogger

func WithLogger(logger *slog.Logger) InstrumentationOption

WithLogger returns an InstrumentationOption that will configure an Instrumentation to use the provided logger.

If this option is used and WithEnv is also used, OTEL_LOG_LEVEL is ignored by the configured Instrumentation. This passed logger takes precedence and is used as-is.

If this option is not used, the Instrumentation will use an slog.Loogger backed by an slog.JSONHandler outputting to STDERR as a default.

func WithPID

func WithPID(pid int) InstrumentationOption

WithPID returns an InstrumentationOption defining the target binary for Instrumentation that is being run with the provided PID.

If multiple of these options are provided to an Instrumentation, the last one will be used.

func WithSampler

func WithSampler(sampler Sampler) InstrumentationOption

WithSampler returns an InstrumentationOption that will configure an Instrumentation to use the provided sampler to sample OpenTelemetry traces.

This currently is a no-op. It is expected to take effect in the next release.

type ParentBasedSampler

type ParentBasedSampler struct {
	// Root is the Sampler used when a span is created without a parent.
	Root Sampler
	// RemoteSampled is the Sampler used when the span parent is remote and sampled.
	RemoteSampled Sampler
	// RemoteNotSampled is the Sampler used when the span parent is remote and not sampled.
	RemoteNotSampled Sampler
	// LocalSampled is the Sampler used when the span parent is local and sampled.
	LocalSampled Sampler
	// LocalNotSampled is the Sampler used when the span parent is local and not sampled.
	LocalNotSampled Sampler
}

ParentBasedSampler is a Sampler which behaves differently, based on the parent of the span. If the span has no parent, the Root sampler is used to make sampling decision. If the span has a parent, depending on whether the parent is remote and whether it is sampled, one of the following samplers will apply:

• RemoteSampled (default: [AlwaysOn])
• RemoteNotSampled (default: [AlwaysOff])
• LocalSampled (default: [AlwaysOn])
• LocalNotSampled (default: [AlwaysOff])

type Sampler

type Sampler interface {
	// contains filtered or unexported methods
}

Sampler decides whether a trace should be sampled and exported.

func DefaultSampler

func DefaultSampler() Sampler

DefaultSampler returns a ParentBased sampler with the following defaults:

• Root: AlwaysOn
• RemoteSampled: AlwaysOn
• RemoteNotSampled: AlwaysOff
• LocalSampled: AlwaysOn
• LocalNotSampled: AlwaysOff

type TraceIDRatioSampler

type TraceIDRatioSampler struct {
	// Fraction is the fraction of traces to sample. This value needs to be in the interval [0, 1].
	Fraction float64
}

TraceIDRatioSampler samples a given fraction of traces. Fraction should be in the closed interval [0, 1]. To respect the parent trace's SampledFlag, the TraceIDRatioSampler sampler should be used as a delegate of a [ParentBased] sampler.