Skip to main content
The write-ahead log (WAL) persists API requests to disk before sending them to the server. By default, the client buffers requests in memory — if the process exits unexpectedly, buffered data is lost. Weave’s WAL addresses this by writing requests to disk before sending them. When you enable the WAL, the client writes each API request to a local JSONL file first, then flushes the file to the server. If a process crashes or the server is unreachable, the data remains on disk and is automatically sent when the client runs again. The WAL is especially useful in environments where processes may be interrupted or the server may be temporarily unavailable:
  • Container orchestration: Pods that may be evicted or OOM-killed before background threads finish uploading traces.
  • Distributed training: Multiple processes writing traces in parallel, where any single process may fail.
  • Unreliable networks: Environments where connectivity to the Weave server is intermittent.
  • Batch jobs: Long-running jobs where losing trace data from a crash would be costly.
For short-lived environments like serverless functions, also consider calling weave.flush() or weave.finish() before the process exits to ensure all data is uploaded. See Trace data loss in worker processes for more information.
The write-ahead log is currently opt-in. It will be enabled by default in a future release.

​
Enable the write-ahead log

To enable the WAL, set the WEAVE_ENABLE_WAL environment variable to true: 
export WEAVE_ENABLE_WAL=true
You can also set it in Python before calling weave.init(): 
import os
os.environ["WEAVE_ENABLE_WAL"] = "true"
No other code changes are required. The WAL works transparently with existing Weave tracing code.

​
How it works

When the WAL is enabled:
  1. Each call to the Weave API (object creates, call starts, call ends, and so on) is appended to a JSONL file on disk instead of being held only in memory.
  2. Each process writes to its own log file, so parallel processes do not conflict.
  3. A background sender reads the log files and flushes their contents to the Weave server.
  4. After the data is successfully sent, the log file is removed.
Log files are stored in .weave/wal/ within your working directory, organized by entity and project. Each file contains the raw API requests as JSON objects, one per line. When the client starts, it checks for existing log files from previous runs. If any are found, the sender flushes them along with any new data. This means data written by a process that crashed is recovered automatically the next time the client runs.

​
Environment variables

VariableTypeDefaultDescription
WEAVE_ENABLE_WALboolfalseEnables the write-ahead log. When set to true, Weave writes the API requests to disk locally before sending them to the server.
WEAVE_DISABLE_WAL_SENDERboolfalseDisables the WAL sender. When set to true, Weave writes the requests to disk locally but does not flush them to the server. This is useful for debugging.
See the environment variables reference page for a list of all available environment variables for Weave.