Documentation
¶
Index ¶
- Variables
- func NewMetrics(opts ...Option) (interfaces.Metrics, error)
- func NewTracer(opts ...Option) (interfaces.Tracer, error)
- type Config
- type Logs
- type Metrics
- type NoopLogs
- type NoopMetrics
- type NoopSpan
- type NoopTracer
- type Option
- func WithBatchTimeout(d time.Duration) Option
- func WithDeploymentEnvironment(env string) Option
- func WithEndpoint(endpoint string) Option
- func WithExportTimeout(d time.Duration) Option
- func WithHeaders(headers map[string]string) Option
- func WithInsecure(insecure bool) Option
- func WithLogLevel(level string) Option
- func WithLogger(l logger.Logger) Option
- func WithMetricsInterval(d time.Duration) Option
- func WithName(name string) Option
- func WithProtocol(p Protocol) Option
- func WithSamplingRatio(r float64) Option
- func WithServiceVersion(v string) Option
- type Protocol
- type Tracer
Constants ¶
This section is empty.
Variables ¶
var ( DefaultNoopTracer interfaces.Tracer = &NoopTracer{} DefaultNoopMetrics interfaces.Metrics = &NoopMetrics{} DefaultNoopLogs interfaces.Logs = &NoopLogs{} )
DefaultNoopTracer, DefaultNoopMetrics, and DefaultNoopLogs are shared no-op implementations for callers that omit explicit observability wiring (e.g. internal/runtime/temporal.buildTemporalRuntimeConfig).
Functions ¶
func NewMetrics ¶
func NewMetrics(opts ...Option) (interfaces.Metrics, error)
NewMetrics constructs a Metrics from the given options:
- Calls BuildConfig to validate and apply defaults.
- Builds an OTLP metrics exporter (gRPC or HTTP per [Config.Protocol]).
- Wraps it in a sdkmetric.PeriodicReader that pushes at [Config.MetricsInterval].
- Creates a sdkmetric.MeterProvider with an OTLP resource (service name, version, environment).
- Returns a Metrics scoped to [Config.Name].
func NewTracer ¶
func NewTracer(opts ...Option) (interfaces.Tracer, error)
NewTracer constructs a Tracer from the given options:
- Calls BuildConfig to validate and apply defaults.
- Builds an OTLP span exporter (gRPC or HTTP per [Config.Protocol]).
- Wraps it in a sdktrace.BatchSpanProcessor for async, batched export.
- Creates a sdktrace.TracerProvider with an OTLP resource (service name, version, environment).
- Returns a Tracer scoped to [Config.Name].
Types ¶
type Config ¶
type Config struct {
// Logger receives exporter and diagnostics messages when wiring fails or during shutdown.
Logger logger.Logger
// LogLevel is used when Logger is unset (same strings as [logger.DefaultLogger]: debug, info, warn, error).
LogLevel string
// Endpoint is the OTLP collector URL, e.g. "collector:4317" (gRPC) or
// "http://collector:4318" (HTTP). Required.
Endpoint string
// Name is the service / scope name attached to all telemetry. Required.
Name string
// Protocol selects the OTLP wire transport. Defaults to [ProtocolGRPC].
Protocol Protocol
// Headers are extra gRPC metadata or HTTP headers sent with every export request
// (e.g. {"Authorization": "Bearer <token>"} for SaaS backends). Optional.
Headers map[string]string
// Insecure disables TLS. Set true for local / dev collectors that have no cert.
Insecure bool
// ServiceVersion is added to the OTLP resource as "service.version". Optional.
ServiceVersion string
// DeploymentEnvironment is added to the OTLP resource as "deployment.environment"
// (e.g. "production", "staging"). Optional.
DeploymentEnvironment string
// ExportTimeout is the per-export call deadline.
// Defaults to [types.DefaultOTLPExportTimeout] (30 s).
ExportTimeout time.Duration
// BatchTimeout is the maximum delay before a trace batch is flushed.
// Lower values reduce trace latency at the cost of throughput.
// Defaults to [types.DefaultOTLPBatchTimeout] (5 s).
BatchTimeout time.Duration
// MetricsInterval is how often the metrics periodic reader pushes to the collector.
// Defaults to [types.DefaultOTLPMetricsInterval] (60 s).
MetricsInterval time.Duration
// SamplingRatio controls trace sampling between 0.0 (drop all) and 1.0 (keep all).
// Values ≤ 0 or > 1 fall back to AlwaysSample.
SamplingRatio float64
}
Config holds all settings for constructing OTLP-backed Tracer and Metrics clients. Build it with BuildConfig after applying functional [Option]s.
All fields that affect exporter timing and behaviour are exposed here so that callers using this package directly have full control. When observability is configured through pkg/agent.ObservabilityConfig the agent SDK applies the [types.DefaultOTLP*] constants automatically.
func BuildConfig ¶
BuildConfig merges options into Config and applies defaults:
- LogLevel: "error"
- Logger: stderr slog logger at LogLevel
- Protocol: ProtocolGRPC (= types.OTLPProtocolGRPC)
- ExportTimeout: types.DefaultOTLPExportTimeout (30 s)
- BatchTimeout: types.DefaultOTLPBatchTimeout (5 s)
- MetricsInterval:types.DefaultOTLPMetricsInterval (60 s)
Returns an error when Endpoint or Name is empty.
type Logs ¶
type Logs struct {
// contains filtered or unexported fields
}
Logs wraps sdklog.LoggerProvider and implements interfaces.Logs. Construct it with NewLogs; the zero value is not usable. Call Logs.Shutdown when the agent or worker stops to flush buffered log records.
func NewLogs ¶
NewLogs constructs a Logs from the given options:
- Calls BuildConfig to validate and apply defaults.
- Builds an OTLP log exporter (gRPC or HTTP per [Config.Protocol]).
- Wraps it in a sdklog.BatchProcessor for async, batched export.
- Creates a sdklog.LoggerProvider with the same service resource as tracer/metrics.
- Returns a Logs whose Logs.Provider can be passed to the logger bridge.
func (*Logs) Provider ¶
func (l *Logs) Provider() *sdklog.LoggerProvider
Provider returns the underlying sdklog.LoggerProvider. Pass it to pkg/logger.DefaultLoggerWithOtelProvider so the slog bridge sends records through this provider rather than the (likely-unset) global OTel LoggerProvider.
type Metrics ¶
type Metrics struct {
// contains filtered or unexported fields
}
Metrics implements interfaces.Metrics backed by an OTLP sdkmetric.MeterProvider.
Counters and histograms are created lazily on first use and cached for the lifetime of the Metrics instance. Construct it with NewMetrics; the zero value is not usable. Call Metrics.Shutdown when the agent or worker stops to flush pending metric data.
func (*Metrics) IncrementCounter ¶
IncrementCounter adds 1 to the named Int64Counter, creating it lazily on first call. Attributes are converted from interfaces.Attribute to OTel key-value pairs.
func (*Metrics) RecordHistogram ¶
func (m *Metrics) RecordHistogram(ctx context.Context, name string, value float64, attrs ...interfaces.Attribute)
RecordHistogram records value on the named Float64Histogram, creating it lazily on first call. Attributes are converted from interfaces.Attribute to OTel key-value pairs.
type NoopLogs ¶
type NoopLogs struct{}
NoopLogs is a no-op interfaces.Logs used when log export is disabled or [WithObservabilityConfig] is not set. Shutdown is a no-op so Agent.Close is always safe to call.
type NoopMetrics ¶
type NoopMetrics struct{}
func (*NoopMetrics) IncrementCounter ¶
func (n *NoopMetrics) IncrementCounter(ctx context.Context, name string, attrs ...interfaces.Attribute)
func (*NoopMetrics) RecordHistogram ¶
func (n *NoopMetrics) RecordHistogram(ctx context.Context, name string, value float64, attrs ...interfaces.Attribute)
type NoopSpan ¶
type NoopSpan struct{}
func (*NoopSpan) RecordError ¶
func (*NoopSpan) SetAttribute ¶
type NoopTracer ¶
type NoopTracer struct{}
func (*NoopTracer) StartSpan ¶
func (n *NoopTracer) StartSpan(ctx context.Context, name string, attrs ...interfaces.Attribute) (context.Context, interfaces.Span)
type Option ¶
type Option func(*Config)
Option mutates Config when passed to BuildConfig, NewTracer, or NewMetrics.
func WithBatchTimeout ¶
WithBatchTimeout sets the maximum delay before a trace span batch is flushed. Defaults to types.DefaultOTLPBatchTimeout (5 s).
func WithDeploymentEnvironment ¶
WithDeploymentEnvironment attaches the deployment environment to the OTLP resource ("deployment.environment"), e.g. "production" or "staging".
func WithEndpoint ¶
WithEndpoint sets the OTLP collector URL. Required.
- gRPC (default): "collector:4317" or "localhost:4317"
- HTTP: "http://collector:4318" or "https://collector:4318"
func WithExportTimeout ¶
WithExportTimeout sets the per-export call deadline. Defaults to types.DefaultOTLPExportTimeout (30 s).
func WithHeaders ¶
WithHeaders sets extra per-request headers (gRPC metadata or HTTP headers). Common use: auth tokens for hosted OTLP backends.
func WithInsecure ¶
WithInsecure disables TLS for the OTLP connection. Use only in development.
func WithLogLevel ¶
WithLogLevel sets the level used when WithLogger is not set (same strings as logger.DefaultLogger: debug, info, warn, error). Empty defaults to "error" in BuildConfig.
func WithLogger ¶
WithLogger sets structured logging for OTLP setup and lifecycle.
func WithMetricsInterval ¶
WithMetricsInterval sets how often the periodic metrics reader pushes to the collector. Defaults to types.DefaultOTLPMetricsInterval (60 s).
func WithProtocol ¶
WithProtocol selects the OTLP wire transport. Defaults to ProtocolGRPC.
func WithSamplingRatio ¶
WithSamplingRatio sets the trace sampling probability in [0.0, 1.0]. Values outside the range fall back to AlwaysSample (keep everything).
func WithServiceVersion ¶
WithServiceVersion attaches the service version to the OTLP resource ("service.version").
type Protocol ¶
type Protocol = types.OTLPProtocol
Protocol is an alias for types.OTLPProtocol re-exported so callers of this package do not need to import internal/types directly.
const ( // ProtocolGRPC exports telemetry over gRPC (default; most collectors support it). ProtocolGRPC Protocol = types.OTLPProtocolGRPC // ProtocolHTTP exports telemetry over HTTP/protobuf (useful when gRPC is blocked). ProtocolHTTP Protocol = types.OTLPProtocolHTTP )
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer implements interfaces.Tracer backed by an OTLP sdktrace.TracerProvider.
Construct it with NewTracer; the zero value is not usable. Call Tracer.Shutdown when the agent or worker stops to flush buffered spans.
func (*Tracer) OTelTracer ¶
OTelTracer returns the underlying OpenTelemetry Tracer. This is an optional OTel specific extension to the interfaces.OTelTracer interface.
func (*Tracer) Shutdown ¶
Shutdown flushes buffered spans and releases the exporter connection. It must be called once when the agent or worker exits.
func (*Tracer) StartSpan ¶
func (t *Tracer) StartSpan(ctx context.Context, name string, attrs ...interfaces.Attribute) (context.Context, interfaces.Span)
StartSpan begins a new span named name under ctx. Attributes are converted from interfaces.Attribute to OpenTelemetry key-value pairs. The returned context carries the active span so nested StartSpan calls form a parent-child tree.
Source Files