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
- func NewZapOTelCore(logger otellog.Logger) zapcore.Core
- func NewZapOTelCoreWithLevel(logger otellog.Logger, minLevel zapcore.Level) zapcore.Core
- type Config
- type LogExporterKind
- type LogProvider
- type MetricsExporterKind
- type SDK
- type TraceExporterKind
- type ZapOTelCore
- func (c *ZapOTelCore) Check(ent zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry
- func (c *ZapOTelCore) Enabled(level zapcore.Level) bool
- func (c *ZapOTelCore) Sync() error
- func (c *ZapOTelCore) With(fields []zapcore.Field) zapcore.Core
- func (c *ZapOTelCore) Write(ent zapcore.Entry, fields []zapcore.Field) error
Constants ¶
const ( TraceExporterOTLPGRPC = tracing.ExporterOTLPGRPC TraceExporterOTLPHTTP = tracing.ExporterOTLPHTTP TraceExporterStdout = tracing.ExporterStdout TraceExporterNoop = tracing.ExporterNoop )
Variables ¶
This section is empty.
Functions ¶
func NewZapOTelCore ¶
NewZapOTelCore creates a zapcore.Core that bridges to the OTel logs pipeline. The minimum log level is Info (zapcore.InfoLevel).
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.
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 ¶
Init creates a unified OTel SDK from the given Config and registers all providers globally (if SetGlobal is true).
func (*SDK) MetricsHTTPHandler ¶
MetricsHTTPHandler returns the Prometheus HTTP handler from the metrics provider, or nil if metrics are not enabled.
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 ¶
func (c *ZapOTelCore) Check(ent zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry
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.