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 Weave sends it automatically when the client runs again. The WAL is especially useful in environments where processes might be interrupted or the server might be temporarily unavailable:
  • Container orchestration: Pods that might be evicted or OOM-killed before background threads finish uploading traces.
  • Distributed training: Multiple processes that write traces in parallel, where any single process might fail.
  • Unreliable networks: Environments where connectivity to the Weave server is intermittent.
  • Batch jobs: Long-running jobs where losing trace data from a crash is 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. For more information, see Trace data loss in worker processes.
The write-ahead log is opt-in. It will be enabled by default in a future release.

​
Enable the write-ahead log

To enable the WAL for your Weave client, 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. Weave appends each call to the Weave API (object creates, call starts, call ends, and so on) to a JSONL file on disk instead of holding it only in memory.
  2. Each process writes to its own log file, so parallel processes don’t conflict.
  3. A background sender reads the log files and flushes their contents to the Weave server.
  4. After the data is successfully sent, Weave removes the log file.
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 Weave automatically recovers data written by a process that crashed the next time the client runs.

​
Environment variables

The following environment variables control WAL behavior.
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 doesn’t flush them to the server. This is useful for debugging.
For a list of all available environment variables for Weave, see the environment variables reference page.