---
title: "Events"
description: "LogbunEvent types, fields, and ops-relevant detail strings."
---

> Documentation Index
> Fetch the complete documentation index at: https://logbun-docs.abshahin.workers.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

Pass `onEvent` on `LogbunConfig`. Listener throws are swallowed (`safeEmit`) and never break the pipeline.

```ts
type LogbunEventType =
  | 'enqueue'
  | 'flush_ok'
  | 'flush_fail'
  | 'dlq'
  | 'drop'
  | 'truncated'
  | 'wal_fail'
  | 'bootstrap_fail'
  | 'prune_fail'
  | 'poison'
  | 'degraded'
  | 'stats'
  | 'limit';

interface LogbunEvent {
  type: LogbunEventType;
  tenantId?: string | null;
  error?: string;
  count?: number;
  detail?: string;
}
```

## `detail` values used by the engine

| `detail` | Typical `type` | Meaning |
|----------|----------------|---------|
| `unsafe_default_volatile` | `limit` | `mode` is volatile (including explicit) |
| `unsafe_default_require_tenant` | `limit` | `requireTenantId` left false and not DPT |
| `pre_ready_volatile` | `limit` | Durable-mode accept into the pre-ready buffer |
| `pre_ready_buffer_full` | `drop` | Pre-ready buffer at `maxPreReadyBuffer` |
| `max_active_tenants` | `dlq` or `drop` | New tenant key beyond cap |
| `max_tenant_id_bytes` | `drop` | Oversize `tenantId` |
| `require_tenant_id` | `drop` | Missing tenant when required |
| `get_tenant_id` | `drop` | `resolveTenantId` threw (`fire` path) |
| `wal_full` | `wal_fail` / `dlq` | Journal at cap; single-log DLQ fallback may still admit |
| `dlq_full` | — | DLQ at pending+processing cap |
| `recovery` | — | Recovery path |
| `durable_admission_scheduling` | `flush_fail` | Journal/DLQ committed; alarm scheduling failed |
| `maintenance_flush` | `flush_fail` | Flush phase of `runMaintenance` failed |
| `maintenance_dlq_scan` | `flush_fail` | DLQ scan phase failed |
| `maintenance_rearm` | `flush_fail` | `requestMaintenance` after a pass failed |
| `shutdown` | `drop` | `fire` after `shutdown()` |
| `shutdown_flush` | `flush_fail` | Flush during shutdown |
| `shutdown_maintenance` | `flush_fail` | In-flight maintenance during shutdown |
| `shutdown_deadline` | `limit` | `inflightFlushes > 0` after shutdown flush |
| `degraded` | `drop` | `fire` while degraded |
| `fire` | `drop` | Inner `fire` path threw |
| `reliability_get_stats` | `stats` | `getStatsDetailed` disk path threw |
| `prune_incomplete` | prune failure | SQLite/Turso batched prune hit the safety cap |

`onEvent` is the observability seam. It is not a delivery callback.

Source: https://logbun-docs.abshahin.workers.dev/reference/events/index.mdx