@barry-rocks/sdk/logging

Structured logging for Node code: createLogger, redaction helpers that keep secrets out of log lines, flushAll, and setupGracefulShutdown. Logs are JSON lines that Barry’s tools read back.

import { … } from "@barry-rocks/sdk/logging";

API

Interfaces

CreateLoggerOptions

Properties

Property	Type	Description
transport?	"stdout" | "stderr" | "silent"	Where to send pino output: - “stdout” (default): writes JSON logs to stdout - “stderr”: writes JSON logs to stderr (use for MCP servers where stdout is reserved) - “silent”: no output

---

LogContext

Indexable

[key: string]: unknown

---

Logger

Methods

child()

child(context): Logger

Parameters

Parameter	Type
context	LogContext

Returns

Logger

debug()

debug(msg, context?): void

Parameters

Parameter	Type
msg	string
context?	LogContext

Returns

void

error()

error(msg, context?): void

Parameters

Parameter	Type
msg	string
context?	LogContext

Returns

void

flush()

flush(): Promise<void>

Returns

Promise<void>

info()

info(msg, context?): void

Parameters

Parameter	Type
msg	string
context?	LogContext

Returns

void

warn()

warn(msg, context?): void

Parameters

Parameter	Type
msg	string
context?	LogContext

Returns

void

---

LogRow

One parsed log line, as the store holds it.

ts is UNIX SECONDS. pino writes time in MILLISECONDS and every store in this bag is seconds; getting it wrong puts rows ~56,000 years out, where no window query will ever see them.

Properties

Property	Type
ctx	string
id	string
level	number
msg	string
service	string
ts	number

Type Aliases

LevelName

LevelName = keyof typeof LEVEL

The level names an emitter accepts, mapped to the numbers it must write.

---

LogLevel

LogLevel = "debug" | "info" | "warn" | "error"

Variables

CTX_OMIT

const CTX_OMIT: Set<string>

Fields promoted to columns; the rest stay in ctx.

name duplicates service; time/level/msg are columns; hostname and pid never varied usefully in practice.

---

LEVEL

const LEVEL: object

pino numeric levels, named so callers stop writing magic numbers.

Type Declaration

Name	Type	Default value
debug	20	20
error	50	50
fatal	60	60
info	30	30
trace	10	10
warn	40	40

Functions

createLogger()

createLogger(service, options?): Logger

Create a logger for a service

Parameters

Parameter	Type	Description
service	string	The service name (e.g., “web”, “slack”)
options?	CreateLoggerOptions	Optional configuration

Returns

Logger

A Logger instance

Example

import { createLogger } from "./index.js";

const log = createLogger("my-service");
log.info("Server started", { port: 3000 });
log.error("Request failed", { error: err.message, requestId: "abc" });

// For MCP servers (stdout reserved for protocol):
const log = createLogger("mcp-barry", { transport: "stderr" });

// Flush on shutdown
process.on("SIGTERM", async () => {
  await log.flush();
  process.exit(0);
});

---

flushAll()

flushAll(): Promise<void>

Flush all pending logs before process exit.

A no-op since the Axiom transport was removed: pino writes to stdout synchronously, so there is nothing buffered to drain. Kept because setupGracefulShutdown awaits it and services call that — and because a future async sink would need exactly this hook back.

Returns

Promise<void>

---

parseLine()

parseLine(line, service): LogRow | null

Parse one pino line.

Unlike errors.ts’s parser there is no level pre-filter – keeping level 30 is the entire point – so this runs JSON.parse on every line. That is the cost the offset tracking buys back: a pass sees only new bytes.

Parameters

Parameter	Type
line	string
service	string

Returns

LogRow | null

---

redact()

redact(obj): Record<string, unknown>

Logging for anything Barry runs: the Node emitter, and the line format it writes and the logs bag reads back.

Part of the kit, not of the logs bag: every bag and service writes log lines, and a bag that only wants to write one should not depend on the bag that collects and stores them. The logs bag keeps the store; Workers code uses @barry-rocks/sdk/logging/edge.

Parameters

Parameter	Type
obj	Record<string, unknown>

Returns

Record<string, unknown>

---

setupGracefulShutdown()

setupGracefulShutdown(server, log, options?): void

Setup graceful shutdown for a server with proper log flushing

Parameters

Parameter	Type	Description
server	{ close: (callback?) => void; }	The HTTP server to close on shutdown
server.close	(callback?) => void	-
log	Logger	Logger instance for shutdown logging
options	{ forceExitTimeout?: number; onShutdown?: () => Promise<void>; }	Optional configuration
options.forceExitTimeout?	number	-
options.onShutdown?	() => Promise<void>	-

Returns

void

References

redactContext

Renames and re-exports redact