Scribe

@glassops/scribe

A deterministic, multi‑tenant logging subsystem designed for regulated environments, contributor safety, and zero‑ambiguity operational behavior. Scribe provides structured log streams, deep redaction, scoped metadata, and predictable directory grammars without leaking runtime state or relying on global configuration.

Scribe is the foundation for all logging across GlassOps services.

Core capabilities

Deterministic directory grammar

Log directories are derived from the LoggerScope:

• Service mode: <target>/<service>/<tenant>
• Non-service mode: <target>/<tenant>/<environment>

This ensures production, staging, and development never collide, and that multi‑tenant logs remain strictly partitioned.

Structured, operationally meaningful logs

• JSON‑structured entries with timestamps.
• Daily-rotated files with configurable retention (default: 14 days).
• Semantic log levels (critical, change, http, etc.) mapped to dedicated transports.
• Request-scoped metadata (tenant, service, environment, user, correlationId, requestId).

Deep, case‑insensitive redaction

Sensitive keys are removed at any depth, regardless of casing:

• password, Password, PASSWORD
• authorization, Authorization, etc.

Other behaviors:

• Circular references → "[Circular]"
• Buffers → "[Binary]"

Transport‑agnostic architecture

File transports are enabled by default, but Scribe supports:

• Console‑only mode
• Cloud‑only mode
• Hybrid mode

Configurable through:

• disableFileTransports
• extraTransports

Pure, re‑entrant API

• No global state
• No shared mutable configuration
• No hidden defaults

Every logger instance is fully deterministic and scoped.

Installation

npm install @glassops/scribe

Mental model

Scribe is built around three principles:

• Identity is explicit: Every log entry carries a complete scope describing tenant, environment, service, and correlation identifiers.
• Streams are semantic: Incidents, changes, HTTP traffic, and application logs are treated as distinct operational categories.
• Safety is mandatory: Redaction, sanitization, and directory grammar are enforced before logs reach any transport.

Directory structure

All segments of the directory path are sanitized to prevent traversal or invalid characters.

• With service: <target>/<service>/<tenant>
• Without service: <target>/<tenant>/<environment>

Usage

Creating a directory

import { createDirectory } from "@glassops/scribe";

const directory = createDirectory("/var/logs", {
  tenant: "acme",
  environment: "production",
  service: "billing",
});

Creating a logger

import { createLogger } from "@glassops/scribe";

const logger = createLogger(
  directory,
  {
    tenant: "acme",
    environment: "production",
    service: "billing",
    correlationId: "abc123",
  },
  {
    level: "info",
    requestLog: "requests-%DATE%.log",
    appLog: "app-%DATE%.log",
    incidentLog: "incident-%DATE%.log",
    changeLog: "change-%DATE%.log",
    logToConsole: true,
    sensitiveKeys: ["password", "token"],
  }
);

Logging methods

Each method accepts a message and optional context. Context is deeply redacted before writing.

• logError(error, context?)
• logWarn(message, context?)
• logInfo(message, context?)
• logDebug(message, context?)
• logIncident(message, context?)
• logChange(message, context?)

Example:

logger.logInfo("User updated profile", {
  userId: "123",
  password: "secret", // redacted automatically
});

HTTP logging (Morgan integration)

Scribe supports direct integration with Morgan. ANSI sequences are stripped before writing to ensure clean JSON logs:

app.use(morgan("combined", { stream: logger.createLoggerStream() }));

Redaction behavior

• Case-insensitive key matching
• Nested sensitive fields are recursively redacted
• Circular references: "[Circular]"
• Buffers: "[Binary]"

Scoping

You can derive a new logger with additional metadata:

const userLogger = await logger.scope({ user: "steven" });
userLogger.logInfo("User action");

Produces a new logger instance with merged scope. Logger directory may change if scope affects service or environment.

Existing transports are closed and rebuilt automatically if necessary.

Logger API

interface ScribeLogger {
    logError(error: string | Error, context?: Record<string, unknown>): void;
    logWarn(message: string, context?: Record<string, unknown>): void;
    logInfo(message: string, context?: Record<string, unknown>): void;
    logDebug(message: string, context?: Record<string, unknown>): void;
    logIncident(message: string, context?: Record<string, unknown>): void;
    logChange(message: string, context?: Record<string, unknown>): void;
    createLoggerStream(): { write: (message: string) => void };
    scope(partial: Partial<LoggerScope>): Promise<void>;
    close(): Promise<void>;
    logger: Logger;
}

• createLoggerStream(): Returns a Morgan-compatible writable stream.
• scope(): Returns a Promise<void>; merges partial metadata into current logger.
• close(): Gracefully shuts down transports.
• logger: Exposes underlying Winston Logger instance.

Transport configuration

interface LoggerOptions {
  level: LogLevel;
  requestLog: string;
  appLog: string;
  changeLog?: string;
  incidentLog?: string;
  logToConsole?: boolean;
  sensitiveKeys?: string[];
  retention?: string;
  disableFileTransports?: boolean;
  extraTransports?: Transport[];
}

Log levels

• critical
• error
• warn
• info
• http
• change
• debug

Each level is treated as a separate operational stream rather than a severity threshold.

Build and publish

Scribe uses a strict file whitelist and deterministic build pipeline.

Scripts

{
  "scripts": {
    "clean": "rm -rf dist",
    "build": "npm run clean && tsc -p tsconfig.json",
    "prepack": "npm run build"
  }
}

Prepack ensures dist/ is always built before:

• npm publish
• npm publish --dry-run
• npm pack

Files included in the package:

{
  "files": ["dist", "README.md", "LICENSE"]
}

Guarantees only compiled output and documentation are published.

Design rationale

• Directory grammar prevents cross-environment and cross-tenant collisions.
• Semantic log levels allow operational tooling to treat incidents, changes, and HTTP traffic as distinct streams.
• Deep, case-insensitive redaction prevents credential leakage.
• Pure, re-entrant API ensures deterministic behavior across multi-tenant and multi-service deployments.
• Daily rotation keeps log files predictable for ingestion pipelines.
• Transport-agnostic design supports file, console, cloud, and hybrid logging.

License

Copyright [2026] [GlassOps Limited]

Licensed under the Apache License, Version 2.0 ("License").

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.