Documentation
Advanced
Logging

Logging

Ponder produces logs to help you understand and debug your application.

Dev server logs screenshot

Dev server terminal UI (v0.0.75).

Log level

There are two ways to configure the minimum log level. If specified, the environment variable takes precedence over the CLI flag.

  • Set the PONDER_LOG_LEVEL environment variable
  • Use the --log-level <LEVEL>, -v (debug) or -vv (trace) CLI option
.env.local
PONDER_LOG_LEVEL=trace
bash
ponder dev --log-level warn
# or, use the shortcut flag for debug
ponder dev -v

Levels

Log levelExample
silent
errorUnrecoverable RPC error, SQL constraint violation
warnReorg reconciliation, malformed config
info (default)Indexing progress, real-time block processing
debugInternal service lifecycle events
traceQuery-level database logs

User logs

Logs produced by your code (e.g. console.log statements in ponder.config.ts or indexing functions) will always be written to the console. Note that Ponder does catch errors thrown by your code and emits an error log including the original error message and stack trace.

Log format

Use the --log-format <FORMAT> CLI option to set the log format.

The auto-updating terminal UI is always enabled during development (ponder dev) regardless of the log level or format.

Pretty (default)

bash
ponder start --log-format pretty
bash
11:54:36 AM INFO  build      Using PGlite database at .ponder/pglite (default)
11:54:36 AM INFO  database   Created table 'Account' in 'public.db'
11:54:36 AM INFO  server     Started listening on port 42069
11:54:36 AM INFO  historical Started syncing 'optimism' logs for 'weth9' with 0.0% cached
11:54:36 AM INFO  historical Started syncing 'base' logs for 'weth9' with 0.0% cached
11:54:36 AM INFO  historical Started syncing 'polygon' logs for 'weth9' with 0.0% cached

JSON

bash
ponder start --log-format json

The JSON log format emits newline-delimited JSON objects with properties level, time, service, msg, and (optionally) error.

bash
{"level":30,"time":1717170664426,"service":"build","msg":"Using PGlite database at .ponder/pglite (default)"}
{"level":30,"time":1717170664454,"service":"database","msg":"Created table 'Account' in 'public.db'"}
{"level":30,"time":1717170664458,"service":"server","msg":"Started listening on port 42069"}
{"level":30,"time":1717170664625,"service":"historical","msg":"Started syncing 'base' logs for 'weth9' with 0.0% cached"}
{"level":30,"time":1717170664628,"service":"historical","msg":"Started syncing 'optimism' logs for 'weth9' with 0.0% cached"}
{"level":30,"time":1717170664683,"service":"historical","msg":"Started syncing 'polygon' logs for 'weth9' with 0.0% cached"}
FoundryMetrics