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

# Squid SDK Logger

> Configure Squid SDK logs, namespaces, levels, child loggers, and output formats.

[`@subsquid/logger`](https://github.com/subsquid/squid-sdk/tree/master/util/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.

`SubstrateBatchProcessor` injects a `Logger` into the [handler context](./substrate-processor/architecture#batch-context) as `ctx.log`, bound to the `sqd:processor:mapping` namespace. Create one explicitly:

```typescript theme={"system"}
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:

```typescript theme={"system"}
import {createLogger} from '@subsquid/logger'

const log = createLogger('sqd:processor:mapping')

log.trace('trace message')
log.debug({block: 18_000_000}, 'processing batch')
log.info('info message')
log.warn('warning message')
log.error('error message')
log.fatal('fatal message')
```

## Child loggers

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

```typescript theme={"system"}
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:

```typescript theme={"system"}
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:

```bash theme={"system"}
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`:

```bash theme={"system"}
SQD_DEBUG=sqd:processor:mapping
```

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

```bash theme={"system"}
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:

```bash theme={"system"}
sqd logs -n <name> -s <slot> -f --level=<level>
```

or

```bash theme={"system"}
sqd logs -n <name> -t <tag> -f --level=<level>
```

<Accordion title="For older version-based deployments...">
  ...the slot string is `v${version}`, so use

  ```bash theme={"system"}
  sqd logs -n <name> -s v<version> -f --level=<level>
  ```

  Check out the [Slots and tags guide](/en/cloud/resources/slots-and-tags) to learn more.
</Accordion>

The available filters are `info`, `warning`, `debug`, and `error`. The `error` filter includes messages emitted at the `error`, `fatal`, and `trace` levels.

See [CLI Reference](/en/cloud/reference/cli/logs) or `sqd logs --help` for a full list of log options supported by SQD Cloud.