Module names 

Metric and label name constants — the single source of truth for the taxonomy documented in docs/METRICS.md.

Every framework metric is registered through these constants; nothing else may hard-code a metric name. Names follow Prometheus conventions: _total suffix on counters, unit suffixes (_seconds, _bytes, _rows) on everything measured in a unit, etl_ prefix throughout.

Constants

BACKPRESSURE_INFLIGHT_BYTES

Current global in-flight byte budget usage.

BACKPRESSURE_PAUSED

1 while the source is paused by the watermark controller.

BACKPRESSURE_PAUSED_SECONDS_TOTAL

Cumulative paused time in seconds. Monotonically increasing; exported as a gauge because the metrics counter type is integer-only.

BACKPRESSURE_PAUSE_EVENTS_TOTAL

Pause transitions (flapping indicator when high).

CHECKPOINT_COMMITS_TOTAL

Source commit calls, by L_OUTCOME.

CHECKPOINT_COMMIT_DURATION_SECONDS

Commit round-trip time.

CHECKPOINT_PENDING_BATCHES

Unacknowledged batches tracked; unlabelled series is the max across partitions.

CHECKPOINT_WATERMARK_AGE_SECONDS

Age of the oldest unacknowledged batch — the primary “stuck pipeline” alert signal.

COUNTERS

Every counter name (must end in _total).

DESER_BATCH_DURATION_SECONDS

Deserialization time per source batch.

DESER_NOT_READY_TOTAL

Counter: payload replays awaiting an upstream dependency (e.g. a schema fetch) — DeserError::NotReady occurrences. Not an error and not backpressure.

DESER_RECORDS_DROPPED_TOTAL

Payloads dropped by the Skip error policy, by L_REASON.

DESER_RECORDS_TOTAL

Deserialization outputs plus one error per failed payload, by L_OUTCOME.

E2E_LATENCY_SECONDS

Source-to-durable-write latency, observed per acknowledged batch.

GAUGES

Every gauge name.

HISTOGRAMS

Every histogram name (must carry a unit suffix).

L_COMPONENT

Component instance id label (e.g. orders_kafka).

L_COMPONENT_TYPE

Component implementation label (e.g. kafka, clickhouse, map).

L_ERROR_TYPE

Error taxonomy class label (retryable, record_level, fatal).

L_EVENT

Rebalance event label (assign, revoke).

L_OUTCOME

Outcome label (ok, error).

L_PARTITION

Source partition label (cardinality-gated by per_partition_detail).

L_PIPELINE

Pipeline name label.

L_QUEUE

Queue edge label (<upstream>-><downstream>).

L_REASON

Drop reason label (filtered, skip_policy).

L_REPLICA

Sink replica label.

L_SHARD

Sink shard label.

L_STATE

Pipeline state label (starting, running, draining, failed).

L_VERSION

Build version label on etl_pipeline_info.

OPERATOR_BATCH_DURATION_SECONDS

Processing time per batch through this operator.

OPERATOR_ERRORS_TOTAL

User-code errors by L_ERROR_TYPE.

OPERATOR_RECORDS_DROPPED_TOTAL

Records intentionally removed, by L_REASON.

OPERATOR_RECORDS_IN_TOTAL

Records entering the operator.

OPERATOR_RECORDS_OUT_TOTAL

Records emitted downstream by the operator.

PIPELINE_INFO

Constant 1; carries build metadata via L_VERSION.

PIPELINE_STATE

1 for the current state, 0 otherwise, by L_STATE.

PIPELINE_THREADS

Pinned pipeline thread count.

QUEUE_CAPACITY

Configured queue bound, by L_QUEUE.

QUEUE_DEPTH

Items currently queued, by L_QUEUE.

QUEUE_FULL_EVENTS_TOTAL

try_send rejections (each is a backpressure signal, never a block).

SINK_ABANDONED_BATCHES_TOTAL

Batches abandoned at the drain deadline (replayed after restart).

SINK_BATCH_BYTES

Bytes per sealed batch.

SINK_BATCH_ROWS

Rows per sealed batch.

SINK_BREAKER_OPENS_TOTAL

Circuit-breaker open transitions, by L_SHARD and L_REPLICA.

SINK_BYTES_TOTAL

Bytes durably written, by L_SHARD.

SINK_ERRORS_TOTAL

Write errors, by L_SHARD and L_ERROR_TYPE.

SINK_FLUSHES_TOTAL

Flushes by trigger, by L_SHARD and L_REASON.

SINK_FLUSH_DURATION_SECONDS

Write round-trip per flush including retries, by L_SHARD.

SINK_INFLIGHT_BATCHES

Sealed batches currently in flight, by L_SHARD.

SINK_RECORDS_TOTAL

Records durably written (acknowledged flushes only), by L_SHARD.

SINK_REPLICA_HEALTHY

1 = circuit closed, 0 = open, by L_SHARD and L_REPLICA.

SINK_RETRIES_TOTAL

Flush attempts beyond the first, by L_SHARD.

SOURCE_BYTES_TOTAL

Payload bytes emitted by the source.

SOURCE_LAG_RECORDS

Consumer lag; unlabelled series is the max across partitions.

SOURCE_LANES_ACTIVE

Currently assigned lanes (partitions).

SOURCE_POLL_DURATION_SECONDS

Time spent inside poll per call.

SOURCE_REBALANCES_TOTAL

Rebalance events observed, labelled by L_EVENT.

SOURCE_RECORDS_TOTAL

Records emitted by the source (post-poll, pre-deserialization).