Skip to content

docs: Add docs for the logs purging configurations #408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcelomendoncasoares merged 2 commits into from
Feb 3, 2026
Merged

docs: Add docs for the logs purging configurations #408

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
272184c
docs: Add docs for the logs purging configurations
marcelomendoncasoares Jan 30, 2026
7631c29
fix: Add a note referencing the default env var values
marcelomendoncasoares Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/06-concepts/07-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,9 @@ These can be separately declared for each run mode in the corresponding yaml fil
| SERVERPOD_REDIS_REQUIRE_SSL | redis.requireSsl | false | Indicates if SSL is required for the Redis connection |
| SERVERPOD_MAX_REQUEST_SIZE | maxRequestSize | 524288 | The maximum size of requests allowed in bytes |
| SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED | sessionLogs.persistentEnabled | - | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`. |
| SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL | sessionLogs.cleanupInterval | 24h | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging. |
| SERVERPOD_SESSION_LOG_RETENTION_PERIOD | sessionLogs.retentionPeriod | 90d | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup. |
| SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | 100000 | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. |
| SERVERPOD_SESSION_CONSOLE_LOG_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured, otherwise `false`. |
| SERVERPOD_SESSION_CONSOLE_LOG_FORMAT | sessionLogs.consoleLogFormat | json | The format for console logging of session data. Valid options are `text` and `json`. Defaults to `text` for run mode `development`, otherwise `json`. |
| SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCallExecutionEnabled | true | Enables or disables the execution of future calls. |
Expand Down Expand Up @@ -194,6 +197,9 @@ maxRequestSize: 524288

sessionLogs:
persistentEnabled: true
cleanupInterval: 24h
retentionPeriod: 90d
retentionCount: 100000
consoleEnabled: true
consoleLogFormat: json

Expand Down
47 changes: 43 additions & 4 deletions docs/06-concepts/09-logging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,16 @@ Log entries are stored in the following tables of the database: `serverpod_log`

You can control whether session logs are written to the database, the console, both, or neither, using environment variables or configuration files. **Environment variables take priority** over configuration file settings if both are provided.

For the default values when environment variables are not set, see the [default behavior for session logs](#default-behavior-for-session-logs).

#### Environment Variables

- `SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED`: Controls whether session logs are written to the database.
- `SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL`: How often to run the log cleanup job (duration string, e.g. `6h`, `24h`). Set to empty to disable automated purging.
- `SERVERPOD_SESSION_LOG_RETENTION_PERIOD`: How long to keep session log entries (duration string, e.g. `30d`, `6h`). Set to empty or omit to use the default (90 days).
- `SERVERPOD_SESSION_LOG_RETENTION_COUNT`: Maximum number of session log entries to keep. Set to empty or omit to use the default (100,000).
- `SERVERPOD_SESSION_CONSOLE_LOG_ENABLED`: Controls whether session logs are output to the console.
- `SERVERPOD_SESSION_CONSOLE_LOG_FORMAT`: The format for console logging (`text` or `json`). See [configuration](./configuration).

#### Configuration File Example

Expand All @@ -35,9 +41,14 @@ You can also configure logging behavior directly in the configuration file:
```yaml
sessionLogs:
persistentEnabled: true # Logs are stored in the database
cleanupInterval: 6h # Run cleanup every 6 hours
retentionPeriod: 30d # Keep entries for 30 days
retentionCount: 5000 # Keep at most 5,000 entries
consoleEnabled: true # Logs are output to the console
```

Duration strings for the cleanup interval and retention period use the same format as in [models](./models#duration): e.g. `30d`, `6h`, `1d 2h 30min`.

### Default Behavior for Session Logs

By default, session logging behavior depends on whether the project has database support:
Expand All @@ -46,18 +57,46 @@ By default, session logging behavior depends on whether the project has database

- `persistentEnabled` is set to `true`, meaning logs are stored in the database.
- `consoleEnabled` is set to `false` by default, meaning logs are not printed to the console unless explicitly enabled.

- **When no database is present**

- `persistentEnabled` is set to `false` since persistent logging requires a database.
- `consoleEnabled` is set to `true`, meaning logs are printed to the console by default.

### Important: Persistent Logging Requires a Database

:::warning
If `persistentEnabled` is set to `true` but **no database is configured**, a `StateError` will be thrown. Persistent logging requires database support, and Serverpod ensures that misconfigurations are caught early by raising this error.
:::

:::info

You can use the companion app **[Serverpod Insights](../tools/insights)** to read, search, and configure the logs.
:::

#### Log retention and automated purging

Since log entries are stored in the database when persistent logging is enabled, the logs table can grow without bound if not purged. Serverpod can automatically purge logs based on configurable retention policies to prevent unchecked storage growth.

##### Defaults values

- **Cleanup interval**: 24 hours — the cleanup job runs once per day.
- **Retention period**: 90 days — removes entries older than this.
- **Retention count**: 100,000 entries — removes entries that exceed this count.

If both time-based (retention period) and count-based (retention count) limits are set, entries are removed if they are either too old or beyond the maximum count, whichever is reached first.

:::note
Automatic cleanup is only available when persistent logging is enabled and the cleanup interval is configured.
:::

##### Customizing retention policies

All three settings are optional and can be set to `null` to disable the respective policy. If the `cleanupInterval` is set to `null`, no purging will run regardless of the other settings, and log tables can grow without bound until you run cleanup manually or re-enable the interval.

Configure retention and cleanup via [environment variables](#environment-variables) or the [configuration file](#configuration-file-example). For example, to keep 30 days and at most 5,000 entries, with cleanup every 6 hours:

```yaml
sessionLogs:
persistentEnabled: true
cleanupInterval: 6h
retentionPeriod: 30d
retentionCount: 5000
```