Logging
Structured log entries emitted during job and worker lifecycle events.
Queuert emits structured log entries for every lifecycle event — worker start/stop, job creation, attempts, failures, completions, chain lifecycle, blockers, and adapter errors. Logging is part of queuert core and does not require the @queuert/otel package.
Setup
Pass a log function (Log) to createClient to receive log entries. createConsoleLog() is the built-in logger:
src/index.ts
const log = createConsoleLog();
const client = createClient({
stateAdapter,
log,
jobTypes,
});src/log.ts
import type { Logger } from "pino";
import type { Log } from "queuert";
/**
* Creates a queuert Log adapter for Pino.
*
* Handles error serialization properly - Pino expects errors in the `err` property
* for proper stack trace formatting and serialization.
*/
export const createPinoLog = (logger: Logger): Log => {
return (entry) => {
const { type, level, message, data } = entry;
const error = "error" in entry ? entry.error : undefined;
// Pino uses 'err' property for proper error serialization
if (error !== undefined) {
logger[level]({ type, ...data, err: error }, message);
} else {
logger[level]({ type, ...data }, message);
}
};
};src/index.ts
const log = createPinoLog(logger);
const client = createClient({
stateAdapter,
log,
jobTypes,
});src/log.ts
import type { Log } from "queuert";
import type { Logger } from "winston";
/**
* Creates a queuert Log adapter for Winston.
*
* Handles error serialization properly - Winston accepts errors as metadata
* and formats them based on configured transports and formats.
*/
export const createWinstonLog = (logger: Logger): Log => {
return (entry) => {
const { type, level, message, data } = entry;
const error = "error" in entry ? entry.error : undefined;
// Winston accepts error in data object
if (error !== undefined) {
logger.log(level, message, { type, ...data, error });
} else {
logger.log(level, message, { type, ...data });
}
};
};src/index.ts
const log = createWinstonLog(logger);
const client = createClient({
stateAdapter,
log,
jobTypes,
});Log entry structure
Every log entry is a typed object with the following shape:
Entry fields
All entries are strongly typed — the type field determines the exact shape of data, the level, and the message. This means consumers can switch on type for type-safe handling.
Log entries
Each entry shows its message; the chips under it are the keys of data, error is the top-level field, and a trailing ? marks a key that can be absent.
Worker lifecycle
- worker_started infoStarted workerworkerId jobTypeNames
- worker_error errorWorker errorworkerId error
- worker_lease_lost warnWorker lost its leaseworkerId
- worker_stopped infoWorker has been stoppedworkerId
Job lifecycle
- job_created infoJob createdid typeName chainId chainTypeName input blockers scheduledAt
- job_completed infoJob completedid typeName chainId chainTypeName status attempt output? continuedWith?
- job_blocked infoJob blocked by incomplete chainsid typeName chainId chainTypeName blockedByChains
- job_rescheduled infoJob rescheduledid typeName chainId chainTypeName scheduledAt
- job_unblocked infoJob unblockedid typeName chainId chainTypeName unblockedByChain
Attempt lifecycle
- job_attempt_started infoJob attempt startedid typeName chainId chainTypeName status attempt workerId
- Job attempt completedid typeName chainId chainTypeName status attempt output? continuedWith? workerId
- job_attempt_failed errorJob attempt failedid typeName chainId chainTypeName status attempt workerId error
- job_attempt_lost warnJob attempt lostid typeName chainId chainTypeName status attempt attemptAt attemptBy workerId
- Reclaimed job attemptid typeName chainId chainTypeName status attempt attemptAt attemptBy workerId reclaimedFrom
Chain lifecycle
- chain_created infoChain createdid typeName input
- chain_completed infoChain completedid typeName output
- chain_deleted infoChain deletedid typeName
Adapter errors
- notify_adapter_error warnNotify adapter erroroperation error
- state_adapter_error warnState adapter erroroperation error
Validation errors
- (dynamic)code typeName ...details error
Examples
Loggers
- log/console createConsoleLogGitHubQueuert's built-in createConsoleLog() for simple console output.
$ pnpm --filter example-log-console startsrc/index.ts - log/pino PinoGitHubPino integration for structured logging, with per-job contextual loggers injected via attemptMiddleware.
$ pnpm --filter example-log-pino startsrc/log.tssrc/index.ts - log/winston WinstonGitHubWinston integration for structured logging, with per-job contextual loggers injected via attemptMiddleware.
$ pnpm --filter example-log-winston startsrc/log.tssrc/index.ts