StatsRaven

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.

PathWhat
meta.dbSQLite: 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.keyThe 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

CommandWhat it does
statsraven serveRuns the server. --listen sets the address
statsraven add-project NAMEMakes a project and prints an ingest token
statsraven site-key --project P --hosts a.com,b.comTurns on the browser snippet for these sites and prints its key
statsraven watch, watch-journalFollows a log file or the systemd journal
statsraven ingestLoads files once, with the server stopped
statsraven route-workerFiles a Cloudflare Worker under a project
statsraven admin-tokenMakes a token for MCP and the SQL API
statsraven query "SQL"Runs a read-only query
statsraven licenseShows what the license allows
statsraven templatesLists 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

VariableWhat it sets
STATSRAVEN_DATA_DIRThe data folder
STATSRAVEN_LISTENWeb app, ingest, MCP and SQL API address. 127.0.0.1:7600 unless set
STATSRAVEN_OTLP_GRPCOpenTelemetry over gRPC. 127.0.0.1:4317 unless set
STATSRAVEN_LICENSE_PATHA license file outside the data folder
STATSRAVEN_RETENTION_DAYSDays to keep raw events, when not set in Settings
STATSRAVEN_WEB_MEMORY_ROWSWebsite rows kept in memory for fast reports. 2,000,000 unless set
STATSRAVEN_REQUEST_MEMORY_ROWSServer 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.