SuavePlan/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0028c8adb669f85f6c0bc823c134c0ac5f74f7bc
skills/docs/observability/monitor/logger/README.md
admin 949299f58d first commit
2026-05-29 08:20:56 +01:00

20 KiB
Raw Blame History

@suaveplan/logger - Foundation logging package — structured JSON output, level filtering, redaction, sampling, OTel correlation, and pluggable sinks.

Summary

Enterprise-grade structured logger for Suaveplan. Provides a full pipeline: level filtering → OTel trace enrichment → sampling → redaction → sinks. Supports multiple output strategies (console, JSON/NDJSON, event bus, storage) with buffering and backpressure.

Documentation tree

- [abstract-logger](./src/abstract/abstract-logger.md) — _(no submodules)_- [console](./src/console/console-logger.md) — _(no submodules)_- [console-logger](./src/console/console-logger.md) — _(no submodules)_- [error-bridge](./src/error-bridge/error-bridge.md) — _(no submodules)_- [error-bridge](./src/error-bridge/error-bridge.md) — _(no submodules)_- [errors](./src/errors/logger-error.md) — _(no submodules)_- [logger-error](./src/errors/logger-error.md) — _(no submodules)_- [event](./src/event/event-logger.md) — _(no submodules)_- [event-logger](./src/event/event-logger.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [init](./src/init/init.md) — _(no submodules)_- [init](./src/init/init.md) — _(no submodules)_- [otel](./src/otel/otel-context.md) — _(no submodules)_- [otel-context](./src/otel/otel-context.md) — _(no submodules)_- [record](./src/record/log-record.md) — _(no submodules)_- [log-record](./src/record/log-record.md) — _(no submodules)_- [redaction](./src/redaction/redaction.md) — _(no submodules)_- [redaction](./src/redaction/redaction.md) — _(no submodules)_- [sampling](./src/sampling/sampling.md) — _(no submodules)_- [sampling](./src/sampling/sampling.md) — _(no submodules)_- [sink](./src/sink/sink.md) — _(no submodules)_- [buffered-sink](./src/sink/buffered-sink.md) — `BufferedSink` is an in-memory queuing wrapper around any `Sink` implementation. It decouples the hot path of log recor…

Features

  • Structured logging — LogRecord with level, message, ISO timestamp, context bag, trace IDs
  • Level filtering — debug | info | warn | error with hierarchical cutoff
  • OTel enrichment — auto-injects trace_id / span_id from the active OpenTelemetry span
  • Sampling — HeadSampler (deterministic FNV1a), TailSampler (buffered), RuleSampler, SampleAll/None
  • Redaction — path-based and regex-pattern rules; respects @suaveplan/error isSensitive() markers
  • Pluggable sinks — ConsoleSink, JsonSink (NDJSON), BufferedSink (async queue, backpressure), MultiSink
  • Concrete loggers — ConsoleLogger, EventLogger (event-bus integration), StorageLogger (KV persistence)
  • Error bridge — installs a global SuaveplanError interceptor so unhandled errors are logged automatically
  • Factory API — createLogger(config) for declarative setup; initLogger(config) for one-call bootstrap

Installation

bun add @suaveplan/logger

Quick Start

import { initLogger } from "@suaveplan/logger/init/init";
import { ConsoleLogger } from "@suaveplan/logger/console/console-logger";

// Option 1 — factory bootstrap
const logger = initLogger({ type: "console", level: "info" });
logger.info("server started", { port: 3000 });

// Option 2 — direct construction
const log = new ConsoleLogger({ level: "debug", colors: true, timestamp: true });
log.debug("connecting", { host: "db.local" });
log.warn("slow query", { ms: 412 });

Modules

Module Description
src/abstract/abstract-logger Base pipeline class — all concrete loggers extend this
src/record/log-record LogRecord type and Zod validation schemas
src/errors/logger-error LoggerError + LOGGER_CODES error registry
src/otel/otel-context OTel trace/span context extractor
src/sampling/sampling All sampler implementations and createSampler factory
src/redaction/redaction RedactionEngine and applyRedaction utility
src/sink/sink Sink interface, MultiSink, flushSink, closeSink
src/sink/console-sink ANSI-colored human-readable console output
src/sink/json-sink NDJSON structured output to any writer
src/sink/buffered-sink Async queue with configurable overflow policies
src/console/console-logger Ready-to-use console logger
src/event/event-logger Event-bus logger with per-level subscriptions
src/storage/storage-logger KV-backed persistent logger with batch flush
src/error-bridge/error-bridge Global SuaveplanError interceptor
src/factory/factory Declarative createLogger factory
src/init/init One-call initLogger bootstrap with global accessor

Usage: Redaction

import { ConsoleLogger } from "@suaveplan/logger/console/console-logger";

const log = new ConsoleLogger({
    level: "info",
    redaction: {
        rules: [
            { kind: "path", path: "user.password" },
            { kind: "pattern", pattern: /token/i },
        ],
    },
});

log.info("login", { user: { password: "s3cr3t", email: "a@b.com" }, token: "xyz" });
// → password and token fields are replaced with "[REDACTED]"

Usage: Sampling

import { createLogger } from "@suaveplan/logger/factory/factory";

const logger = createLogger({
    type: "console",
    level: "debug",
    sampling: { kind: "head", options: { rate: 0.1 } }, // keep 10%
});

Usage: Buffered JSON sink

import { BufferedSink } from "@suaveplan/logger/sink/buffered-sink";
import { JsonSink } from "@suaveplan/logger/sink/json-sink";

const inner = new JsonSink({ writer: (line) => fs.appendFileSync("app.log", line + "\n") });
const sink  = new BufferedSink({ sink: inner, maxQueueSize: 1000, overflowPolicy: "drop" });

// ... on shutdown:
await sink.flush();
await sink.close();

Usage: StorageLogger

import { StorageLogger } from "@suaveplan/logger/storage/storage-logger";

const logger = new StorageLogger(kvStorage, {
    level: "info",
    autoFlush: true,
    flushInterval: 10_000,
    maxBatchSize: 100,
});

logger.error("payment failed", { orderId: "ord_123" });

const recent = await logger.getLogs({ limit: 50 });
await logger.clearLogs(new Date(Date.now() - 7 * 86400_000)); // purge >7 days old

Usage: Error bridge

import { installSuaveplanErrorInterceptor } from "@suaveplan/logger/error-bridge/error-bridge";
import { ConsoleLogger } from "@suaveplan/logger/console/console-logger";

const log = new ConsoleLogger({ level: "warn" });
installSuaveplanErrorInterceptor(log); // all future SuaveplanErrors are logged automatically

API Reference

See each module's co-located .md file (linked in the table above) for full parameter and return-type documentation.

License

Private — Suaveplan internal use only.

Reference in New Issue View Git Blame Copy Permalink