@kleb/logging (0.2.0)

Published 2026-07-03 14:47:44 +02:00 by kleb

Setup this registry in your project .npmrc file:

@kleb:registry=

To install the package using npm, run the following command:

npm install @kleb/logging@0.2.0

or add it to the package.json file:

"@kleb/logging": "0.2.0"

For more information on the npm registry, see the documentation.

@kleb/logging

Structured logging for TypeScript projects.

Install from the private Forgejo npm registry after configuring auth for https://git.kleb.sh/api/packages/kleb/npm/:

bun add @kleb/logging

import { createLogger } from "@kleb/logging";

const logger = createLogger();
logger.info("app.started", { port: 3000 });

Use the server entrypoint for rotating file logs:

import { createLogger } from "@kleb/logging";
import { createRotatingFileSink } from "@kleb/logging/server";

const logger = createLogger({
  sinks: [
    createRotatingFileSink({
      directory: "logs",
      archiveDirectory: "archive",
      formats: ["json", "text"],
      rotation: { every: "day", atHour: 0 },
      maxArchived: 31,
    }),
  ],
});

Archives are written below the active log directory by default:

logs/
  current.log
  current.json.log
  error.log
  errors.json.log
  archive/
    text/
    json/

Use a custom archive folder when active logs and archived logs should be separated:

createRotatingFileSink({
  directory: "logs/active",
  archiveDirectory: "../archive",
  formats: ["json", "text"],
  rotation: { every: "hour" },
});

For short-lived validation or interval-based rotation, use rotation.every.milliseconds:

createRotatingFileSink({
  directory: "logs",
  formats: ["json", "text"],
  rotation: { every: { milliseconds: 60_000 } },
});

Disable automatic rotation while keeping manual rotation available:

const sink = createRotatingFileSink({
  directory: "logs",
  rotation: false,
});

await sink.rotate();

Use the context entrypoint to attach request-scoped fields across async calls:

import { createLogger } from "@kleb/logging";
import { logContextProvider, withLogContext } from "@kleb/logging/context";

const logger = createLogger({
  contextProvider: logContextProvider,
});

await withLogContext({ requestId: "req-123", userId: "user-1" }, async () => {
  await doWork();
  logger.info("work.completed");
});

Fields passed directly to a log call override active context fields:

logger.info("work.completed", { requestId: "req-explicit" });

Combine context providers when logs should include multiple ambient sources:

import { combineLogContextProviders, createLogger } from "@kleb/logging";
import { logContextProvider } from "@kleb/logging/context";
import { otelContextProvider } from "@kleb/logging/otel";

const logger = createLogger({
  contextProvider: combineLogContextProviders(logContextProvider, otelContextProvider()),
});

The OpenTelemetry entrypoint reads the active span from @opentelemetry/api and adds traceId and spanId when a valid active span exists. It does not initialize telemetry, create spans, or export logs.

Redaction is explicit:

const logger = createLogger({
  redaction: {
    keys: ["authorization", /password/i],
    patterns: [/token-[a-z0-9]+/gi],
  },
});

HTTP helpers require already-safe route patterns:

logger.info(
  "http.request.completed",
  createHttpLogFields({
    requestId: "req-123",
    method: "GET",
    routePattern: "/api/users/:id",
    status: 200,
    durationMs: 12.5,
  }),
);

Development dependencies

ID	Version
@opentelemetry/api	^1.9.1

Peer dependencies

ID	Version
@opentelemetry/api	^1.9.1

Details

npm

2026-07-03 14:47:44 +02:00

UNLICENSED

27 KiB

Assets (1)

logging-0.2.0.tgz 27 KiB

Versions (7) View all

0.6.0

2026-07-20

0.5.0

2026-07-14

0.4.0

2026-07-07

0.3.1

2026-07-04

0.3.0

2026-07-03

@kleb/logging (0.2.0)

Installation

About this package

@kleb/logging

Dependencies