Crate fsqlite_observability 

MVCC conflict analytics and observability infrastructure.

Provides shared types and utilities for conflict tracing, metrics aggregation, and diagnostic logging across the FrankenSQLite MVCC layer.

Design Principles

• Zero-cost when unused: All observation is opt-in via the ConflictObserver trait. When no observer is registered, conflict emission compiles to nothing (the default NoOpObserver is inlined).
• Non-blocking: Observers MUST NOT acquire page locks or block writers. Conflict tracing is purely diagnostic.
• Shared foundation: Types defined here are reused by downstream observability beads (bd-t6sv2.2, .3, .5, .6, .8, .12).

Structs

ConflictMetrics

Aggregated conflict statistics exposed via PRAGMA.

ConflictMetricsSnapshot

Serializable snapshot of conflict metrics.

ConflictRingBuffer

Fixed-capacity ring buffer for storing recent conflict events.

CxPropagationMetrics

Atomic counters for Cx propagation telemetry.

CxPropagationMetricsSnapshot

Serializable snapshot of Cx propagation metrics.

IoUringLatencyMetrics

IoUringLatencySnapshot

MetricsObserver

Combined observer that records events to both a ConflictMetrics aggregator and a ConflictRingBuffer for detailed logging.

NoOpObserver

No-op observer that compiles to nothing. Default when observability is not configured.

TraceMetricsSnapshot

Snapshot of structured tracing counters.

TxnSlotMetrics

Atomic counters for TxnSlot lifecycle telemetry.

TxnSlotMetricsSnapshot

Serializable snapshot of TxnSlot telemetry counters.

Enums

ConflictEvent

A single conflict event emitted by the MVCC layer.

SsiAbortCategory

Categorized SSI abort reason (serialization-friendly).

Statics

GLOBAL_CX_PROPAGATION_METRICS

Global Cx propagation metrics singleton.

GLOBAL_IO_URING_LATENCY_METRICS

Global io_uring latency metrics singleton.

GLOBAL_TXN_SLOT_METRICS

Global TxnSlot observability metrics singleton.

Traits

ConflictObserver

Observer trait for conflict events.

Functions

io_uring_latency_snapshot

next_decision_id

Allocate the next decision identifier.

next_trace_id

Allocate the next trace identifier.

record_compat_trace_callback

Record a sqlite3_trace_v2 compatibility callback invocation.

record_io_uring_read_latency

record_io_uring_unix_fallback

record_io_uring_write_latency

record_trace_export

Record an export batch for tracing spans.

record_trace_export_error

Record a failed span-export attempt.

record_trace_span_created

Record creation of a tracing span in the SQL pipeline.

reset_io_uring_latency_metrics

reset_trace_metrics

Reset trace counters to zero (tests/diagnostics).

trace_metrics_snapshot

Read a point-in-time snapshot of trace counters.