diff options
Diffstat (limited to 'website/src/en/docs/features/message-logging.md')
| -rw-r--r-- | website/src/en/docs/features/message-logging.md | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/website/src/en/docs/features/message-logging.md b/website/src/en/docs/features/message-logging.md index b2ea1e6..5e929bc 100644 --- a/website/src/en/docs/features/message-logging.md +++ b/website/src/en/docs/features/message-logging.md @@ -1,3 +1,94 @@ --- layout: doc --- + +# Message Logging + +Records channel chat messages in NDJSON (Newline Delimited JSON) format to files. This feature is available when channel chat is enabled and is turned on by default. + +## Configuration + +```yaml +# config.yml +features: + channelChat: + enabled: true + messageLogging: + enabled: true + retentionDays: 30 + maxFileSizeMB: 100 +``` + +| Setting Key | Default | Description | +|-------------|---------|-------------| +| `enabled` | `true` | Enable message logging | +| `retentionDays` | `30` | Number of days to retain log files (`0` for unlimited retention) | +| `maxFileSizeMB` | `100` | Maximum size of a single log file (MB) | + +## Log File Format + +Log files are saved in the `plugins/LunaticChat/logs/` directory. Each line is a single JSON object. + +### File Naming + +``` +channel-messages-YYYY-MM-dd.json +``` + +When the file size exceeds `maxFileSizeMB`, a new file with a suffix is created. + +``` +channel-messages-2026-04-05.json # Base file +channel-messages-2026-04-05-1.json # On size overflow +channel-messages-2026-04-05-2.json # On further overflow +``` + +### Entry Format + +Each line has the following JSON structure. + +```json +{ + "timestamp": "2026-04-05T14:23:45.123Z", + "playerId": "550e8400-e29b-41d4-a716-446655440000", + "playerName": "Steve", + "channelId": "general", + "message": "Hello everyone!" +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `timestamp` | String | ISO 8601 timestamp (UTC) | +| `playerId` | String | Player UUID | +| `playerName` | String | Player display name | +| `channelId` | String | ID of the channel the message was sent to | +| `message` | String | Message content | + +## File Rotation + +- **Daily rotation**: A new file is created when the date changes +- **Size rotation**: Switches to a suffixed file when `maxFileSizeMB` is exceeded +- **Automatic cleanup**: Log files older than the number of days specified by `retentionDays` are automatically deleted (no deletion when set to `0`) + +## Usage Examples + +Since the format is NDJSON, you can easily filter and aggregate logs using tools like `jq`. + +### Extract Messages from a Specific Channel + +```bash +jq 'select(.channelId == "general")' channel-messages-2026-04-05.json +``` + +### Extract Messages from a Specific Player + +```bash +jq 'select(.playerName == "Steve")' channel-messages-2026-04-05.json +``` + +### Count Messages by Channel + +```bash +jq -s 'group_by(.channelId) | map({channel: .[0].channelId, count: length})' channel-messages-2026-04-05.json +``` |