@openknot-ts/logging
v0.0.6-preview
Published
OpenKnot's logging contract: a logger for operations, handlers and plugs, written by a console default or a plug.
Readme
OpenKnot logging
@openknot-ts/logging is OpenKnot's own logging contract. Operations, handlers and plugs declare logger in their requirements like any other dependency; an implementation writes the records. The console writes them until a plug provides another implementation.
operation, handler, plug → requirements: { logger } → Logger { trace, debug, info, warn, error, fatal, child }
@openknot-ts/logging → LOG_LEVEL filter → Logging { write(record) }
implementation → console (default) or a plug, such as pinoLog
import { logger } from "@openknot-ts/logging/wire";
const renameRole = operation<RenameRole, RoleState>()({
requirements: { findRole, logger },
run: async (input, { findRole, logger }) => {
logger.debug("renaming role", { roleId: input.id });
// ...
},
});
const createRole = command<CreateRole>()({
requirements: { saveRole, logger },
run: async (input, ctx) => {
ctx.logger.info("role created", { roleId: input.id });
// ...
},
});- Each method takes a message and optional attributes. Pass a failure as the
errorattribute:logger.error("delivery failed", { error }). child(attributes)returns a logger that adds those attributes to every record.LOG_LEVEL(trace,debug,info,warn,errororfatal, the levels pino and OpenTelemetry share;infoby default) is read atrunApplication(); any other value stops startup. The console writestracewithconsole.debugandfatalwithconsole.error.- With a tracing implementation bound, such as
provideOpenTelemetry(), every written record carries the active span'straceIdandspanId, as Spring Sleuth adds them to the MDC. Records outside a span carry neither, records filtered by their level never ask, and nothing changes without tracing. - Logging never fails the work that logs: a record the implementation cannot write is reported on the console with the implementation's error.
- Flow also logs its own executions per kind. No failure is silent by default: exposures and subscriptions write their defects, listeners and schedulers every failure; other kinds are set like
LOG_LEVEL_COMMAND=debugwithLOG_DURATION=true: see execution logs. - Behavior operations may require
loggerbeside readers and operations.standalone()uses the console logger unlessoverride(logger, value)supplies one.
Implement and bind
logging is a unit whose own declaration writes on the console; one binding replaces it:
import type { Logging } from "@openknot-ts/logging";
import { logging } from "@openknot-ts/logging/wire";
const jsonLines = unit({
provides: logging,
factory: (): Logging => ({
write: (record) => process.stdout.write(`${JSON.stringify(record)}\n`),
}),
});A record carries level, message and frozen attributes; time, format and destination belong to the implementation. @openknot-ts/pino-logging writes through the application's pino instance.
API
| Entry | Export | Description |
| --- | --- | --- |
| root | Logger, Logging, LogRecord, LogLevel, LogAttributes | The contract types. |
| root | createLogger(logging, { level?, attributes?, correlation? }) | A logger over an implementation, without Wire; correlation() adds attributes to each written record. |
| root | consoleLogging, parseLogLevel(value), isLogLevel(value) | The console implementation and level parsing. |
| root | isLoggerReference(value), LoggerMarker | Recognizes the /wire logger without loading Wire, as Behavior does. |
| /wire | logger, logging, loggingConfig | What consumers require, what implementations provide, and LOG_LEVEL. |
