Documentation
¶
Overview ¶
Package telemetry provides OpenTelemetry initialization and global accessor functions for traces, metrics, and logs.
Three pipelines are initialised independently via InitTracer, InitMeter, and InitLog. When no exporter is configured the SDK is still installed so that valid trace/span IDs are available for structured log correlation, while actual export is discarded (zero overhead).
Index ¶
- Constants
- func ConsoleProcessors(min otellog.Severity) []sdklog.Processor
- func Debug(ctx context.Context, msg string, attrs ...otellog.KeyValue)
- func Disable()
- func Enable()
- func Error(ctx context.Context, msg string, attrs ...otellog.KeyValue)
- func FormatPlainTextRecordLine(record *sdklog.Record) []byte
- func Info(ctx context.Context, msg string, attrs ...otellog.KeyValue)
- func InitAll(ctx context.Context, opts ...Option) (shutdown func(context.Context) error, err error)
- func InitLog(ctx context.Context, opts ...LogOption) (func(context.Context) error, error)
- func InitMeter(ctx context.Context, opts ...MeterOption) (func(context.Context) error, error)
- func InitTracer(ctx context.Context, opts ...TraceOption) (func(context.Context) error, error)
- func Logger(name string) otellog.Logger
- func Meter() metric.Meter
- func MeterWithSuffix(suffix string) metric.Meter
- func NewPlainTextExporter(w io.Writer) sdklog.Exporter
- func NewSeverityFilter(base sdklog.Processor, min, max otellog.Severity) sdklog.Processor
- func SetLoggerName(name string)
- func Trace(ctx context.Context, msg string, attrs ...otellog.KeyValue)
- func Tracer() trace.Tracer
- func TracerWithSuffix(suffix string) trace.Tracer
- func Warn(ctx context.Context, msg string, attrs ...otellog.KeyValue)
- type LogOption
- type MeterOption
- type Option
- type TraceOption
Constants ¶
const ( InstrumentationName = "flowcraft" ServiceName = "flowcraft" ServiceVersion = "0.1.0" )
Variables ¶
This section is empty.
Functions ¶
func ConsoleProcessors ¶ added in v0.1.9
ConsoleProcessors returns the canonical stdout/stderr split sink: records in [min, Warn) go to stdout, records in [Warn, +∞) go to stderr — mirroring POSIX conventions.
Each side is a NewPlainTextExporter wrapped in sdklog.NewBatchProcessor for async batching and shutdown draining, then gated by NewSeverityFilter so OTel's Enabled protocol can short-circuit dropped records before formatting.
Pass the result spread into WithLogProcessor:
telemetry.InitLog(ctx,
telemetry.WithLogProcessor(telemetry.ConsoleProcessors(otellog.SeverityInfo)...),
)
Each call returns a fresh slice of processors with their own batchers and exporters; do not share the returned processors across multiple LoggerProviders.
func Disable ¶
func Disable()
Disable globally disables all convenience log functions (useful in tests).
func FormatPlainTextRecordLine ¶ added in v0.1.9
FormatPlainTextRecordLine renders an OTel log record as a single line in the canonical plain-text format used by NewPlainTextExporter:
RFC3339Nano SEVERITY message k=v ...
Exposed so downstream sinks (file exporters, custom processors) can match the on-screen format.
func InitAll ¶
InitAll initializes tracing, metrics, and logging in one call. It returns a single shutdown function that tears down all three in reverse order.
func InitLog ¶
InitLog initializes the OpenTelemetry LoggerProvider.
Sinks are exactly the WithLogProcessor entries supplied by the caller; pass them in any order, batching/filtering policy is theirs to control. If no processor is supplied a discardProcessor (noop) is installed so global log calls remain safe.
Typical usage:
telemetry.InitLog(ctx,
telemetry.WithLogProcessor(telemetry.ConsoleProcessors(otellog.SeverityInfo)...),
)
To wire an OTLP / file / custom exporter, wrap it in the OTel BatchProcessor (or your own processor) and pass it via WithLogProcessor.
func InitMeter ¶
InitMeter initializes the OpenTelemetry MeterProvider.
With an Exporter it creates a PeriodicReader for regular metric collection. Without one the provider is created with no reader (noop — instruments are valid but never exported).
func InitTracer ¶
InitTracer initializes the OpenTelemetry TracerProvider.
With an Exporter the provider uses WithBatcher for async export. Without one it installs a real SDK provider backed by discardExporter (via WithSyncer to avoid background goroutine overhead) so that valid trace/span IDs are still generated for structured log correlation.
func MeterWithSuffix ¶
MeterWithSuffix returns a named sub-meter.
func NewPlainTextExporter ¶ added in v0.1.9
NewPlainTextExporter returns an sdklog.Exporter that formats each record via FormatPlainTextRecordLine and writes it to w. All severities are written to the same w; for stdout/stderr splitting use ConsoleProcessors or compose two exporters with NewSeverityFilter.
The exporter writes synchronously per Export call but is intended to be wrapped in sdklog.NewBatchProcessor (which provides asynchronous batching, queueing, and shutdown draining). ConsoleProcessors and the internal default sink already do this wrapping.
A nil w is treated as io.Discard.
func NewSeverityFilter ¶ added in v0.1.9
NewSeverityFilter wraps base with a severity gate. Records with severity < min, or severity >= max when max != 0, are dropped before reaching base.
Use max = 0 for "no upper bound" (the common case).
The filter implements OTel's Enabled protocol, so dropped records are never constructed in the first place — saving CPU and allocations across the entire pipeline (formatting, batching, exporting).
Returns a noop processor if base is nil.
func SetLoggerName ¶
func SetLoggerName(name string)
SetLoggerName sets the scope name for the convenience log functions.
func TracerWithSuffix ¶
TracerWithSuffix returns a named sub-tracer (e.g. "flowcraft/store").
Types ¶
type LogOption ¶
type LogOption func(*logOptions)
LogOption configures InitLog behaviour.
func WithLogProcessor ¶ added in v0.1.9
WithLogProcessor registers an OTel log processor. May be called multiple times to stack independent destinations (file, OTLP, custom routing).
This mirrors OTel's own sdklog.NewLoggerProvider(WithProcessor(...)) design and is the canonical way to attach log destinations.
func WithLogServiceName ¶
func WithLogServiceVersion ¶
type MeterOption ¶
type MeterOption func(*meterOptions)
MeterOption configures InitMeter behaviour.
func WithMeterExporter ¶
func WithMeterExporter(exp sdkmetric.Exporter) MeterOption
func WithMeterServiceName ¶
func WithMeterServiceName(name string) MeterOption
func WithMeterServiceVersion ¶
func WithMeterServiceVersion(version string) MeterOption
type Option ¶
type Option func(*initAllOpts)
func LoggerOpts ¶
func MeterOpts ¶
func MeterOpts(opts ...MeterOption) Option
func TracerOpts ¶
func TracerOpts(opts ...TraceOption) Option
type TraceOption ¶
type TraceOption func(*options)
TraceOption configures InitTracer behaviour.
func WithExporter ¶
func WithExporter(exp sdktrace.SpanExporter) TraceOption
func WithServiceName ¶
func WithServiceName(name string) TraceOption
func WithServiceVersion ¶
func WithServiceVersion(version string) TraceOption
Source Files