# Service logs

Both services emit one JSON object per line to stderr through `slog`.
Each record includes a timestamp, level, message, and service name.

`PROVENANCE_LOG_LEVEL` selects `debug`, `info`, `warn`, or `error`.
The default is `info`. An invalid level stops service startup.

## Debug configuration

Add this assignment to your private environment or `.env`:

```dotenv
PROVENANCE_LOG_LEVEL=debug
```

Stop the development launcher.
Start the launcher with its updated environment:

```sh
direnv exec . nix run .#services
```

NixOS exposes `services.provenance.appview.logLevel` and `services.provenance.ui.logLevel`.
The development service module exposes `logLevel` and accepts the environment override.

## Log levels

| Level | Records |
| --- | --- |
| Info | Safe startup configuration, database open, replay attempts, phase changes, archive plans, segment starts, completion, and shutdown |
| Info | Replay progress once per minute, including a checkpoint and byte/event deltas during an idle download |
| Warn | Upstream request/read errors, failed HTTP statuses, cooldown-related retries, and stream reconnect decisions |
| Error | Terminal replay errors with their causes, failed phase, and durable checkpoint |
| Debug | HTTP request duration, external queue wait, response status/length, bytes read, archive segment/block/range identifiers, redirects, and committed batches |

Duration and backoff fields use nanoseconds. Byte fields use bytes.
Replay counters in logs cover the current worker run. The checkpoint persists in SQLite.
A zero checkpoint delta with a positive byte delta describes a download before its first batch commit.

Terminal errors include an `error.message` and the wrapped `error.types`.
The message preserves causes that an indexing wrapper otherwise hides.
Public status responses and metrics retain sanitized error categories only.

## Data restrictions

Request logs omit authorization headers, cookies, URL queries, fragments, bodies, and record contents.
Diagnostic fields include HTTP ranges, response lengths, and retry timing.
The output handler redacts configured credentials, bearer tokens, credential assignments, and sensitive attributes.
Archive identifiers come from a fixed query-parameter allowlist, not the complete query string.
Error fields have a 4096-byte limit after redaction.
Error messages retain provider diagnostics after redaction.
Before you share logs outside the operator team, review them.

Debug logs can produce substantial output during an archive import.
Use debug level for diagnosis. Then restore info level.