Monitoring

Laredo's core library emits structured events through the EngineObserver interface. The pre-built service includes Prometheus and OpenTelemetry observers.

EngineObserver

The observer receives callbacks for every lifecycle event:

• Source connected/disconnected
• Pipeline state changes
• Baseline progress and completion
• Change received/applied/error
• ACK advances
• Buffer depth changes
• Snapshot creation/restore
• Schema changes
• Lag updates
• Dead letter writes
• Row expirations
• Fan-out client events

Prometheus

observability {
  metrics {
    type = prometheus
    port = 9090
    path = "/metrics"
  }
}

Key metrics

Metric	Type	Description
laredo_pipeline_state	Gauge	Current pipeline state
laredo_pipeline_row_count	Gauge	Rows in target
laredo_pipeline_buffer_depth	Gauge	Current buffer depth
laredo_pipeline_inserts_total	Counter	Total inserts applied
laredo_pipeline_updates_total	Counter	Total updates applied
laredo_pipeline_deletes_total	Counter	Total deletes applied
laredo_pipeline_errors_total	Counter	Total errors
laredo_source_lag_bytes	Gauge	Replication lag in bytes
laredo_source_lag_seconds	Gauge	Replication lag in seconds
laredo_change_apply_duration_seconds	Histogram	Time to apply a change
laredo_baseline_duration_seconds	Histogram	Time to complete baseline
laredo_snapshot_duration_seconds	Histogram	Time to create a snapshot
laredo_fanout_connected_clients	Gauge	Connected fan-out clients

OpenTelemetry

observability {
  metrics {
    type = otel
  }
}

Maps the same metrics to the OTel meter API with configurable exporters (OTLP, stdout, etc.).

Custom observer

Implement the EngineObserver interface for custom observability:

engine, _ := laredo.NewEngine(
    // ...
    laredo.WithObserver(myCustomObserver),
)

NullObserver

Use NullObserver when embedding Laredo and you don't need observability callbacks:

laredo.WithObserver(laredo.NullObserver{})

All methods are no-ops. This is useful for suppressing the default behavior when no observer is configured.

CompositeObserver

Use CompositeObserver to fan out events to multiple observers simultaneously:

observer := laredo.NewCompositeObserver(
    prometheusObserver,
    myCustomObserver,
    myLogObserver,
)

engine, _ := laredo.NewEngine(
    // ...
    laredo.WithObserver(observer),
)

Each event is delivered to all registered observers in order. Nil observers passed to NewCompositeObserver are filtered out automatically.