whatshooked/EVENT_LOGGER.md

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:

{
  "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:

{
  "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:

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:

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

{
  "event_logger": {
    "enabled": true,
    "targets": ["file"],
    "file_dir": "./logs/events"
  }
}

Enable SQLite Logging Only

{
  "event_logger": {
    "enabled": true,
    "targets": ["sqlite"]
  },
  "database": {
    "sqlite_path": "./data/whatshooked.db"
  }
}

Enable Multiple Targets

{
  "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

-- 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

-- 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).