otelx

Documentation

Overview

Package otelx wires OpenTelemetry tracing into a MicroJet application. It owns the global tracer provider and W3C propagator; the other MicroJet modules (httpx, gormx, messaging/nats) instrument themselves through the otel globals, so they trace automatically once a Tracing service is registered — and stay zero-overhead no-ops when it is not.

Index

• func Module(name ...string) host.Module
• type Config
• type Tracing
  • func Lookup(app *host.App, name ...string) (*Tracing, bool)
  • func New() *Tracing
  • func Of(app *host.App, name ...string) *Tracing
  • func (t *Tracing) Close() error
  • func (t *Tracing) CloseOrder() int
  • func (t *Tracing) Init() error
  • func (t *Tracing) Provider() *sdktrace.TracerProvider
  • func (t *Tracing) ReadConfig(l configx.Reader) error
  • func (t *Tracing) SetLogger(logger *slog.Logger)
  • func (t *Tracing) SetServiceInfo(name, version string)

Functions

func Module

func Module(name ...string) host.Module

Module registers the OpenTelemetry tracing service. Config is loaded from the [tracing] section (enabled by default, exporting to an OTLP/HTTP collector at localhost:4318); service name and version default to the [app] section. Once installed, the instrumented MicroJet layers — HTTP server and client, GORM, NATS — emit and propagate spans automatically; without it they remain no-ops. Pending spans are flushed on shutdown.

Tracing configures the global OpenTelemetry provider, so it is effectively a singleton; the optional name exists only for API symmetry with the other modules and to retrieve the service via otelx.Of(app, name).

Types

type Config

type Config struct {
	// Enabled turns span export on or off. When false, Init is a no-op and the
	// process keeps the default no-op tracer provider.
	Enabled bool `mapstructure:"enabled"`
	// Endpoint is the host:port of the OTLP/HTTP collector (no scheme).
	Endpoint string `mapstructure:"endpoint"`
	// Insecure sends spans over plain HTTP instead of TLS. Local collectors
	// usually listen without TLS, so this defaults to true; set it to false and
	// point Endpoint at your gateway in production.
	Insecure bool `mapstructure:"insecure"`
	// SampleRatio is the fraction of root traces to sample in [0, 1]. Child
	// spans always follow their parent's sampling decision.
	SampleRatio float64 `mapstructure:"sampleRatio"`
	// ServiceName overrides the service.name resource attribute. When empty,
	// the host fills it from [app] name.
	ServiceName string `mapstructure:"serviceName"`
	// ServiceVersion overrides the service.version resource attribute. When
	// empty, the host fills it from [app] version.
	ServiceVersion string `mapstructure:"serviceVersion"`
}

Config controls how tracing is set up, read from the [tracing] config section. The zero value plus ReadConfig defaults gives a tracer that exports to a local OTLP/HTTP collector (localhost:4318) sampling every trace.

type Tracing

type Tracing struct {
	Config Config
	// contains filtered or unexported fields
}

Tracing is the lifecycle service that configures the global OpenTelemetry tracer provider. Installed via otelx.Module (or register it yourself with host.ProvideService); the host loads its config, installs the provider during init, and flushes pending spans on shutdown.

func Lookup

func Lookup(app *host.App, name ...string) (*Tracing, bool)

Lookup returns the tracing service installed under the optional name and whether one was installed. Use it where absence is an expected, recoverable condition; prefer Of when the service must exist.

func New

func New() *Tracing

New returns a Tracing service ready to be registered with the host.

func Of

func Of(app *host.App, name ...string) *Tracing

Of returns the tracing service installed by Module under the optional name, panicking if none was installed.

func (*Tracing) Close

func (t *Tracing) Close() error

Close implements core.Closer, flushing pending spans and shutting the provider down. Bounded by shutdownTimeout so a dead collector cannot hang process exit.

func (*Tracing) CloseOrder

func (t *Tracing) CloseOrder() int

CloseOrder closes tracing late (as a backend) so spans emitted while other services shut down still have a live exporter; the final flush happens last.

func (*Tracing) Init

func (t *Tracing) Init() error

Init implements core.Initer. It builds the OTLP/HTTP exporter and tracer provider and installs them globally, together with the W3C trace-context + baggage propagator. A disabled config leaves the no-op globals untouched. The exporter does not dial the collector here; an unreachable endpoint surfaces as logged export warnings, never as a startup failure.

func (*Tracing) Provider

func (t *Tracing) Provider() *sdktrace.TracerProvider

Provider returns the installed tracer provider, or nil when tracing is disabled or Init has not run. Useful for tests and manual flushing.

func (*Tracing) ReadConfig

func (t *Tracing) ReadConfig(l configx.Reader) error

ReadConfig implements configx.Configurable, reading the [tracing] section.

func (*Tracing) SetLogger

func (t *Tracing) SetLogger(logger *slog.Logger)

SetLogger sets the logger used for setup messages and async export errors. The host calls it during WithTracing; a nil logger is ignored.

func (*Tracing) SetServiceInfo

func (t *Tracing) SetServiceInfo(name, version string)

SetServiceInfo sets the fallback service name and version used when the [tracing] section does not specify them. The host passes [app] name/version.