@polkadot-apps/logger

Structured, namespace-filtered logging for the @polkadot-apps ecosystem.

Install

pnpm add @polkadot-apps/logger
# or
npm install @polkadot-apps/logger
Copy

No additional dependencies required.

Quick Start

import { createLogger } from "@polkadot-apps/logger";

const log = createLogger("my-module");

log.error("connection failed", { endpoint: "wss://rpc.polkadot.io" });
log.warn("retry limit approaching", { attempt: 3, max: 5 });
log.info("connected", { chain: "Polkadot" });
log.debug("block received", { number: 21_000_000 });
Copy

The default log level is "warn", so only error and warn messages are emitted out of the box.

Basic Usage

Each logger is scoped to a namespace. Namespaces appear in every log entry, making it straightforward to trace output back to the originating module.

import { createLogger } from "@polkadot-apps/logger";

const rpcLog = createLogger("rpc");
const txLog = createLogger("tx-pool");

rpcLog.info("subscribed to new heads");
txLog.debug("pending extrinsic", { hash: "0xabc..." });
Copy

Configuration

Use configure to change the global log level, filter by namespace, or install a custom handler.

import { configure } from "@polkadot-apps/logger";

configure({
  level: "debug", // show all messages
});
Copy

Set Level and Namespace Filter

import { configure } from "@polkadot-apps/logger";

configure({
  level: "info",
  namespaces: ["rpc", "tx-pool"], // only these namespaces emit
});
Copy

Environment Variables

You can configure logging without code changes by setting environment variables before the process starts.

Environment variables are read once at initialization. Calling configure overrides them.

Custom Handlers

Replace the default console output with any function that accepts a LogEntry.

import { configure } from "@polkadot-apps/logger";
import type { LogEntry } from "@polkadot-apps/logger";

configure({
  handler: (entry: LogEntry) => {
    // Send to an external service
    fetch("/api/logs", {
      method: "POST",
      body: JSON.stringify(entry),
    });
  },
});
Copy

Structured JSON Logging

import { configure } from "@polkadot-apps/logger";

configure({
  level: "debug",
  handler: (entry) => {
    process.stdout.write(JSON.stringify(entry) + "\n");
  },
});
Copy

Namespace Filtering

When namespaces is set, only loggers whose namespace appears in the list produce output. All other loggers are silenced regardless of log level.

import { configure, createLogger } from "@polkadot-apps/logger";

configure({ level: "debug", namespaces: ["rpc"] });

const rpcLog = createLogger("rpc");
const uiLog = createLogger("ui");

rpcLog.debug("this is emitted"); // visible
uiLog.debug("this is silenced"); // filtered out
Copy

API

Types

/** Log severity levels, ordered from most to least severe. */
type LogLevel = "error" | "warn" | "info" | "debug";

/** A single structured log entry. */
interface LogEntry {
  level: LogLevel;
  namespace: string;
  message: string;
  data?: unknown;
  timestamp: number;
}

/** A function that receives log entries for custom output. */
type LogHandler = (entry: LogEntry) => void;

/** Global logger configuration. */
interface LoggerConfig {
  /** Minimum severity to emit. Default: "warn". */
  level?: LogLevel;
  /** When set, only matching namespaces produce output. */
  namespaces?: string[];
  /** Replace the default console handler. */
  handler?: LogHandler;
}

/** A namespaced logger instance. */
interface Logger {
  error(message: string, data?: unknown): void;
  warn(message: string, data?: unknown): void;
  info(message: string, data?: unknown): void;
  debug(message: string, data?: unknown): void;
}
Copy

License

Apache-2.0