Offline buffer

OxiPulse is designed to never lose metrics due to temporary network failures. When the OTLP endpoint is unreachable, the agent automatically switches to a local disk buffer and replays accumulated data once connectivity is restored.

How it works

  1. On each collection tick, the agent attempts to send the metrics batch to the configured endpoint.
  2. If the send fails (connection refused, timeout, DNS failure), the batch is written to a local buffer file on disk instead of being discarded.
  3. On the next successful connection, the agent replays all buffered batches in order before resuming normal operation.
  4. If the buffer reaches the configured maximum size (OXIPULSE_BUFFER_MAX_MB, default 100 MB), the oldest batches are dropped to make room for new ones.
Metrics in the buffer retain their original timestamps, so your time-series data remains accurate even after a long offline period.

Buffer location

Default locations by platform:

  • Linux: /var/lib/oxipulse/buffer/
  • Windows: C:\ProgramData\OxiPulse\buffer\

Override with the OXIPULSE_BUFFER_PATH environment variable:

bash
OXIPULSE_BUFFER_PATH=/data/oxipulse/buffer

Monitoring buffer state

The agent logs buffer activity at info level:

Log output
INFO oxipulse: endpoint unreachable, buffering metrics (buffer: 12 MB / 100 MB)
INFO oxipulse: connection restored, replaying 47 buffered batches
INFO oxipulse: buffer drained, resuming normal operation

Disk space considerations

At the default 10-second interval, one batch is approximately 1–3 KB. The default 100 MB buffer can hold roughly 8–24 hours of metrics before the oldest data starts being dropped.

Ensure the buffer directory is on a partition with sufficient free space, especially for servers that may experience extended offline periods.