A log stream is an independently replicated shard in OceanBase. Each stream has its own Paxos log and leader. User tablets map to log streams, so failover and replication lag are scoped per stream rather than for the whole cluster.

OceanBase stores user data in log streams: independently replicated shards that each maintain their own Paxos log. Each log stream elects a leader from its replica set. That design differs from a single primary with asynchronous read replicas.

When log streams matter

You need this model when you plan zone layout, diagnose leader failover, or explain replication lag that affects only part of a tenant. Hot tablets that map to one log stream can bottleneck on a single leader even when other nodes have spare CPU.

Core concepts

  • Log stream (LS): Unit of replication; holds a slice of tablet data and its Paxos log.
  • Tablet: User-visible partition mapped to one log stream.
  • Paxos quorum: Production clusters typically use three or five replicas across zones.

See the OceanBase glossary for related terms, What is OceanBase? for the product overview, and Paxos quorum design for multi-region replica placement.

Leader election

When a leader fails, followers run an election. The new leader must have the highest committed log sequence. Client connections should route through OBProxy (ODP), which caches leader locations and refreshes on redirect.

SELECT ls_id, role, zone FROM oceanbase.__all_virtual_log_stat;

Monitor ROLE transitions during failover tests. Repeated elections on the same log stream often indicate network partition, disk latency, or clock skew. Measure failover duration in your environment; do not assume a fixed SLA without a recent drill.

Sizing guidance

Start with one log stream per tenant for small workloads. Add log streams when single-stream CPU stays above roughly 70% sustained or Paxos append latency grows past your SLA. Validate with workload tests rather than extrapolating from lab benchmarks alone.

Common mistakes

  • Connecting applications directly to observers instead of OBProxy during failover tests.
  • Treating cluster-wide CPU as healthy while one log stream leader is saturated.
  • Adding zones without updating locality and quorum math.

Validation

Run a controlled leader switch or observer stop in staging, then confirm:

  1. __all_virtual_log_stat shows a stable leader per stream.
  2. Application errors recover through OBProxy without manual connection changes.
  3. Replication lag returns to baseline within your measured window.

Sources and further reading