Telemetry

Structured logging, metrics, and traces with optional persistence.

Chimpbase provides structured logging, metrics, and tracing through the context. Telemetry can optionally be persisted to dedicated internal streams.

Logging

ctx.log.debug("processing started", { orderId: 123 });
ctx.log.info("order created", { orderId: 123, total: 99.99 });
ctx.log.warn("inventory low", { sku: "ABC", remaining: 2 });
ctx.log.error("payment failed", { orderId: 123, reason: "declined" });

Metrics

ctx.metric("orders.created", 1, { region: "us-east" });
ctx.metric("payment.amount", 99.99, { currency: "USD" });

Tracing

const span = ctx.trace("process-order");
span.setAttribute("orderId", "123");
// ... do work

Telemetry Persistence

By default, telemetry is in-memory only. To persist telemetry to the database, enable it in the configuration:

const chimpbase = await createChimpbase({
  storage: { engine: "postgres", url: process.env.DATABASE_URL! },
  telemetry: {
    persist: {
      logs: true,
      metrics: true,
      traces: true,
      minLevel: "warn", // Only persist warn and error logs
    },
  },
});

When enabled, records are buffered during handler execution and batch-appended to dedicated streams:

  • _chimpbase.logs
  • _chimpbase.metrics
  • _chimpbase.traces

Per-Handler Overrides

Override telemetry settings for specific handlers:

const noisyAction = action({
  args: v.object({ id: v.string() }),
  telemetry: { persist: { logs: false } },
  async handler(ctx, input) {
    // Logs from this action won't be persisted
  },
});

Automatic Cleanup

A built-in cleanup cron (__chimpbase.telemetry.cleanup) can be configured with retention periods to automatically prune old telemetry data.

State & Storage
Key-value store, collections, and append-only streams.
Hono
Use Hono as your HTTP framework with Chimpbase.