Logging
How to use Log.debug, info, warn, error for structured logging that surfaces in the Backfill dashboard and `backfill logs`.
Log is the only way to emit observability data from a script. Four levels, each takes a message and an optional structured-data object.
import { Log } from "@backfill-io/sdk";
Log.debug(message: string, data?: Record<string, any>): void;
Log.info(message: string, data?: Record<string, any>): void;
Log.warn(message: string, data?: Record<string, any>): void;
Log.error(message: string, data?: Record<string, any>): void;
Usage
Log.info("Tax calculated", {
invoiceId: ctx.entity.id,
subtotal,
taxAmount,
taxRate: rate,
});
The data object renders structurally in the dashboard and in backfill logs --follow. Keep keys short and stable — searches across log lines key off them.
What about console.log?
Works in the sandbox, but it isn’t the right channel. Only Log.* calls flow into the platform’s audit trail and the CLI’s log stream. Use Log for anything you want to inspect later.
Levels
| Level | Use for |
|---|---|
debug | Verbose detail useful while iterating. Filtered by default in the log view. |
info | Notable but expected events: a sync completed, a hook fired, a counter incremented. |
warn | Recoverable surprises: missing optional config, unknown enum values, retries kicking in. |
error | Things that failed and you’d want to chase. Always include enough context to reproduce. |
Constraints
- No log levels below
debug. There’s notrace. - Data must be JSON-serializable — no functions, symbols, or circular references.
- One call = one log line. No streaming.