opentelemetry

package module
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Aug 20, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package opentelemetry provides a unified, one-call setup for OpenTelemetry traces, metrics, and logs — the three pillars of observability.

It builds on the standalone `tracing` and `metrics` packages and adds the logs signal (still experimental in the OTel Go SDK) to provide a single entry point for application bootstrap.

Quick start

otelSDK, err := opentelemetry.Init(ctx, opentelemetry.Config{
    ServiceName:    "my-service",
    ServiceVersion: "1.0.0",
    Environment:    "production",
    TraceExporter:  opentelemetry.TraceExporterOTLPGRPC,
    OTLPEndpoint:   "localhost:4317",
    MetricsExporter: opentelemetry.MetricsExporterPrometheus,
    LogExporter:    opentelemetry.LogExporterOTLPGRPC,
    SampleRatio:    0.1,
})
if err != nil {
    log.Fatal(err)
}
defer otelSDK.Shutdown(ctx)

// Expose Prometheus metrics.
http.Handle("/metrics", otelSDK.MetricsHTTPHandler())
go http.ListenAndServe(":9090", nil)

The package also provides a Zap→OTel logs bridge so that existing zap.Logger usage can be forwarded to the OTel logs pipeline.

Index

Constants

View Source
const (
	TraceExporterOTLPGRPC = tracing.ExporterOTLPGRPC
	TraceExporterOTLPHTTP = tracing.ExporterOTLPHTTP
	TraceExporterStdout   = tracing.ExporterStdout
	TraceExporterNoop     = tracing.ExporterNoop
)

Variables

This section is empty.

Functions

func NewZapOTelCore

func NewZapOTelCore(logger otellog.Logger) zapcore.Core

NewZapOTelCore creates a zapcore.Core that bridges to the OTel logs pipeline. The minimum log level is Info (zapcore.InfoLevel).

func NewZapOTelCoreWithLevel

func NewZapOTelCoreWithLevel(logger otellog.Logger, minLevel zapcore.Level) zapcore.Core

NewZapOTelCoreWithLevel creates a zapcore.Core with a custom minimum level.

Types

type Config

type Config struct {
	// ── Shared ──
	ServiceName        string
	ServiceVersion     string
	ServiceNamespace   string
	Environment        string
	ResourceAttributes map[string]string

	// ── Tracing ──
	TraceExporter          TraceExporterKind
	OTLPEndpoint           string // used for trace OTLP exporters
	OTLPInsecure           *bool
	OTLPHeaders            map[string]string
	SampleRatio            float64
	SpanBatchTimeout       time.Duration
	SpanMaxQueueSize       int
	SpanMaxExportBatchSize int

	// ── Metrics ──
	MetricsExporter         MetricsExporterKind
	DefaultHistogramBuckets []float64
	PrometheusRegistry      promclient.Registerer
	PrometheusGatherer      promclient.Gatherer

	// ── Logs ──
	LogExporter     LogExporterKind
	LogOTLPEndpoint string // used for log OTLP exporters (defaults to OTLPEndpoint)
	LogOTLPInsecure *bool
	LogOTLPHeaders  map[string]string

	// ── Global ──
	// SetGlobal registers all providers globally. Default: true.
	SetGlobal bool
}

Config configures the unified OTel SDK (traces + metrics + logs).

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type LogExporterKind

type LogExporterKind string

LogExporterKind selects which log exporter to use.

const (
	// LogExporterOTLPGRPC sends logs via OTLP over gRPC (port 4317).
	LogExporterOTLPGRPC LogExporterKind = "otlp_grpc"
	// LogExporterOTLPHTTP sends logs via OTLP over HTTP (port 4318).
	LogExporterOTLPHTTP LogExporterKind = "otlp_http"
	// LogExporterStdout writes logs to stdout (useful for development).
	LogExporterStdout LogExporterKind = "stdout"
	// LogExporterNoop discards all logs.
	LogExporterNoop LogExporterKind = "noop"
)

type LogProvider

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

LogProvider wraps an SDK LoggerProvider.

func (*LogProvider) Logger

func (p *LogProvider) Logger() otellog.Logger

Logger returns a logger with the configured service name.

func (*LogProvider) LoggerProvider

func (p *LogProvider) LoggerProvider() *sdklog.LoggerProvider

LoggerProvider returns the underlying SDK LoggerProvider.

func (*LogProvider) Shutdown

func (p *LogProvider) Shutdown(ctx context.Context) error

Shutdown flushes and shuts down the log provider. It is safe to call multiple times and from concurrent goroutines.

type MetricsExporterKind

type MetricsExporterKind string

MetricsExporterKind selects which metrics exporter to use.

const (
	// MetricsExporterPrometheus exposes metrics via a Prometheus HTTP handler.
	MetricsExporterPrometheus MetricsExporterKind = "prometheus"
	// MetricsExporterNoop discards all metrics.
	MetricsExporterNoop MetricsExporterKind = "noop"
)

type SDK

type SDK struct {
	Traces  *tracing.Provider
	Metrics *metrics.Provider
	Logs    *LogProvider
	// contains filtered or unexported fields
}

SDK is the unified OTel SDK handle. It holds the trace provider, metrics provider, and log provider, and provides a single Shutdown method.

func Init

func Init(ctx context.Context, cfg Config) (*SDK, error)

Init creates a unified OTel SDK from the given Config and registers all providers globally (if SetGlobal is true).

func (*SDK) MetricsHTTPHandler

func (s *SDK) MetricsHTTPHandler() http.Handler

MetricsHTTPHandler returns the Prometheus HTTP handler from the metrics provider, or nil if metrics are not enabled.

func (*SDK) Shutdown

func (s *SDK) Shutdown(ctx context.Context) error

Shutdown flushes and shuts down all providers (traces, metrics, logs). It is safe to call multiple times.

type TraceExporterKind

type TraceExporterKind = tracing.ExporterKind

TraceExporterKind selects which trace exporter to use.

type ZapOTelCore

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

ZapOTelCore is a zapcore.Core that bridges zap log entries to the OpenTelemetry logs pipeline.

This allows existing zap.Logger usage to be forwarded to OTel-compatible backends (Jaeger, Loki, etc.) without changing application code.

Usage:

core := opentelemetry.NewZapOTelCore(otelSDK.Logs.Logger())
logger := zap.New(core)

func (*ZapOTelCore) Check

Check returns a CheckedEntry if logging should proceed, nil otherwise.

func (*ZapOTelCore) Enabled

func (c *ZapOTelCore) Enabled(level zapcore.Level) bool

Enabled returns whether the given level is enabled.

func (*ZapOTelCore) Sync

func (c *ZapOTelCore) Sync() error

Sync flushes any buffered log entries. The OTel logs pipeline is asynchronous; a true flush requires shutting down the LoggerProvider.

func (*ZapOTelCore) With

func (c *ZapOTelCore) With(fields []zapcore.Field) zapcore.Core

With adds structured context to the core.

func (*ZapOTelCore) Write

func (c *ZapOTelCore) Write(ent zapcore.Entry, fields []zapcore.Field) error

Write writes the entry to the OTel logs pipeline.

Jump to

Keyboard shortcuts

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