docs: Adding documentation for session logs output. (#179)

serverpod · Oct 18, 2024 · b99ffde · b99ffde
1 parent aa9ee78
commit b99ffde
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 0 deletions.
diff --git a/docs/06-concepts/07-configuration.md b/docs/06-concepts/07-configuration.md
@@ -31,6 +31,8 @@ There are three different ways to configure Serverpod: with environment variable
 | SERVERPOD_REDIS_USER                         | redis.user                           | -         | The user name for Redis authentication           |
 | SERVERPOD_REDIS_ENABLED                      | redis.enabled                        | false     | Indicates if Redis is enabled                    |
 | 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_CONSOLE_LOG_ENABLED        | sessionLogs.consoleEnabled           | -    | Enables or disables logging session data to the console. Defaults to `true` if no database is configured, otherwise `false`. |
 
 | Environment variable               | Passwords file  | Default | Description                                                       |
 |------------------------------------|-----------------|---------|-------------------------------------------------------------------|
@@ -73,6 +75,10 @@ redis:
   port: 8091
 
 maxRequestSize: 524288
+
+sessionLogs:
+  persistentEnabled: true
+  consoleEnabled: true
 ```
 
 ### Passwords file example

diff --git a/docs/06-concepts/09-logging.md b/docs/06-concepts/09-logging.md
@@ -19,6 +19,43 @@ session.log(
 
 Log entries are stored in the following tables of the database: `serverpod_log` for text messages, `serverpod_query_log` for queries, and `serverpod_session_log` for completed sessions. Optionally, it's possible to pass a log level with the message to filter out messages depending on the server's runtime settings.
 
+### Controlling Session Logs with Environment Variables or Configuration Files
+
+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.
+
+#### Environment Variables
+
+- `SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED`: Controls whether session logs are written to the database.
+- `SERVERPOD_SESSION_CONSOLE_LOG_ENABLED`: Controls whether session logs are output to the console.
+
+#### Configuration File Example
+
+You can also configure logging behavior directly in the configuration file:
+
+```yaml
+sessionLogs:
+  persistentEnabled: true   # Logs are stored in the database
+  consoleEnabled: true      # Logs are output to the console
+```
+
+### Default Behavior for Session Logs
+
+By default, session logging behavior depends on whether the project has database support:
+
+- **When a database is present**
+
+  - `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
+
+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
 
 The Serverpod GUI is coming soon, making it easy to read, search, and configure the logs.