Events

Wire up a handler

LOAD events;

-- Required: a fully-qualified path to an executable
SET events_destination = '/usr/local/bin/event-handler.py';

-- Pick the event types (default is ['query_begin', 'query_end'])
SET events_types = ['query_begin', 'query_end'];

-- Optional: a tag included in every event line
SET events_session_name = 'analytics-replica';

-- Optional: don't block queries on the handler
SET events_async = TRUE;

Append every query to a daily log file

The smallest possible audit trail — one JSONL file per day, written by a shell handler:

#!/usr/bin/env bash
# /usr/local/bin/log-to-file.sh — append every event to a daily log
exec >> "/var/log/duckdb/events-$(date +%F).jsonl"
cat

SET events_destination = '/usr/local/bin/log-to-file.sh';
SET events_types       = ['query_begin', 'query_end'];

-- Every query now appends two lines to today's log file
SELECT count(*) FROM orders;

Page on query errors

query_end includes has_error, error_message, and error_type when a query fails. Filter in the handler and post to your alerting system:

#!/usr/bin/env python3
# /usr/local/bin/error-alerter.py
import json, sys, urllib.request

for line in sys.stdin:
    e = json.loads(line)
    if e.get('event') == 'query_end' and e.get('has_error'):
        urllib.request.urlopen(
            'https://alerts.example.com/page',
            data=line.encode(),
        )

SET events_destination = '/usr/local/bin/error-alerter.py';
SET events_types       = ['query_end'];
SET events_async       = TRUE;     -- don't let a slow alerter block queries

-- A failed query produces a query_end with has_error=true
SELECT * FROM nonexistent_table;

Track transaction lifecycle

Capture the full begin/commit/rollback sequence and group by transaction_id:

SET events_destination = '/usr/local/bin/txn-tracker.py';
SET events_types       = ['transaction_begin', 'transaction_commit', 'transaction_rollback'];

BEGIN;
INSERT INTO orders VALUES (1, 'widget', 99.99);
COMMIT;
-- Two events: transaction_begin and transaction_commit, same transaction_id.

A transaction_rollback carries has_error and error_message when the rollback was triggered by a failure.

Per-tenant attribution

When several DuckDB processes feed the same handler, tag each one and group downstream by session_name:

-- In the per-tenant startup script
SET events_destination  = '/usr/local/bin/multi-tenant-collector.py';
SET events_session_name = 'tenant-acme';
SET events_types        = ['query_begin', 'query_end'];
SET events_async        = TRUE;

# /usr/local/bin/multi-tenant-collector.py — bucket events by tenant
import json, sys, collections

counts = collections.Counter()
for line in sys.stdin:
    e = json.loads(line)
    if e.get('event') == 'query_end':
        counts[e.get('session_name', 'unknown')] += 1
        # ... ship to your metrics backend, or write to per-tenant files

Pair query_begin and query_end for latency

Both events share a query_id. Maintain a small in-memory map in the handler:

#!/usr/bin/env python3
# /usr/local/bin/latency-recorder.py
import json, sys
from datetime import datetime

starts = {}
for line in sys.stdin:
    e = json.loads(line)
    qid = e.get('query_id')
    ts  = datetime.fromisoformat(e['timestamp'].replace('Z', '+00:00'))

    if e['event'] == 'query_begin':
        starts[qid] = ts
    elif e['event'] == 'query_end' and qid in starts:
        latency_ms = (ts - starts.pop(qid)).total_seconds() * 1000
        print(f"qid={qid} latency_ms={latency_ms:.1f} error={e.get('has_error')}",
              flush=True)

SET events_destination = '/usr/local/bin/latency-recorder.py';
SET events_types       = ['query_begin', 'query_end'];

Fan out to multiple consumers

Only one events_destination is allowed. Point it at a small dispatcher that forks the stream:

#!/usr/bin/env bash
# /usr/local/bin/fanout.sh — split the event stream three ways
exec tee \
  >(cat >> /var/log/duckdb/events.jsonl) \
  >(curl -s -X POST -H 'content-type: application/x-ndjson' \
        --data-binary @- https://collector.example.com/ingest) \
  > /dev/null

SET events_destination = '/usr/local/bin/fanout.sh';

Re-applying configuration on session start

PRAGMAs do not persist across restarts (same caveat as the cronjob extension). Stash the four SET statements in a startup file that every connection runs:

-- /etc/duckdb/init.sql
LOAD events;
SET events_destination  = '/usr/local/bin/event-handler.py';
SET events_types        = ['query_begin', 'query_end'];
SET events_session_name = 'prod-replica-1';
SET events_async        = TRUE;

duckdb -init /etc/duckdb/init.sql /data/analytics.duckdb