Storage, backup and updates
Where data lives
Everything is in one folder: /var/lib/statsraven for the service, /data in Docker, otherwise ./data or STATSRAVEN_DATA_DIR.
| Path | What |
|---|---|
meta.db | SQLite: projects, people, settings, patterns, charts, chats and the change log |
segments/ | Events as Parquet files, one folder per project and day. Other tools can read them |
rollups/ | Hourly totals per day |
wal/ | Records received but not yet written to Parquet |
index/ | The full-text index for log search, when it is on |
license.key | The license file |
How long data is kept
With a license, StatsRaven keeps raw events until the disk needs room, or for a number of days you choose in Settings, Storage. Free keeps 7 days. Hourly totals stay after raw events go.
When the disk reaches the cleanup level, 90% unless you change it, StatsRaven removes debug lines, bot traffic and the oldest days first, never today. At the refuse level, 97% unless changed, it stops taking new data and senders are told to retry. Both apply without a restart.
Log search
Tail, Search finds stored log lines, newest first. Every word must match. Use quotes for a phrase, -word to leave a word out, OR between choices, and level:error, source:nginx, status:500 or template: for fields. Chat and Claude over MCP search the same way with search_logs. Email and IP addresses in results are hidden. People who may not see log text, set in Settings, Privacy, cannot search it.
Search uses a full-text index kept in index/ in the data folder. Lines are added as they are stored, older lines are added in the background when the index is new, and days removed by retention or a full disk leave it too. The index is off until an admin turns it on: Get started asks once, with advice from a check of the disk and memory, and Settings, Storage turns it on or off and shows its size. It can take more disk than the stored data itself. Without the index, search reads the stored lines, which is slower and takes plain words only.
Backup
Back up the whole data folder. For a consistent copy, stop StatsRaven, copy the folder, and start it again:
sudo systemctl stop statsraven
sudo tar -czf statsraven-backup.tar.gz -C /var/lib statsraven
sudo systemctl start statsraven
To restore, stop StatsRaven, put the folder back, and start it. Data sent while it is stopped waits in Vector, Fluent Bit or the OpenTelemetry Collector and arrives when it is back.
Updates
Run the install command again, or pull the new Docker image and start the container with the same volume. Data is kept and changes to its format are applied on start. The app answers within seconds of a restart while older data loads in the background. Every release is listed at statsraven.com/download.
A license covers the releases made while its updates are paid. A newer release still starts and runs, and Settings, License says it came out after your updates ended. Renew updates or install an earlier release. To stay on one release in Docker, use its version tag, such as ghcr.io/umutgokbayrak/statsraven:0.1, instead of latest.
Commands
| Command | What it does |
|---|---|
statsraven serve | Runs the server. --listen sets the address |
statsraven add-project NAME | Makes a project and prints an ingest token |
statsraven site-key --project P --hosts a.com,b.com | Turns on the browser snippet for these sites and prints its key |
statsraven watch, watch-journal | Follows a log file or the systemd journal |
statsraven ingest | Loads files once, with the server stopped |
statsraven route-worker | Files a Cloudflare Worker under a project |
statsraven admin-token | Makes a token for MCP and the SQL API |
statsraven query "SQL" | Runs a read-only query |
statsraven license | Shows what the license allows |
statsraven templates | Lists the most common log patterns |
Every command takes --data for the data folder and --license for a license file elsewhere. statsraven --version prints the version.
Settings from the environment
| Variable | What it sets |
|---|---|
STATSRAVEN_DATA_DIR | The data folder |
STATSRAVEN_LISTEN | Web app, ingest, MCP and SQL API address. 127.0.0.1:7600 unless set |
STATSRAVEN_OTLP_GRPC | OpenTelemetry over gRPC. 127.0.0.1:4317 unless set |
STATSRAVEN_LICENSE_PATH | A license file outside the data folder |
STATSRAVEN_RETENTION_DAYS | Days to keep raw events, when not set in Settings |
STATSRAVEN_WEB_MEMORY_ROWS | Website rows kept in memory for fast reports. 2,000,000 unless set |
STATSRAVEN_REQUEST_MEMORY_ROWS | Server request rows kept in memory. 3,000,000 unless set |
AI settings are on the AI page. For the service, put variables in /etc/statsraven/statsraven.env and restart it.