@zudojs/observability 1.1.1 → 1.2.1

package/README.md

@@ -33,8 +33,7 @@ const obs = createObservability({
   environment: "production",
   logLevel: LogLevel.INFO,
 
-  // Opt in to redaction — see "Redaction" below.
-  redaction: {},
+  // Redaction is on by default — see "Redaction" below.
 
   // Sample 10% of traces. The decision is derived from the trace ID, so a
   // trace is never sampled in half across services.
@@ -82,8 +81,19 @@ Never pass a raw level number between the two; convert with
 
 ## Redaction
 
-Redaction is off unless you configure it, and on once you do. The logger
-applies it to every record before any transport sees it, and the tracer
+Redaction is **on by default**, as it is in `@zudojs/logger`: with no
+`redaction` option, every name the logger's default matcher redacts
+(`DEFAULT_LOGGER_SECRET_FIELDS` — password, passphrase, secret, token, jwt,
+bearer, auth, authorization, cookie, session, sid, credential, api key,
+private key, client secret, card number, cvv, ssn, pin, otp and more) is
+redacted here too. `DEFAULT_SENSITIVE_FIELDS` is that effective default list:
+the logger's `DEFAULT_LOGGER_SECRET_FIELDS` plus a few spellings of its own
+(`apikey`, `access_token`, `cardnumber`, …).
+Pass a config to change the rules, or `redaction: false` to turn it off.
+Before 1.2 redaction was off unless configured, so a `password` field was
+exported in the clear.
+
+The logger applies it to every record before any transport sees it, and the tracer
 applies it to every span attribute and span event attribute before any
 processor or exporter sees it — a `Bearer` token attached to a span is
 redacted the same way one written to a log field is.
@@ -92,8 +102,8 @@ redacted the same way one written to a log field is.
 const obs = createObservability({
   serviceName: "api",
   redaction: {
-    // Defaults cover passwords, tokens, cookies, keys and card numbers.
-    fields: ["password", "token", "ssn"],
+    // `fields` adds to the defaults; they stay in force.
+    fields: ["nationalId", "taxNumber"],
     patterns: [/^x-.*-secret$/i],
     // "contains" (the default) matches on word boundaries: "userPassword"
     // and "x-api-key" match, "shippingAddress" and "authorId" do not.
@@ -109,6 +119,22 @@ obs.logger.info("login", {
 });
 ```
 
+`fields` **extends** the defaults (since 1.2.1): the default names and the
+logger's matcher stay in force, so a field list can only add redaction —
+`fields: ["nationalId"]` and `fields: [...DEFAULT_SENSITIVE_FIELDS, "nationalId"]`
+mean the same thing. In 1.2.0 a list replaced the defaults, and because
+`DEFAULT_SENSITIVE_FIELDS` then lacked `jwt`, `sid`, `pwd`, `passphrase` and
+`bearer`, spreading it redacted less than the default. To use your list alone,
+opt out explicitly:
+
+```typescript
+createObservability({
+  serviceName: "api",
+  // Only `ssn` is redacted — no default names, no logger matcher.
+  redaction: { fields: ["ssn"], replaceDefaults: true },
+});
+```
+
 Traversal handles the shapes secrets actually arrive in: arrays, nested
 objects, instances of your own classes (a DTO carrying a `password` field is
 redacted and keeps its prototype), and cyclic graphs (a request object in a log
@@ -119,6 +145,10 @@ being flattened to `{}`.
 `redactObject`, `redactValue` and `createStructureRedactor` are exported for
 use outside the logger.
 
+```typescript
+createObservability({ serviceName: "api", redaction: false }); // opt out
+```
+
 ## Metrics
 
 Counters, gauges and histograms, keyed by name **and** labels.
@@ -165,8 +195,9 @@ name as two types is rejected wholesale by OTLP and Prometheus.
 
 Metrics are exported by a `PeriodicMetricReader`, which the facade starts for
 you when a `metricExporter` is configured. `metricExportIntervalMs: 0`
-disables the periodic export while still collecting a final snapshot on
-`flush()` and `shutdown()`:
+disables the periodic export while still collecting a snapshot on `flush()`
+and a final one on `shutdown()`. `shutdown()` exports that final snapshot
+exactly once (before 1.2 it was exported twice):
 
 ```typescript
 const obs = createObservability({

package/dist/index.d.ts

@@ -16,7 +16,7 @@
  * const obs = createObservability({
  *   serviceName: "my-api",
  *   logLevel: LogLevel.INFO,
- *   redaction: {},                 // opt in to redaction
+ *   // Redaction is on by default; `redaction: false` turns it off.
  *   sampler: createProbabilitySampler(0.1),
  * });
  *

package/dist/index.js

@@ -16,7 +16,7 @@
  * const obs = createObservability({
  *   serviceName: "my-api",
  *   logLevel: LogLevel.INFO,
- *   redaction: {},                 // opt in to redaction
+ *   // Redaction is on by default; `redaction: false` turns it off.
  *   sampler: createProbabilitySampler(0.1),
  * });
  *

package/dist/observability/observability.core.d.ts

@@ -23,7 +23,7 @@ interface TelemetryPipeline {
     readonly metricReader: PeriodicMetricReader;
     readonly config: ObservabilityConfig;
     readonly sampler: ObservabilityConfig["sampler"];
-    /** Redacts span attributes, when `config.redaction` is set. */
+    /** Redacts span attributes, unless `config.redaction` is `false`. */
     readonly redactAttribute?: (key: string, value: unknown) => unknown;
 }
 /**
@@ -64,6 +64,11 @@ export declare class DefaultObservability implements Observability {
      * when the caller went on to exit.
      */
     flush(): Promise<void>;
+    /**
+     * Drains the log and span buffers, and — when `includeMetrics` — exports a
+     * metric snapshot. Shutdown passes `false`: the reader's own `shutdown()`
+     * exports the final snapshot, and collecting here as well sent it twice.
+     */
     private drain;
     private reportFailures;
     /**

package/dist/observability/observability.core.js

@@ -79,9 +79,14 @@ export class DefaultObservability {
      * when the caller went on to exit.
      */
     async flush() {
-        await this.drain();
+        await this.drain(true);
     }
-    async drain() {
+    /**
+     * Drains the log and span buffers, and — when `includeMetrics` — exports a
+     * metric snapshot. Shutdown passes `false`: the reader's own `shutdown()`
+     * exports the final snapshot, and collecting here as well sent it twice.
+     */
+    async drain(includeMetrics) {
         const tasks = [];
         if (this.pipeline.logProcessor) {
             tasks.push(this.pipeline.logProcessor.flush());
@@ -90,7 +95,8 @@ export class DefaultObservability {
             if (processor.forceFlush)
                 tasks.push(processor.forceFlush());
         }
-        tasks.push(this.pipeline.metricReader.collect());
+        if (includeMetrics)
+            tasks.push(this.pipeline.metricReader.collect());
         await this.reportFailures(await Promise.allSettled(tasks), "flush");
     }
     async reportFailures(results, source) {
@@ -115,8 +121,9 @@ export class DefaultObservability {
     }
     async performShutdown() {
         // Drain first: whatever is still queued should reach the backend before
-        // the exporters close.
-        await this.drain();
+        // the exporters close. Metrics are left to the reader's shutdown, which
+        // exports the final snapshot exactly once.
+        await this.drain(false);
         const steps = [];
         steps.push(this.pipeline.metricReader.shutdown());
         if (this.pipeline.logProcessor) {
@@ -186,10 +193,10 @@ function buildPipeline(config) {
     });
     // Redaction is applied by the logger, so every transport and exporter
     // downstream sees redacted records — configuring it and not wiring it here
-    // is what made the "credentials are never logged" promise untrue.
-    const redactor = config.redaction
-        ? createStructureRedactor(config.redaction)
-        : undefined;
+    // is what made the "credentials are never logged" promise untrue. It is on
+    // unless the caller opts out with `redaction: false`, as in @zudojs/logger.
+    const redaction = resolveRedaction(config);
+    const redactor = redaction ? createStructureRedactor(redaction) : undefined;
     const logger = new StructuredLogger({
         name: config.serviceName,
         level: config.logLevel ?? LogLevel.INFO,
@@ -244,8 +251,8 @@ function buildPipeline(config) {
         onError: config.onError,
     });
     metricReader.start();
-    const redactAttribute = config.redaction
-        ? buildAttributeRedactor(config.redaction)
+    const redactAttribute = redaction
+        ? buildAttributeRedactor(redaction)
         : undefined;
     return {
         logger,
@@ -259,6 +266,15 @@ function buildPipeline(config) {
         redactAttribute,
     };
 }
+/**
+ * The redaction rules in force: the caller's, the defaults when none were
+ * given, or none at all for an explicit `redaction: false`.
+ */
+function resolveRedaction(config) {
+    if (config.redaction === false)
+        return undefined;
+    return config.redaction ?? {};
+}
 /**
  * Builds the span-attribute redactor.
  *

package/dist/redaction/index.d.ts

@@ -3,5 +3,6 @@
  *
  * Sensitive field redaction for logs and traces.
  */
-export { createRedactor, createStructureRedactor, redactObject, redactValue, isSensitiveField, DEFAULT_SENSITIVE_FIELDS, CIRCULAR_MARKER, MAX_DEPTH_MARKER, } from "./redaction.core.js";
+export { createRedactor, createStructureRedactor, redactObject, redactValue, isSensitiveField, CIRCULAR_MARKER, MAX_DEPTH_MARKER, } from "./redaction.core.js";
+export { DEFAULT_SENSITIVE_FIELDS } from "./redaction.defaults.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/redaction/index.js

@@ -3,5 +3,6 @@
  *
  * Sensitive field redaction for logs and traces.
  */
-export { createRedactor, createStructureRedactor, redactObject, redactValue, isSensitiveField, DEFAULT_SENSITIVE_FIELDS, CIRCULAR_MARKER, MAX_DEPTH_MARKER, } from "./redaction.core.js";
+export { createRedactor, createStructureRedactor, redactObject, redactValue, isSensitiveField, CIRCULAR_MARKER, MAX_DEPTH_MARKER, } from "./redaction.core.js";
+export { DEFAULT_SENSITIVE_FIELDS } from "./redaction.defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/redaction/redaction.core.d.ts

@@ -17,8 +17,6 @@
  *     `x-api-key` are caught, not just the exact names in the list.
  */
 import type { RedactionConfig } from "../types.js";
-/** Default sensitive field names, matched case-insensitively. */
-export declare const DEFAULT_SENSITIVE_FIELDS: readonly string[];
 /** Marker used in place of a structure that was too deep or already seen. */
 export declare const CIRCULAR_MARKER = "[CIRCULAR]";
 export declare const MAX_DEPTH_MARKER = "[MAX_DEPTH]";

package/dist/redaction/redaction.core.js

@@ -16,33 +16,14 @@
  *   - matching is substring-based by default, so `userPassword` and
  *     `x-api-key` are caught, not just the exact names in the list.
  */
-/** Default sensitive field names, matched case-insensitively. */
-export const DEFAULT_SENSITIVE_FIELDS = [
-    "password",
-    "passwd",
-    "secret",
-    "token",
-    "authorization",
-    "auth",
-    "cookie",
-    "session",
-    "credential",
-    "api_key",
-    "apikey",
-    "access_token",
-    "refresh_token",
-    "private_key",
-    "client_secret",
-    "credit_card",
-    "creditcard",
-    "card_number",
-    "cardnumber",
-    "cvv",
-    "ssn",
-    "social_security",
-    "pin",
-    "otp",
-];
+import { createDefaultSecretFieldMatcher } from "@zudojs/logger";
+import { DEFAULT_SENSITIVE_FIELDS } from "./redaction.defaults.js";
+/**
+ * @zudojs/logger's default secret-name matcher. The default rules here
+ * include it, so a field the logger redacts is never exported in the clear
+ * by this package.
+ */
+const isLoggerSecretField = createDefaultSecretFieldMatcher();
 const DEFAULT_REPLACEMENT = "[REDACTED]";
 const DEFAULT_MAX_DEPTH = 8;
 /** Marker used in place of a structure that was too deep or already seen. */
@@ -87,15 +68,22 @@ function wordJoins(key) {
     return joins;
 }
 function compile(config) {
-    const fields = (config?.fields ?? DEFAULT_SENSITIVE_FIELDS).map((field) => field.toLowerCase());
+    const configured = config?.fields;
+    const replaceDefaults = configured !== undefined && config?.replaceDefaults === true;
+    const fields = (replaceDefaults
+        ? configured
+        : [...DEFAULT_SENSITIVE_FIELDS, ...(configured ?? [])]).map((field) => field.toLowerCase());
     const patterns = config?.patterns ?? [];
     const matchMode = config?.matchMode ?? "contains";
     const exact = new Set(fields);
     const normalizedFields = new Set(fields.map((field) => field.replace(/[^a-z0-9]/g, "")).filter(Boolean));
+    const withLoggerDefaults = !replaceDefaults && matchMode === "contains";
     const isSensitive = (key) => {
         const lower = key.toLowerCase();
         if (exact.has(lower))
             return true;
+        if (withLoggerDefaults && isLoggerSecretField(key))
+            return true;
         if (matchMode === "contains") {
             for (const candidate of wordJoins(key)) {
                 if (normalizedFields.has(candidate))

package/dist/redaction/redaction.defaults.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @zudojs/observability — Default redaction field list
+ *
+ * One list, built from @zudojs/logger's rather than copied from it, so the
+ * documented "extend the defaults" pattern
+ * (`fields: [...DEFAULT_SENSITIVE_FIELDS, "nationalId"]`) can never cover
+ * fewer names than the default rules do.
+ */
+/**
+ * Default sensitive field names, matched case-insensitively.
+ *
+ * Every entry of @zudojs/logger's `DEFAULT_LOGGER_SECRET_FIELDS` (password,
+ * passphrase, pwd, secret, token, jwt, bearer, auth, cookie, session, sid,
+ * credential, api key, card number, cvv, ssn, pin, otp, …) plus the
+ * spellings in {@link OBSERVABILITY_EXTRA_FIELDS}.
+ */
+export declare const DEFAULT_SENSITIVE_FIELDS: readonly string[];
+//# sourceMappingURL=redaction.defaults.d.ts.map

package/dist/redaction/redaction.defaults.js

@@ -0,0 +1,33 @@
+/**
+ * @zudojs/observability — Default redaction field list
+ *
+ * One list, built from @zudojs/logger's rather than copied from it, so the
+ * documented "extend the defaults" pattern
+ * (`fields: [...DEFAULT_SENSITIVE_FIELDS, "nationalId"]`) can never cover
+ * fewer names than the default rules do.
+ */
+import { DEFAULT_LOGGER_SECRET_FIELDS } from "@zudojs/logger";
+/**
+ * Spellings this package matched before it adopted the logger's list. In
+ * `"contains"` mode they are already covered by a logger entry; they are kept
+ * so `"exact"` mode (`apikey` vs `api_key`) does not lose them.
+ */
+const OBSERVABILITY_EXTRA_FIELDS = [
+    "apikey",
+    "access_token",
+    "refresh_token",
+    "creditcard",
+    "cardnumber",
+];
+/**
+ * Default sensitive field names, matched case-insensitively.
+ *
+ * Every entry of @zudojs/logger's `DEFAULT_LOGGER_SECRET_FIELDS` (password,
+ * passphrase, pwd, secret, token, jwt, bearer, auth, cookie, session, sid,
+ * credential, api key, card number, cvv, ssn, pin, otp, …) plus the
+ * spellings in {@link OBSERVABILITY_EXTRA_FIELDS}.
+ */
+export const DEFAULT_SENSITIVE_FIELDS = Object.freeze([
+    ...new Set([...DEFAULT_LOGGER_SECRET_FIELDS, ...OBSERVABILITY_EXTRA_FIELDS]),
+]);
+//# sourceMappingURL=redaction.defaults.js.map

package/dist/types/config.types.d.ts

@@ -50,10 +50,18 @@ export type RedactionMatchMode = "exact" | "contains";
 /** Configuration for redacting sensitive fields from logs and traces. */
 export interface RedactionConfig {
     /**
-     * Field names to redact (case-insensitive). Defaults to a built-in list
-     * covering passwords, tokens, cookies, keys and card numbers.
+     * Extra field names to redact (case-insensitive), added to the defaults:
+     * `DEFAULT_SENSITIVE_FIELDS` and @zudojs/logger's default matcher stay in
+     * force, so a list can only ever add redaction. Set
+     * {@link RedactionConfig.replaceDefaults} to use this list alone.
      */
     readonly fields?: readonly string[];
+    /**
+     * `true` makes {@link RedactionConfig.fields} replace the default names and
+     * the logger's matcher instead of extending them — the pre-1.2.1 meaning
+     * of `fields`. Ignored when `fields` is not set. Default: `false`.
+     */
+    readonly replaceDefaults?: boolean;
     /**
      * Additional patterns tested against the field name. Useful for
      * conventions a name list cannot express, such as `/^x-.*-token$/i`.
@@ -101,9 +109,13 @@ export interface ObservabilityConfig {
     readonly processors?: readonly SpanProcessor[];
     /**
      * Redacts sensitive fields from log contexts *and* from span attributes and
-     * span event attributes. Omit it and neither is redacted.
+     * span event attributes.
+     *
+     * On by default: omitting it applies the default rules, which include
+     * every name @zudojs/logger redacts. Pass a config to change the rules, or
+     * `false` to turn redaction off.
      */
-    readonly redaction?: RedactionConfig;
+    readonly redaction?: RedactionConfig | false;
     /**
      * Metrics registry tuning: the series cap that bounds cardinality, and the
      * histogram bucket boundaries. Without this the defaults were unreachable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/observability",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Structured logging, metrics, tracing, context propagation, and exporters for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -26,12 +26,13 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.2.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/logger": "1.4.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11",
-    "@types/node": "^26.4.1"
+    "vitest": "^5.0.1",
+    "@types/node": "^26.6.2"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -46,7 +47,7 @@
     "tracing",
     "logs"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-observability",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },