Event logging
This commit is contained in:
249
EVENT_LOGGER.md
Normal file
249
EVENT_LOGGER.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# Event Logger Configuration
|
||||
|
||||
The event logger allows you to persist all system events to various storage targets for auditing, debugging, and analytics.
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the `event_logger` section to your `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"event_logger": {
|
||||
"enabled": true,
|
||||
"targets": ["file", "sqlite", "postgres"],
|
||||
"file_dir": "./data/events",
|
||||
"table_name": "event_logs"
|
||||
},
|
||||
"database": {
|
||||
"type": "postgres",
|
||||
"host": "localhost",
|
||||
"port": 5432,
|
||||
"username": "whatshooked",
|
||||
"password": "your_password_here",
|
||||
"database": "whatshooked",
|
||||
"sqlite_path": "./data/events.db"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### event_logger
|
||||
|
||||
- **enabled** (boolean): Enable or disable event logging
|
||||
- Default: `false`
|
||||
|
||||
- **targets** (array): List of storage targets to use. Options:
|
||||
- `"file"` - Store events as JSON files in organized directories
|
||||
- `"sqlite"` - Store events in a local SQLite database
|
||||
- `"postgres"` or `"postgresql"` - Store events in PostgreSQL database
|
||||
|
||||
- **file_dir** (string): Base directory for file-based event storage
|
||||
- Default: `"./data/events"`
|
||||
- Events are organized as: `{file_dir}/{event_type}/{YYYYMMDD}/{HH_MM_SS}_{event_type}.json`
|
||||
|
||||
- **table_name** (string): Database table name for storing events
|
||||
- Default: `"event_logs"`
|
||||
|
||||
### database
|
||||
|
||||
Database configuration is shared with the event logger when using `sqlite` or `postgres` targets.
|
||||
|
||||
For **SQLite**:
|
||||
- `sqlite_path`: Path to SQLite database file (e.g., `"./data/events.db"`)
|
||||
- If not specified, defaults to `"./data/events.db"`
|
||||
|
||||
For **PostgreSQL**:
|
||||
- `type`: `"postgres"`
|
||||
- `host`: Database host (e.g., `"localhost"`)
|
||||
- `port`: Database port (e.g., `5432`)
|
||||
- `username`: Database username
|
||||
- `password`: Database password
|
||||
- `database`: Database name
|
||||
|
||||
## Storage Targets
|
||||
|
||||
### File Target
|
||||
|
||||
Events are stored as JSON files in an organized directory structure:
|
||||
|
||||
```
|
||||
./data/events/
|
||||
├── message.received/
|
||||
│ ├── 20231225/
|
||||
│ │ ├── 14_30_45_message.received.json
|
||||
│ │ ├── 14_31_12_message.received.json
|
||||
│ │ └── 14_32_00_message.received.json
|
||||
│ └── 20231226/
|
||||
│ └── 09_15_30_message.received.json
|
||||
├── message.sent/
|
||||
│ └── 20231225/
|
||||
│ └── 14_30_50_message.sent.json
|
||||
└── whatsapp.connected/
|
||||
└── 20231225/
|
||||
└── 14_00_00_whatsapp.connected.json
|
||||
```
|
||||
|
||||
Each file contains the complete event data:
|
||||
```json
|
||||
{
|
||||
"type": "message.received",
|
||||
"timestamp": "2023-12-25T14:30:45Z",
|
||||
"data": {
|
||||
"account_id": "acc1",
|
||||
"from": "+1234567890",
|
||||
"message": "Hello, world!",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SQLite Target
|
||||
|
||||
Events are stored in a SQLite database with the following schema:
|
||||
|
||||
```sql
|
||||
CREATE TABLE event_logs (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
event_type TEXT NOT NULL,
|
||||
timestamp DATETIME NOT NULL,
|
||||
data TEXT NOT NULL,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
CREATE INDEX idx_event_logs_type_timestamp
|
||||
ON event_logs(event_type, timestamp);
|
||||
```
|
||||
|
||||
### PostgreSQL Target
|
||||
|
||||
Events are stored in PostgreSQL with JSONB support for efficient querying:
|
||||
|
||||
```sql
|
||||
CREATE TABLE event_logs (
|
||||
id SERIAL PRIMARY KEY,
|
||||
event_type VARCHAR(100) NOT NULL,
|
||||
timestamp TIMESTAMP NOT NULL,
|
||||
data JSONB NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
CREATE INDEX idx_event_logs_type_timestamp
|
||||
ON event_logs(event_type, timestamp);
|
||||
```
|
||||
|
||||
## Event Types
|
||||
|
||||
The following event types are logged:
|
||||
|
||||
### WhatsApp Connection Events
|
||||
- `whatsapp.connected`
|
||||
- `whatsapp.disconnected`
|
||||
- `whatsapp.pair.success`
|
||||
- `whatsapp.pair.failed`
|
||||
- `whatsapp.qr.code`
|
||||
- `whatsapp.qr.timeout`
|
||||
- `whatsapp.qr.error`
|
||||
- `whatsapp.pair.event`
|
||||
|
||||
### Message Events
|
||||
- `message.received`
|
||||
- `message.sent`
|
||||
- `message.failed`
|
||||
- `message.delivered`
|
||||
- `message.read`
|
||||
|
||||
### Hook Events
|
||||
- `hook.triggered`
|
||||
- `hook.success`
|
||||
- `hook.failed`
|
||||
|
||||
## Examples
|
||||
|
||||
### Enable File Logging Only
|
||||
```json
|
||||
{
|
||||
"event_logger": {
|
||||
"enabled": true,
|
||||
"targets": ["file"],
|
||||
"file_dir": "./logs/events"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enable SQLite Logging Only
|
||||
```json
|
||||
{
|
||||
"event_logger": {
|
||||
"enabled": true,
|
||||
"targets": ["sqlite"]
|
||||
},
|
||||
"database": {
|
||||
"sqlite_path": "./data/whatshooked.db"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enable Multiple Targets
|
||||
```json
|
||||
{
|
||||
"event_logger": {
|
||||
"enabled": true,
|
||||
"targets": ["file", "sqlite", "postgres"],
|
||||
"file_dir": "./data/events",
|
||||
"table_name": "event_logs"
|
||||
},
|
||||
"database": {
|
||||
"type": "postgres",
|
||||
"host": "localhost",
|
||||
"port": 5432,
|
||||
"username": "whatshooked",
|
||||
"password": "securepassword",
|
||||
"database": "whatshooked",
|
||||
"sqlite_path": "./data/events.db"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Querying Events
|
||||
|
||||
### SQLite Query Examples
|
||||
|
||||
```sql
|
||||
-- Get all message events from the last 24 hours
|
||||
SELECT * FROM event_logs
|
||||
WHERE event_type LIKE 'message.%'
|
||||
AND timestamp > datetime('now', '-1 day')
|
||||
ORDER BY timestamp DESC;
|
||||
|
||||
-- Count events by type
|
||||
SELECT event_type, COUNT(*) as count
|
||||
FROM event_logs
|
||||
GROUP BY event_type
|
||||
ORDER BY count DESC;
|
||||
```
|
||||
|
||||
### PostgreSQL Query Examples
|
||||
|
||||
```sql
|
||||
-- Get all message events with specific sender
|
||||
SELECT * FROM event_logs
|
||||
WHERE event_type = 'message.received'
|
||||
AND data->>'from' = '+1234567890'
|
||||
ORDER BY timestamp DESC;
|
||||
|
||||
-- Find events with specific data fields
|
||||
SELECT event_type, timestamp, data
|
||||
FROM event_logs
|
||||
WHERE data @> '{"account_id": "acc1"}'
|
||||
ORDER BY timestamp DESC
|
||||
LIMIT 100;
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **File Target**: Suitable for low to medium event volumes. Easy to backup and archive.
|
||||
- **SQLite Target**: Good for single-server deployments. Supports moderate event volumes.
|
||||
- **PostgreSQL Target**: Best for high-volume deployments and complex queries. Supports concurrent access.
|
||||
|
||||
You can enable multiple targets simultaneously to balance immediate access (file) with queryability (database).
|
||||
Reference in New Issue
Block a user