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.
• 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.

Circular references become "[Circular]". Buffers become "[Binary]".

Transport‑agnostic architecture

File transports are enabled by default, but Scribe supports:

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

Using:

• 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

Scribe derives the log directory from the LoggerScope:

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

All segments are sanitized to prevent traversal or invalid characters.

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
});

HTTP logging (Morgan integration)

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

ANSI sequences are stripped before writing, ensuring clean machine‑readable logs.

Redaction behavior

Scribe removes sensitive keys at any depth:

{
  password: "[REDACTED]",
  nested: {
    token: "[REDACTED]"
  }
}

• Case‑insensitive matching
• Circular references → "[Circular]"
• Buffers → "[Binary]"

Scoping

You can derive a new logger with additional metadata: const userLogger = logger.scope({ user: "steven" }); userLogger.logInfo("User action");

This produces a new logger instance with merged scope.

Transport configuration

Scribe supports file‑based, console‑only, cloud‑only, and hybrid modes.

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

Build and publish

Scribe uses a strict file whitelist and a 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"]
}

This 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 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

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, either express or implied. See the License for the specific language governing permissions and limitations under the License.