@zudojs/observability 1.1.0 → 1.2.0

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,17 @@ 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, along with this package's own `DEFAULT_SENSITIVE_FIELDS`.
+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,7 +100,7 @@ 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.
+    // Setting `fields` replaces the default list (and the logger's rules).
     fields: ["password", "token", "ssn"],
     patterns: [/^x-.*-secret$/i],
     // "contains" (the default) matches on word boundaries: "userPassword"
@@ -119,6 +127,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 +177,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) {
@@ -143,6 +150,35 @@ function buildResourceAttributes(config) {
         ...(config.resource ?? {}),
     };
 }
+/** Shortest interval between two repeat queue-overflow reports. */
+const DROP_REPORT_INTERVAL_MS = 60_000;
+/**
+ * Rate-limits a processor's `onDrop` callback.
+ *
+ * `onDrop` fires once per record the bounded queue refuses, on the
+ * synchronous `logger.info()` path, and the report below allocates an
+ * `Error` (so, a stack capture) and re-enters the caller's `onError` —
+ * which usually writes to the sink that is already stalled. The bounded
+ * queue is the control that makes a stalled exporter survivable; reporting
+ * every drop turned it into a second, louder failure.
+ *
+ * Handled the same way an over-cardinality metric is a few lines below: the
+ * first occurrence is reported immediately, then at most one per interval.
+ * The count handed to `report` is the processor's running total, so
+ * whoever does get notified still sees how many records were lost.
+ */
+function throttleDropReports(report) {
+    let lastReportedAt;
+    return (dropped) => {
+        const at = Date.now();
+        if (lastReportedAt !== undefined &&
+            at - lastReportedAt < DROP_REPORT_INTERVAL_MS) {
+            return;
+        }
+        lastReportedAt = at;
+        report(dropped);
+    };
+}
 function buildPipeline(config) {
     const useConsole = config.useConsoleExporters ?? true;
     /* ── Logging ─────────────────────────────────────────────────────────── */
@@ -153,14 +189,14 @@ function buildPipeline(config) {
         batchSize: config.logBatchSize,
         flushIntervalMs: config.logFlushIntervalMs,
         onError: config.onError,
-        onDrop: (dropped) => config.onError?.(new Error(`Dropped ${dropped} log records: queue full`), "BatchLogProcessor"),
+        onDrop: throttleDropReports((dropped) => config.onError?.(new Error(`Dropped ${dropped} log records: queue full`), "BatchLogProcessor")),
     });
     // 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,
@@ -179,7 +215,7 @@ function buildPipeline(config) {
         new BatchSpanProcessor({
             exporter: ownSpanExporter(),
             onError: config.onError,
-            onDrop: (dropped) => config.onError?.(new Error(`Dropped ${dropped} spans: queue full`), "BatchSpanProcessor"),
+            onDrop: throttleDropReports((dropped) => config.onError?.(new Error(`Dropped ${dropped} spans: queue full`), "BatchSpanProcessor")),
         }),
     ];
     // When the caller supplied their own processors, they own the exporter's
@@ -215,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,
@@ -230,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/redaction.core.js

@@ -16,6 +16,13 @@
  *   - matching is substring-based by default, so `userPassword` and
  *     `x-api-key` are caught, not just the exact names in the list.
  */
+import { createDefaultSecretFieldMatcher } from "@zudojs/logger";
+/**
+ * @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();
 /** Default sensitive field names, matched case-insensitively. */
 export const DEFAULT_SENSITIVE_FIELDS = [
     "password",
@@ -92,10 +99,13 @@ function compile(config) {
     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 = config?.fields === undefined && 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/tracing/span/span.core.js

@@ -6,6 +6,23 @@
  */
 import { SpanKind, SpanStatus } from "../../types.js";
 import { createSpanContext, createChildSpanContext, } from "./spanContext.type.js";
+/**
+ * Stores one attribute on a bag whose keys come from instrumentation.
+ *
+ * `bag[key] = value` invokes the inherited `__proto__` setter for that one
+ * key: the attribute never lands, and an object value replaces the bag's
+ * prototype. A poisoned prototype then defeats `maxAttributes`, because the
+ * cap is only applied to keys the bag does not already answer for. Matches
+ * the same guard in `redaction.core.ts`.
+ */
+function defineAttribute(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
 /** Defaults matching the OpenTelemetry specification. */
 const DEFAULT_LIMITS = {
     maxAttributes: 128,
@@ -81,12 +98,12 @@ export class DefaultSpan {
     setAttribute(key, value) {
         if (this.ended || !this.recording)
             return;
-        if (!(key in this.attributes) &&
+        if (!Object.prototype.hasOwnProperty.call(this.attributes, key) &&
             Object.keys(this.attributes).length >= this.limits.maxAttributes) {
             this.droppedAttributes++;
             return;
         }
-        this.attributes[key] = this.sanitize(key, value);
+        defineAttribute(this.attributes, key, this.sanitize(key, value));
     }
     addEvent(name, attributes) {
         if (this.ended || !this.recording)
@@ -104,7 +121,7 @@ export class DefaultSpan {
                     this.droppedAttributes++;
                     continue;
                 }
-                eventAttributes[key] = this.sanitize(key, value);
+                defineAttribute(eventAttributes, key, this.sanitize(key, value));
                 kept++;
             }
         }

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

@@ -51,7 +51,8 @@ export type RedactionMatchMode = "exact" | "contains";
 export interface RedactionConfig {
     /**
      * Field names to redact (case-insensitive). Defaults to a built-in list
-     * covering passwords, tokens, cookies, keys and card numbers.
+     * covering passwords, tokens, cookies, keys and card numbers, plus every
+     * name @zudojs/logger's default matcher redacts. Setting it replaces both.
      */
     readonly fields?: readonly string[];
     /**
@@ -101,9 +102,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.0",
+  "version": "1.2.0",
   "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.1.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/logger": "1.4.0"
   },
   "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"
   },