diff --git a/docs/06-concepts/07-configuration.md b/docs/06-concepts/07-configuration.md index 03942dbe..7f45fa4b 100644 --- a/docs/06-concepts/07-configuration.md +++ b/docs/06-concepts/07-configuration.md @@ -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. | @@ -194,6 +197,9 @@ maxRequestSize: 524288 sessionLogs: persistentEnabled: true + cleanupInterval: 24h + retentionPeriod: 90d + retentionCount: 100000 consoleEnabled: true consoleLogFormat: json diff --git a/docs/06-concepts/09-logging.md b/docs/06-concepts/09-logging.md index 2e86a292..2afbea02 100644 --- a/docs/06-concepts/09-logging.md +++ b/docs/06-concepts/09-logging.md @@ -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 @@ -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: @@ -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 +```