telemetry

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package telemetry wires OpenTelemetry traces and metrics, and log/slog.

The provider is a value. It sets no global provider, because design rule 1 forbids global mutable state. The application passes it to each subsystem that produces a span.

The default exporter is none. With every exporter off, the HTTP middleware returns the handler that it received, so a request costs no extra allocation. See the SDD, S3.

Index

Constants

View Source
const (
	// ExporterNone produces no telemetry. It is the default.
	ExporterNone = "none"
	// ExporterOTLP sends to a collector over OTLP.
	ExporterOTLP = "otlp"
)

The exporter names that OTEL_TRACES_EXPORTER and OTEL_METRICS_EXPORTER take.

View Source
const ProtocolHTTP = "http/protobuf"

ProtocolHTTP is the only OTLP protocol that Avero ships.

The gRPC exporter is a module that the SDD does not name, so Avero does not import it. google.golang.org/grpc still reaches the build through go.opentelemetry.io/proto/otlp, which the OTLP HTTP exporters use for their message types. Avero opens no gRPC connection.

Variables

This section is empty.

Functions

func Attr

func Attr(key string, value any) attribute.KeyValue

Attr builds a span attribute. A config.Secret reads as ******** and never reaches an exporter. See the SDD, S1 and S3.

Types

type Fault

type Fault struct {
	// Variable is the environment variable at fault.
	Variable string `json:"variable"`
	// Message states the fault.
	Message string `json:"message"`
	// Repair states what to do. It is one sentence.
	Repair string `json:"repair"`
	// Err is the cause. It can be nil.
	Err error `json:"-"`
}

Fault is one telemetry fault. It names the environment variable, states what went wrong, and states the repair in one sentence. See DX-7.

func (*Fault) Error

func (f *Fault) Error() string

Error returns the message and the repair on two lines.

func (*Fault) Unwrap

func (f *Fault) Unwrap() error

Unwrap returns the cause.

type Option

type Option func(*options)

Option configures a provider.

func WithLogWriter

func WithLogWriter(w io.Writer) Option

WithLogWriter sends the log to w. The default is standard error.

func WithMeterProvider

func WithMeterProvider(mp metric.MeterProvider) Option

WithMeterProvider supplies the meter provider. It replaces the exporter that the configuration names.

func WithTracerProvider

func WithTracerProvider(tp trace.TracerProvider) Option

WithTracerProvider supplies the tracer provider. A test passes one that keeps every span in memory. It replaces the exporter that the configuration names.

type Provider

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

Provider holds the tracer, the meter and the logger of one application. Build it with New and register it as a component, so that Stop flushes the exporters inside SHUTDOWN_GRACE.

func New

func New(cfg config.BaseConfig, opts ...Option) (*Provider, error)

New builds a provider from the OTEL_* variables of the configuration.

func (*Provider) DrelOption

func (p *Provider) DrelOption() drel.Option

DrelOption returns the engine option that installs the tracer.

engine, err := drel.NewEngine(cfg.DatabaseURL, telemetry.DrelOption())

func (*Provider) DrelTracer

func (p *Provider) DrelTracer() drel.Tracer

DrelTracer returns the tracer that drel uses. It returns nil when the exporter is off, and drel then produces no span.

func (*Provider) HTTPMiddleware

func (p *Provider) HTTPMiddleware() router.Middleware

HTTPMiddleware fills the trace slot of the middleware chain. It starts one server span for each request and records the duration.

With every exporter off it returns the handler that it received. The chain then holds no wrapper, so a request costs no extra call and no extra allocation. See the SDD, S3.

The span carries the route pattern and never the raw path, the query, a header or a cookie. A secret in a URL or in a header therefore never reaches an exporter.

func (*Provider) Logger

func (p *Provider) Logger() *slog.Logger

Logger returns the logger. Every record inside a request carries the trace ID, the span ID and the request ID.

func (*Provider) Meter

func (p *Provider) Meter() metric.Meter

Meter returns the meter. It is a no-op meter when the exporter is none.

func (*Provider) MetricsEnabled

func (p *Provider) MetricsEnabled() bool

MetricsEnabled reports whether a measurement reaches an exporter.

func (*Provider) Name

func (p *Provider) Name() string

Name identifies the component. See the SDD, section 5.1.

func (*Provider) Start

func (p *Provider) Start(context.Context) error

Start does nothing. New builds the exporters, so a fault appears before the process starts. See DX-8.

func (*Provider) StartClient

func (p *Provider) StartClient(ctx context.Context, name string,
	attrs ...attribute.KeyValue,
) (context.Context, trace.Span)

StartClient begins a span for a call to another service. A generated client calls it. See the SDD, S13.

func (*Provider) StartConsumer

func (p *Provider) StartConsumer(ctx context.Context, name string,
	attrs ...attribute.KeyValue,
) (context.Context, trace.Span)

StartConsumer begins a span for a message that the application handles. The inbox consumer calls it. See the SDD, S8.

func (*Provider) StartInternal

func (p *Provider) StartInternal(ctx context.Context, name string,
	attrs ...attribute.KeyValue,
) (context.Context, trace.Span)

StartInternal begins a span for work inside the application, such as a projection.

func (*Provider) StartProducer

func (p *Provider) StartProducer(ctx context.Context, name string,
	attrs ...attribute.KeyValue,
) (context.Context, trace.Span)

StartProducer begins a span for a message that the application publishes. The outbox relay calls it. See the SDD, S7.

func (*Provider) Stop

func (p *Provider) Stop(ctx context.Context) error

Stop flushes the exporters. The context carries the SHUTDOWN_GRACE deadline. It is safe to call more than one time.

func (*Provider) Tracer

func (p *Provider) Tracer() trace.Tracer

Tracer returns the tracer. It is a no-op tracer when the exporter is none.

func (*Provider) TracesEnabled

func (p *Provider) TracesEnabled() bool

TracesEnabled reports whether a span reaches an exporter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL