Documentation
¶
Overview ¶
Package observability provides interfaces and utilities for logging and tracing.
This package defines standard interfaces for structured logging and distributed tracing that can be implemented by different backends. It allows shared packages to emit observability data without depending on specific implementations.
Logger Interface ¶
The Logger interface defines methods for template evaluation observability:
type Logger interface {
CacheHit(expression, expressionType string)
EvaluationStart(expression, expressionType string)
EvaluationError(err error, expression, expressionType string, duration time.Duration)
EvaluationSuccess(expression, expressionType string, duration time.Duration, result any)
}
Tracing ¶
The StartSpan function creates OpenTelemetry spans for distributed tracing:
ctx, span := observability.StartSpan(ctx, "reconcile", attribute.String("step", stepName))
defer span.End()
Integration ¶
This package integrates with:
- OpenTelemetry for distributed tracing
- Prometheus for metrics (via pkg/metrics)
- Standard logr for structured logging
Implementations can be swapped at runtime for testing or different deployment environments.
Index ¶
- func ConfigureTracing(serviceName string, initTimeout, shutdownTimeout time.Duration)
- func EnableTracePropagation(enabled bool)
- func EnableTracing(enabled bool)
- func InitTracerProvider(ctx context.Context, serviceName string) (func(context.Context) error, error)
- func ShutdownTracerProvider(ctx context.Context) error
- func StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func TracePropagationEnabled() bool
- func TracingEnabled() bool
- type Logger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConfigureTracing ¶ added in v0.1.4
ConfigureTracing sets the default tracing service name and init/shutdown timeouts.
Notes:
- serviceName is used when InitTracerProvider is called without a name.
- initTimeout bounds exporter initialization; shutdownTimeout bounds flush/close.
- Zero or negative timeout values leave the current defaults unchanged.
func EnableTracePropagation ¶ added in v0.1.4
func EnableTracePropagation(enabled bool)
EnableTracePropagation toggles whether OTEL propagators should inject trace context.
func EnableTracing ¶ added in v0.1.3
func EnableTracing(enabled bool)
EnableTracing toggles OpenTelemetry span emission for shared helpers.
func InitTracerProvider ¶ added in v0.1.4
func InitTracerProvider(ctx context.Context, serviceName string) (func(context.Context) error, error)
InitTracerProvider configures an OTLP trace exporter and tracer provider. It is safe to call multiple times; initialization happens once per process lifetime unless the provider is explicitly shut down.
func ShutdownTracerProvider ¶ added in v0.1.4
ShutdownTracerProvider flushes and closes the configured tracer provider. It is safe to call multiple times.
func StartSpan ¶ added in v0.1.3
func StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
StartSpan creates a tracer span when tracing is enabled and returns the context/span pair. When tracing is disabled, it returns the original context and a no-op span.
func TracePropagationEnabled ¶ added in v0.1.4
func TracePropagationEnabled() bool
TracePropagationEnabled reports whether OTEL trace propagation is enabled.
func TracingEnabled ¶ added in v0.1.3
func TracingEnabled() bool
TracingEnabled reports whether spans should be emitted.
Types ¶
type Logger ¶
type Logger interface {
CacheHit(expression, expressionType string)
EvaluationStart(expression, expressionType string)
EvaluationError(err error, expression, expressionType string, duration time.Duration)
EvaluationSuccess(expression, expressionType string, duration time.Duration, result any)
}
Logger defines the interface for a structured logger that can be used by shared packages.
Source Files