observe
import "github.com/danmestas/dagnats/observe"config.go defines the telemetry configuration struct. Kept separate from setup.go so callers can construct Config without importing OTel SDK types.
propagation.go provides trace context propagation helpers for NATS message boundaries. InjectTraceContext writes W3C trace context to both NATS headers and the Event payload for persistence. ExtractTraceContext reads from headers first, falling back to Event.TraceParent for replay scenarios.
propagator.go installs the default W3C trace-context propagator when nothing else has claimed the global slot. Kept separate from propagation.go so that file stays focused on NATS header carriers.
setup.go is the single entry point for OTel provider setup. One call to InitTelemetry wires tracing, metrics, and logging with NATS-backed exporters (always) and OTLP/HTTP exporters (when configured). This is a deep module: rich behavior behind a minimal interface.
Index
- func EnsureDefaultPropagator()
- func ExtractTraceContext(msg jetstream.Msg, evt *protocol.Event) context.Context
- func ExtractTraceContextHeader(hdr nats.Header) context.Context
- func ExtractTraceContextRaw(msg *nats.Msg, evt *protocol.Event) context.Context
- func InitTelemetry(ctx context.Context, cfg Config) (func(context.Context), error)
- func InjectTraceContext(ctx context.Context, msg *nats.Msg, evt *protocol.Event)
- func InjectTraceContextHeader(ctx context.Context, hdr nats.Header)
- func TraceContextFromTask(task protocol.TaskPayload) context.Context
- type Config
- type NATSHeaderCarrier
func EnsureDefaultPropagator
func EnsureDefaultPropagator()EnsureDefaultPropagator installs a TraceContext+Baggage composite as the global OTel TextMapPropagator if — and only if — the current global is the no-op default (Fields() empty). Never overwrites an already-installed propagator, custom or otherwise. Idempotent: safe to call from every component constructor. A package-level mutex serializes concurrent first-party callers, so this function is safe to race from many goroutines; it cannot defend against an out-of-band otel.SetTextMapPropagator call racing it from outside this package, since OTel’s global setter has no compare-and-swap — first-party installs must route through here.
func ExtractTraceContext
func ExtractTraceContext(msg jetstream.Msg, evt *protocol.Event) context.ContextExtractTraceContext reads W3C trace context from NATS headers, falling back to Event.TraceParent for replay. Accepts jetstream.Msg for consumer message handling. evt may be nil when no event fallback is needed.
func ExtractTraceContextHeader
func ExtractTraceContextHeader(hdr nats.Header) context.ContextExtractTraceContextHeader reads W3C trace context directly from a NATS header map. Returns context.Background() when hdr is nil or carries no traceparent. This is the header-level entry point for transports (e.g. nats-micro requests) that expose headers without a *nats.Msg or jetstream.Msg.
func ExtractTraceContextRaw
func ExtractTraceContextRaw(msg *nats.Msg, evt *protocol.Event) context.ContextExtractTraceContextRaw reads W3C trace context from a raw *nats.Msg header, falling back to Event.TraceParent for replay. Used in publish paths that work with *nats.Msg.
func InitTelemetry
func InitTelemetry(ctx context.Context, cfg Config) (func(context.Context), error)InitTelemetry creates and registers OTel TracerProvider, MeterProvider, and LoggerProvider. Returns a shutdown function that flushes and closes all three providers. Panics on programmer errors (nil conn, empty service name). Propagator install now routes through EnsureDefaultPropagator (best-effort first-writer-wins) instead of unconditionally resetting the global, so a propagator installed before InitTelemetry runs survives.
func InjectTraceContext
func InjectTraceContext(ctx context.Context, msg *nats.Msg, evt *protocol.Event)InjectTraceContext writes W3C trace context to both NATS headers and the Event’s TraceParent/TraceState fields for persistence. Panics on nil msg (programmer error). evt may be nil when no event dual-write is needed.
func InjectTraceContextHeader
func InjectTraceContextHeader(ctx context.Context, hdr nats.Header)InjectTraceContextHeader writes W3C trace context from ctx directly into a NATS header map. This is the header-level entry point for carriers that are not a *nats.Msg — the inject counterpart to ExtractTraceContextHeader. Panics on nil ctx or nil hdr (programmer error: a nil map cannot be written to).
Writes nothing when ctx carries no valid span context: the W3C propagator skips invalid span contexts, so callers never see an empty or malformed traceparent.
func TraceContextFromTask
func TraceContextFromTask(task protocol.TaskPayload) context.ContextTraceContextFromTask reads the W3C trace context the bridge stamped on a polled task and returns a context suitable as the parent of the worker’s execution span. Returns context.Background() when the task carries no traceparent (pre-#537 bridges, or a dispatch with no active span), so callers can pass the result through unconditionally.
This lives in observe rather than in the SDK so W3C extraction stays behind the observability boundary: every worker transport hands over its TaskPayload and gets back a context, instead of each one rebuilding a header map and reaching for the propagator itself.
type Config
Config controls how InitTelemetry wires OTel providers. ServiceName and NATSConn are required — InitTelemetry panics if either is zero-valued. OTLPEndpoint, when non-empty, gates whether OTLP/HTTP export is enabled at all; the actual endpoint, headers, TLS, protocol, and per-signal overrides come from the standard OTel SDK env vars (see #184).
type Config struct {
// ServiceName identifies this process in telemetry data.
ServiceName string
// NATSConn is used to create a JetStream context for the
// NATS-backed exporters. Caller owns the connection.
NATSConn *nats.Conn
// OTLPEndpoint is a sentinel that gates OTLP exporter
// construction: when non-empty, dagnats constructs OTLP
// exporters and the OTel SDK reads its standard env vars
// (OTEL_EXPORTER_OTLP_ENDPOINT, _HEADERS, _PROTOCOL,
// _INSECURE, per-signal variants, etc.) for the actual
// endpoint and transport configuration. The string value
// itself is no longer passed to the SDK.
OTLPEndpoint string
// Resource holds additional OTel resource attributes
// merged into the auto-detected set (host, OS, process).
Resource map[string]string
}type NATSHeaderCarrier
NATSHeaderCarrier adapts nats.Header to OTel’s propagation.TextMapCarrier interface, enabling W3C trace-context injection and extraction over NATS messages.
type NATSHeaderCarrier struct {
Header nats.Header
}func (NATSHeaderCarrier) Get
func (c NATSHeaderCarrier) Get(key string) stringGet returns the first value for the given key, or "" if the header is nil.
func (NATSHeaderCarrier) Keys
func (c NATSHeaderCarrier) Keys() []stringKeys returns all header keys in sorted order, or nil if Header is nil.
func (NATSHeaderCarrier) Set
func (c NATSHeaderCarrier) Set(key, val string)Set stores a key-value pair. Panics if Header is nil (programmer error).
Generated by gomarkdoc