diff --git a/docs-internal/logging-strategy.md b/docs-internal/logging-strategy.md index 07a2a099c..ead9ff910 100644 --- a/docs-internal/logging-strategy.md +++ b/docs-internal/logging-strategy.md @@ -1,6 +1,6 @@ # Fabro Logging Strategy -Fabro uses the `tracing` crate for structured, file-based logging. Logs write to `~/.fabro/logs/{prefix}.YYYY-MM-DD.log` (e.g. `cli.2026-04-06.log`, `server.2026-04-06.log`), rotated daily by `tracing-appender`. Logs older than 7 days are cleaned up on startup. Controlled by the `FABRO_LOG` env var (default: `info`). Logs are for **developers debugging issues after the fact** — they are not user-facing output. +Fabro uses the `tracing` crate for structured logging. By default, logs write to `~/.fabro/logs/{prefix}.YYYY-MM-DD.log` (e.g. `cli.2026-04-06.log`, `server.2026-04-06.log`), rotated daily by `tracing-appender`, and entries older than 7 days are cleaned up on startup. The server log destination is configurable: set `[server.logging].destination = "stdout"` (or `FABRO_LOG_DESTINATION=stdout`) to stream the server log to stdout instead — required for container deployments where the platform captures stdout. The level is controlled by `FABRO_LOG` (default: `info`). Logs are for **developers debugging issues after the fact** — they are not user-facing output. Production runs at INFO level. INFO should be low-volume and high-signal — the summary of what happened. When something goes wrong, developers enable `FABRO_LOG=debug` to get the full picture. DEBUG can be as verbose as needed since it's only turned on temporarily. diff --git a/docs/administration/server-configuration.mdx b/docs/administration/server-configuration.mdx index adfd958d4..a2ad8d0d2 100644 --- a/docs/administration/server-configuration.mdx +++ b/docs/administration/server-configuration.mdx @@ -234,11 +234,16 @@ Merge rules follow the normative matrix: `[run.inputs]` replaces wholesale, `[ru ### `[server.logging]` section -Configure the default server log level. Precedence: `FABRO_LOG` env var > `--debug` flag > `[server.logging].level` > `"info"`. +Configure the server log level and destination. | Key | Description | Default | |---|---|---| | `level` | Log level: `error`, `warn`, `info`, `debug`, `trace` | `"info"` | +| `destination` | Where server logs are written: `file` (rotated daily under `/logs/`) or `stdout` | `"file"` | + +Level precedence: `FABRO_LOG` env var > `--debug` flag > `[server.logging].level` > `"info"`. + +Destination precedence: `FABRO_LOG_DESTINATION` env var > `[server.logging].destination` > `"file"`. `stdout` is incompatible with daemon mode — use `fabro server start --foreground` (which is what container images do). The CLI has its own `[cli.logging]` section. @@ -404,3 +409,4 @@ Fabro resolves these from `process env -> server.env`. | Variable | Default | Description | |---|---|---| | `FABRO_LOG` | `info` | Log level: `error`, `warn`, `info`, `debug` | +| `FABRO_LOG_DESTINATION` | `file` | Server log destination: `file` or `stdout` (containers default to `stdout`) |