Squid SDK Logger

@subsquid/logger is Squid SDK’s structured logger. It is a small native implementation, not a Pino logger. The package exports a createPinoSink() adapter for applications that want to route its records through Pino. Legacy chain-specific processors inject a Logger into the handler context as ctx.log, bound to the sqd:processor:mapping namespace. Portal-native processors built with @subsquid/batch-processor do not inject a logger. Create one explicitly:

import {createLogger} from '@subsquid/logger'

const log = createLogger('sqd:processor', {component: 'indexer'})
  .child('mapping', {network: 'ethereum'})

log.info({blocks: 1}, 'processed batch')

Logger exposes the following logging levels, in order of increasing severity:

TRACE
DEBUG
INFO
WARN
ERROR
FATAL

By default, the logging level is set to INFO. Each level accepts either a message or an attributes object followed by a message:

processor.run(new TypeormDatabase(), async (ctx) => {
  ctx.log.trace('trace message')
  ctx.log.debug({block: ctx.blocks[0]?.header.height}, 'processing batch')
  ctx.log.info('info message')
  ctx.log.warn('warning message')
  ctx.log.error('error message')
  ctx.log.fatal('fatal message')
})

Child loggers

child() creates a logger that inherits its parent’s namespace and attributes. It has two overloads:

child(attributes: object): Logger
child(namespace: string, attributes?: object): Logger

A string appends a colon-separated namespace. An object adds structured fields without changing the namespace. Parent and child attributes are merged, with child attributes taking precedence:

const requestLog = createLogger('sqd:processor', {component: 'indexer'})
  .child('mapping', {network: 'ethereum'})
  .child({requestId: 'docs-check'})

requestLog.info({blocks: 1}, 'processed batch')
// Namespace: sqd:processor:mapping
// Attributes include component, network, requestId, and blocks.

Output format and destination

The built-in sinks always write to standard error. Output format is selected when @subsquid/logger is first imported:

Condition	Format
`FORCE_PRETTY_LOGGER=1` or another nonzero value	Human-readable pretty output
`FORCE_PRETTY_LOGGER=0`	One JSON object per line
Variable unset and standard error is a TTY	Human-readable pretty output
Variable unset and standard error is not a TTY	One JSON object per line

Set the variable before starting Node because the selection is made at module initialization:

FORCE_PRETTY_LOGGER=0 node lib/main.js

Overriding the log level

The log level can be overridden by setting a matching namespace selector to one of the SQD_TRACE, …, SQD_FATAL environment variables. To set the handler log level to DEBUG, set SQD_DEBUG to sqd:processor:mapping:

SQD_DEBUG=sqd:processor:mapping

The namespace selector supports wildcards, so you can also enable internal processor debug logs with:

SQD_DEBUG=sqd:processor*

Processor context loggers inherit the processor-level namespace sqd:processor.

Accessing logs of a deployed Squid

Processor logs can be inspected after the squid is deployed to Cloud:

sqd logs -n <name> -s <slot> -f --level=<level>

sqd logs -n <name> -t <tag> -f --level=<level>

For older version-based deployments...

…the slot string is v${version}, so use

sqd logs -n <name> -s v<version> -f --level=<level>

Check out the Slots and tags guide to learn more.

The available filters are info, warning, debug, and error. The error filter includes messages emitted through ctx.log.error, ctx.log.fatal, and ctx.log.trace. See CLI Reference or sqd logs --help for a full list of log options supported by SQD Cloud.

Overview

Pipes SDK

Squid SDK

Alternative clients

Child loggers

Output format and destination

Overriding the log level

Accessing logs of a deployed Squid

​Child loggers

​Output format and destination

​Overriding the log level

​Accessing logs of a deployed Squid

Child loggers

Output format and destination

Overriding the log level

Accessing logs of a deployed Squid