telemetry

import "github.com/open-outbox/relay/internal/telemetry"

Package telemetry provides a centralized system for application observability. It integrates structured logging, Prometheus metrics, and OpenTelemetry tracing to give deep insights into the Open Outbox Relay’s operation.

The core components of this package include:

Telemetry: A composite struct that bundles a `zap.Logger`, `Metrics` (Prometheus), and OpenTelemetry `Tracer` and `Meter` instances. This allows for easy injection of all observability tools into any component.
Metrics: Manages Prometheus metric instruments (e.g., counters, gauges, histograms) for tracking key performance indicators and operational health.
OTelProviders: Handles the setup and shutdown of OpenTelemetry SDKs, including configuring exporters for traces and metrics.

This package aims to make it simple for other parts of the application to emit logs, record metrics, and create spans without needing to manage the underlying observability SDKs directly. It promotes consistent instrumentation across the entire relay.

Index

Constants
type Metrics
- func NewMetrics(meterProvider metric.MeterProvider) (*Metrics, error)
type OTelProviders
- func NewOTelProviders(ctx context.Context, cfg *config.Config) (*OTelProviders, error)
type Telemetry
- func (t Telemetry) ScopedLogger(moduleName string) *zap.Logger

Constants

InstrumentationName is the unique identifier used for OpenTelemetry tracing and metrics associated with the relay’s internal operations.

const InstrumentationName = "github.com/open-outbox/relay"

type Metrics

Metrics holds the set of OpenTelemetry metric instruments used to monitor the health and performance of the Outbox Relay.

type Metrics struct {
    // BatchSize tracks the number of events fetched from the database in a
    // single claim operation. This helps monitor if the relay is keeping
    // up with the ingestion rate.
    BatchSize metric.Int64Histogram

    // EventsTotal is a counter that tracks the total number of events processed.
    // Typical attributes include 'status' (success/failed) and 'type' (event type).
    EventsTotal metric.Int64Counter

    // EndToEndLatency measures the total time elapsed from the moment an event
    // was created in the database until it was successfully acknowledged by
    // the message broker.
    // Typical attributes include 'type' (event type).
    EndToEndLatency metric.Float64Histogram

    // StorageLatency measures the duration of individual database operations.
    // Typical attributes include 'op' (e.g., claim, mark_delivered, mark_failed).
    StorageLatency metric.Float64Histogram

    // PublisherLatency measures how long it takes to publish a message to the
    // broker.
    // Typical attributes include 'status' (success/failed) and 'type' (event type).
    PublisherLatency metric.Float64Histogram

    // PendingGauge represents the current number of events sitting in the
    // outbox table with a 'PENDING' status.
    PendingGauge metric.Int64Gauge

    // OldestPendingSeconds tracks the age of the oldest pending event in the
    // queue, providing a direct measurement of "lag".
    OldestPendingSeconds metric.Int64Gauge

    // RelayStatusGauge represents the current operational state of the relay:
    // 1 = Active, 2 = Paused (Publisher Down), 3 = Error (Infrastructure Failure).
    RelayStateGauge metric.Int64Gauge
}

func NewMetrics

func NewMetrics(meterProvider metric.MeterProvider) (*Metrics, error)

NewMetrics initializes the Metrics struct by creating instruments through the provided MeterProvider. It defines the descriptions and units for each metric to ensure they are correctly represented in observability backends.

type OTelProviders

OTelProviders holds the concrete SDK providers (for shutdown) and the initialized interfaces (for injection).

type OTelProviders struct {
    TraceProvider *trace.TracerProvider
    MeterProvider *metric.MeterProvider
    Shutdown      func(context.Context) error
}

func NewOTelProviders

func NewOTelProviders(ctx context.Context, cfg *config.Config) (*OTelProviders, error)

NewOTelProviders bootstraps the OpenTelemetry pipeline.

type Telemetry

Telemetry is a composite structure that bundles all observability tools used by the relay. It simplifies dependency injection by providing a single object containing logging, metrics, tracing, and metering capabilities.

type Telemetry struct {
    // Logger is the structured logger (zap) used for recording events.
    Logger *zap.Logger
    // Metrics provides access to the custom application metrics instruments.
    Metrics *Metrics
    // Tracer provides the ability to create trace spans for distributed tracing.
    Tracer trace.Tracer
    // Meter provides the ability to create metric instruments for observability.
    Meter metric.Meter
}

func (Telemetry) ScopedLogger

func (t Telemetry) ScopedLogger(moduleName string) *zap.Logger

ScopedLogger returns a new logger instance with a “module” field preset to the provided moduleName for consistent contextual logging.