Running Metric

The installer creates a directory containing compose.yml, metric.toml, symbolicator.yml and .env. Run all commands on this page from that directory.

Start and stop

Start Metric and wait until it is healthy:

docker compose up -d --wait --wait-timeout 120

Stop Metric without deleting data:

docker compose down

Do not add -v. It deletes the MongoDB and file-storage volumes.

Logs and status

docker compose ps
docker compose logs -f metric

Medium and High can also show Symbolicator logs:

docker compose logs -f symbolicator

Metric writes JSON logs. Passwords, tokens, DSNs and private event data should still be removed before sharing logs.

Health endpoints:

curl http://localhost:4001/live
curl http://localhost:4001/ready

/live confirms that the process event loop is running. /ready confirms that Metric, its target database schema and its required workers are ready. During an automatic schema migration, /live stays at HTTP 200 while /ready returns HTTP 503. Browser navigation shows bounded step progress; API and SDK requests return HTTP 503 with Retry-After until runtime activation.

Metric intentionally does not expose a Prometheus endpoint in the current product scope. The /metrics browser path is a page in the web interface, not a monitoring endpoint.

For a long-running installation, monitor /ready, docker stats, repeated container restarts and free disk space in the data and active cache volumes.

HTTPS proxy

The supplied profiles allow sign-in over HTTP, including from another machine. Use an HTTPS proxy for a public or long-running installation because HTTP does not encrypt passwords, session cookies or application data. You do not need a second Compose file.

If the proxy sends X-Forwarded-For, add the proxy address or network to server.trusted_proxies in metric.toml. Configure the proxy to replace any X-Forwarded-For value received from the internet.

Restart Metric after changing the configuration:

docker compose up -d --wait --wait-timeout 120

Backups

Metric does not include its own backup command. Follow Manual backup and restore for a database-scoped MongoDB dump and either local BlobStore or metadata-preserving S3 copies. The procedure stops Metric, does not lock the whole MongoDB server, and explains the remaining TTL consistency limit.

Keep MongoDB, BlobStore, configuration and installation secrets together. Session Replay especially depends on both database descriptions and recording segments. Test restoration into an empty, separate installation; readiness alone does not prove that every file survived. The Symbolicator cache is rebuildable and can be omitted from backups.

Symbolicator

Medium and High start Symbolicator automatically. It resolves native and JavaScript stack traces using debug files and source maps uploaded to Metric. Its API port is available only inside the Compose network. Min and Low omit it and retain raw frames instead.

The symbolicator-cleanup container removes expired cache files. The cache is stored in metric_symbolicator-cache and may be deleted and rebuilt without losing Metric data.

After a successful startup, Metric can continue storing ordinary error events during a temporary Symbolicator outage. Check both logs when symbolication fails:

docker compose logs --tail=200 metric symbolicator

Symbolicator is a third-party component under FSL-1.1-MIT. Review the third-party notice.

Resource profile

The selected profile is recorded in .env:

grep '^METRIC_PROFILE=' .env
docker stats

The installer preserves an existing .env and metric.toml, including when it is rerun from inside the installation directory. If MongoDB data exists but .env is missing, it stops instead of generating an incompatible password. Rerunning with another METRIC_PROFILE does not change a live installation. Before changing retention or resource limits, back up the data and compare the complete target profile in Configuration.

Updates

The current binary requires schema generation 21 exactly before starting application workers. Metric automatically migrates complete generation-19 and generation-20 databases to generation 21. Earlier generations have no supported transition chain.

Do not edit schema_meta, delete MongoDB collections or remove Docker volumes after a schema error. Follow Update Metric.