telemetry

Documentation

Index

• Constants
• func NewLockedWriter(w io.Writer) io.Writer
• func SanitizeDiagnostic(value string) string
• func Start(ctx context.Context, cfg Config) (context.Context, *sdktrace.TracerProvider, error)
• type Config

Constants

const DefaultShutdownBudget = 2 * time.Second

DefaultShutdownBudget is the canonical timeout for telemetry shutdown and synchronous exporter attempts. It is the single source of truth for the budget; the public ax package derives its default from this value.

Functions

func NewLockedWriter

func NewLockedWriter(w io.Writer) io.Writer

NewLockedWriter returns an io.Writer that serializes all writes to w with a mutex. It is used at two intentional layers of defense-in-depth: Execute (ax package) wraps cfg.stderr before any goroutine touches it, and Start wraps the same writer again for the specific inner path taken by the stdouttrace debug exporter. Each layer cannot assume the other synchronizes its writes.

func SanitizeDiagnostic

func SanitizeDiagnostic(value string) string

SanitizeDiagnostic replaces ASCII control characters (< 0x20 and DEL 0x7f) with spaces, preventing log-forging via newline injection or ANSI escapes in error messages that are written to stderr diagnostics.

func Start

func Start(ctx context.Context, cfg Config) (context.Context, *sdktrace.TracerProvider, error)

Start installs W3C trace propagation, resolves exporters from cfg, and returns a context carrying any inbound trace/state from cfg.TraceParent and cfg.TraceState, a fully configured TracerProvider, and a nil error.

Exporter resolution (fail-open):

• cfg.OTLPEndpoint set → OTLP HTTP exporter attached via SimpleSpanProcessor; construction failure emits a one-time stderr diagnostic and the exporter is skipped — the provider remains usable.
• cfg.Debug set → pretty-print stderr debug exporter attached; same fail-open behavior on construction failure.
• Both, neither, or either may be active simultaneously.

The error return is always nil. Exporter and propagation failures degrade to a no-op/recording-only provider rather than surfacing an error; the error return exists solely for signature stability in case a future change makes Start fallible.

Under the ax_no_otlp build constraint, newOTLPExporter resolves to the stub in otlp_disabled.go, so a configured cfg.OTLPEndpoint takes the fail-open branch above: one "otel exporter disabled" diagnostic, no export, and an otherwise unchanged recording provider. Every other behaviour documented here — propagation, the debug exporter, the returned context — is identical in both configurations.

Types

type Config

type Config struct {
	TraceParent    string
	TraceState     string
	OTLPEndpoint   string
	Debug          bool
	Stderr         io.Writer
	ServiceName    string
	ServiceVersion string
	ShutdownBudget time.Duration
}

Config is the telemetry configuration resolved by the public StartTelemetry constructor before the provider is installed.