@deeptracer/core 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Logger: () => Logger,
+  SDK_NAME: () => SDK_NAME,
+  SDK_VERSION: () => SDK_VERSION,
   createLogger: () => createLogger
 });
 module.exports = __toCommonJS(index_exports);
@@ -52,118 +54,167 @@ var Batcher = class {
   startTimer() {
     this.timer = setInterval(() => this.flush(), this.flushIntervalMs);
   }
-  destroy() {
+  async destroy() {
     if (this.timer) clearInterval(this.timer);
+    this.timer = null;
     this.flush();
   }
 };
 
+// src/version.ts
+var SDK_VERSION = "0.3.0";
+var SDK_NAME = "core";
+
 // src/transport.ts
 var Transport = class {
   constructor(config) {
     this.config = config;
   }
-  async sendLogs(logs) {
-    try {
-      const res = await fetch(`${this.config.endpoint}/ingest/logs`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.apiKey}`
-        },
-        body: JSON.stringify({
-          product: this.config.product,
-          service: this.config.service,
-          environment: this.config.environment,
-          logs
-        })
-      });
-      if (!res.ok) {
+  inFlightRequests = /* @__PURE__ */ new Set();
+  /**
+   * Send a request with automatic retry and exponential backoff.
+   * Retries up to `maxRetries` times on network errors and 5xx responses.
+   * Does NOT retry on 4xx (client errors — bad payload, auth failure, etc.).
+   */
+  async sendWithRetry(url, body, label, maxRetries = 3) {
+    const baseDelays = [1e3, 2e3, 4e3];
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const res = await fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "x-deeptracer-sdk": `${SDK_NAME}/${SDK_VERSION}`
+          },
+          body: JSON.stringify(body)
+        });
+        if (res.ok) return;
+        if (res.status >= 400 && res.status < 500) {
+          console.warn(
+            `[@deeptracer/core] Failed to send ${label}: ${res.status} ${res.statusText}`
+          );
+          return;
+        }
+        if (attempt < maxRetries) {
+          await this.sleep(this.jitter(baseDelays[attempt]));
+          continue;
+        }
         console.warn(
-          `[@deeptracer/core] Failed to send logs: ${res.status} ${res.statusText}`
+          `[@deeptracer/core] Failed to send ${label}: ${res.status} ${res.statusText} (exhausted ${maxRetries} retries)`
         );
-      }
-    } catch {
-      console.warn(
-        "[@deeptracer/core] Failed to send logs, falling back to console"
-      );
-    }
-  }
-  async sendError(error) {
-    try {
-      const res = await fetch(`${this.config.endpoint}/ingest/errors`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.apiKey}`
-        },
-        body: JSON.stringify({
-          ...error,
-          product: this.config.product,
-          service: this.config.service,
-          environment: this.config.environment
-        })
-      });
-      if (!res.ok) {
+      } catch {
+        if (attempt < maxRetries) {
+          await this.sleep(this.jitter(baseDelays[attempt]));
+          continue;
+        }
         console.warn(
-          `[@deeptracer/core] Failed to send error: ${res.status} ${res.statusText}`
+          `[@deeptracer/core] Failed to send ${label} (exhausted ${maxRetries} retries)`
         );
       }
-    } catch {
-      console.warn("[@deeptracer/core] Failed to send error report");
-      console.error(error.error_message);
     }
   }
+  /** Add +/- 20% jitter to a delay to prevent thundering herd. */
+  jitter(ms) {
+    const factor = 0.8 + Math.random() * 0.4;
+    return Math.round(ms * factor);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /** Track an in-flight request and remove it when done. */
+  track(promise) {
+    this.inFlightRequests.add(promise);
+    promise.finally(() => this.inFlightRequests.delete(promise));
+  }
+  async sendLogs(logs) {
+    const p = this.sendWithRetry(
+      `${this.config.endpoint}/ingest/logs`,
+      {
+        product: this.config.product,
+        service: this.config.service,
+        environment: this.config.environment,
+        logs
+      },
+      "logs"
+    );
+    this.track(p);
+    return p;
+  }
+  async sendError(error) {
+    const p = this.sendWithRetry(
+      `${this.config.endpoint}/ingest/errors`,
+      {
+        ...error,
+        product: this.config.product,
+        service: this.config.service,
+        environment: this.config.environment
+      },
+      "error"
+    );
+    this.track(p);
+    return p;
+  }
   async sendTrace(span) {
-    try {
-      const res = await fetch(`${this.config.endpoint}/ingest/traces`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.apiKey}`
-        },
-        body: JSON.stringify({
-          ...span,
-          product: this.config.product,
-          service: this.config.service,
-          environment: this.config.environment
-        })
-      });
-      if (!res.ok) {
-        console.warn(
-          `[@deeptracer/core] Failed to send trace: ${res.status} ${res.statusText}`
-        );
-      }
-    } catch {
-      console.warn("[@deeptracer/core] Failed to send trace span");
-    }
+    const p = this.sendWithRetry(
+      `${this.config.endpoint}/ingest/traces`,
+      {
+        ...span,
+        product: this.config.product,
+        service: this.config.service,
+        environment: this.config.environment
+      },
+      "trace"
+    );
+    this.track(p);
+    return p;
   }
   async sendLLMUsage(report) {
-    try {
-      const res = await fetch(`${this.config.endpoint}/ingest/llm`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.apiKey}`
-        },
-        body: JSON.stringify({
-          ...report,
-          product: this.config.product,
-          service: this.config.service,
-          environment: this.config.environment
-        })
-      });
-      if (!res.ok) {
-        console.warn(
-          `[@deeptracer/core] Failed to send LLM usage: ${res.status} ${res.statusText}`
-        );
-      }
-    } catch {
-      console.warn("[@deeptracer/core] Failed to send LLM usage report");
-    }
+    const p = this.sendWithRetry(
+      `${this.config.endpoint}/ingest/llm`,
+      {
+        ...report,
+        product: this.config.product,
+        service: this.config.service,
+        environment: this.config.environment
+      },
+      "LLM usage"
+    );
+    this.track(p);
+    return p;
+  }
+  /**
+   * Wait for all in-flight requests to complete, with a timeout.
+   * Used by `logger.destroy()` to ensure data is sent before process exit.
+   *
+   * @param timeoutMs - Maximum time to wait (default: 2000ms)
+   */
+  async drain(timeoutMs = 2e3) {
+    if (this.inFlightRequests.size === 0) return;
+    const allDone = Promise.all(this.inFlightRequests).then(() => {
+    });
+    const timeout = new Promise((resolve) => setTimeout(resolve, timeoutMs));
+    await Promise.race([allDone, timeout]);
   }
 };
 
+// src/state.ts
+function createLoggerState(maxBreadcrumbs) {
+  return {
+    user: null,
+    tags: {},
+    contexts: {},
+    breadcrumbs: [],
+    maxBreadcrumbs
+  };
+}
+function addBreadcrumb(state, breadcrumb) {
+  state.breadcrumbs.push(breadcrumb);
+  if (state.breadcrumbs.length > state.maxBreadcrumbs) {
+    state.breadcrumbs.shift();
+  }
+}
+
 // src/logger.ts
 function generateId() {
   const bytes = new Uint8Array(8);
@@ -182,11 +233,13 @@ var Logger = class _Logger {
   transport;
   contextName;
   config;
+  state;
   requestMeta;
-  constructor(config, contextName, requestMeta) {
+  constructor(config, contextName, requestMeta, state) {
     this.config = config;
     this.contextName = contextName;
     this.requestMeta = requestMeta;
+    this.state = state ?? createLoggerState(config.maxBreadcrumbs ?? 20);
     this.transport = new Transport(config);
     this.batcher = new Batcher(
       { batchSize: config.batchSize, flushIntervalMs: config.flushIntervalMs },
@@ -195,6 +248,111 @@ var Logger = class _Logger {
       }
     );
   }
+  // ---------------------------------------------------------------------------
+  // User context
+  // ---------------------------------------------------------------------------
+  /**
+   * Set the current user context. Attached to all subsequent logs, errors, spans, and LLM reports.
+   * Shared across all child loggers (withContext, forRequest).
+   *
+   * @example
+   * ```ts
+   * logger.setUser({ id: "u_123", email: "user@example.com", plan: "pro" })
+   * ```
+   */
+  setUser(user) {
+    this.state.user = user;
+  }
+  /** Clear the current user context. */
+  clearUser() {
+    this.state.user = null;
+  }
+  // ---------------------------------------------------------------------------
+  // Tags & Context
+  // ---------------------------------------------------------------------------
+  /**
+   * Set global tags (flat string key-values). Merged into all events' metadata as `_tags`.
+   * Tags are indexed and searchable on the dashboard.
+   *
+   * @example
+   * ```ts
+   * logger.setTags({ release: "1.2.3", region: "us-east-1" })
+   * ```
+   */
+  setTags(tags) {
+    Object.assign(this.state.tags, tags);
+  }
+  /** Clear all global tags. */
+  clearTags() {
+    this.state.tags = {};
+  }
+  /**
+   * Set a named context block. Merged into metadata as `_contexts.{name}`.
+   * Contexts are structured objects attached for reference (not necessarily indexed).
+   *
+   * @example
+   * ```ts
+   * logger.setContext("server", { hostname: "web-3", memory: "4gb" })
+   * ```
+   */
+  setContext(name, data) {
+    this.state.contexts[name] = data;
+  }
+  /** Clear a specific context block, or all contexts if no name is given. */
+  clearContext(name) {
+    if (name) {
+      delete this.state.contexts[name];
+    } else {
+      this.state.contexts = {};
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Breadcrumbs
+  // ---------------------------------------------------------------------------
+  /**
+   * Manually add a breadcrumb to the trail.
+   * Breadcrumbs are also recorded automatically for every log, span, and error.
+   *
+   * @example
+   * ```ts
+   * logger.addBreadcrumb({ type: "http", message: "POST /api/checkout" })
+   * ```
+   */
+  addBreadcrumb(breadcrumb) {
+    addBreadcrumb(this.state, {
+      type: breadcrumb.type,
+      message: breadcrumb.message,
+      timestamp: breadcrumb.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Internal helpers
+  // ---------------------------------------------------------------------------
+  /** Merge user, tags, and contexts from shared state into event metadata. */
+  mergeStateMetadata(metadata) {
+    const { user, tags, contexts } = this.state;
+    const hasUser = user !== null;
+    const hasTags = Object.keys(tags).length > 0;
+    const hasContexts = Object.keys(contexts).length > 0;
+    if (!hasUser && !hasTags && !hasContexts && !metadata) return void 0;
+    const result = { ...metadata };
+    if (hasUser) result.user = user;
+    if (hasTags) result._tags = { ...tags };
+    if (hasContexts) result._contexts = { ...contexts };
+    return result;
+  }
+  /** Run the beforeSend hook. If the hook throws, pass the event through. */
+  applyBeforeSend(event) {
+    if (!this.config.beforeSend) return event;
+    try {
+      return this.config.beforeSend(event);
+    } catch {
+      return event;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Logging
+  // ---------------------------------------------------------------------------
   log(level, message, dataOrError, maybeError) {
     let metadata;
     let error;
@@ -216,6 +374,7 @@ var Logger = class _Logger {
         }
       };
     }
+    metadata = this.mergeStateMetadata(metadata);
     const entry = {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       level,
@@ -227,17 +386,25 @@ var Logger = class _Logger {
       request_id: this.requestMeta?.request_id,
       vercel_id: this.requestMeta?.vercel_id
     };
+    const hookResult = this.applyBeforeSend({ type: "log", data: entry });
+    if (hookResult === null) return;
+    const finalEntry = hookResult.data;
     if (this.config.debug) {
       const prefix = this.contextName ? `[${this.contextName}]` : "";
       const lvl = level.toUpperCase().padEnd(5);
       const consoleFn = level === "error" ? _originalConsole.error : level === "warn" ? _originalConsole.warn : level === "debug" ? _originalConsole.debug : _originalConsole.log;
-      if (metadata) {
-        consoleFn(`${lvl} ${prefix} ${message}`, metadata);
+      if (finalEntry.metadata) {
+        consoleFn(`${lvl} ${prefix} ${message}`, finalEntry.metadata);
       } else {
         consoleFn(`${lvl} ${prefix} ${message}`);
       }
     }
-    this.batcher.add(entry);
+    addBreadcrumb(this.state, {
+      type: "log",
+      message: `[${level}] ${message}`,
+      timestamp: entry.timestamp
+    });
+    this.batcher.add(finalEntry);
   }
   /** Log a debug message. */
   debug(message, dataOrError, error) {
@@ -255,11 +422,14 @@ var Logger = class _Logger {
   error(message, dataOrError, error) {
     this.log("error", message, dataOrError, error);
   }
-  /** Create a context-scoped logger. All logs include the context name. */
+  // ---------------------------------------------------------------------------
+  // Child loggers
+  // ---------------------------------------------------------------------------
+  /** Create a context-scoped logger. All logs include the context name. Shares state with parent. */
   withContext(name) {
-    return new _Logger(this.config, name, this.requestMeta);
+    return new _Logger(this.config, name, this.requestMeta, this.state);
   }
-  /** Create a request-scoped logger that extracts trace context from headers. */
+  /** Create a request-scoped logger that extracts trace context from headers. Shares state with parent. */
   forRequest(request) {
     const vercelId = request.headers.get("x-vercel-id") || void 0;
     const requestId = request.headers.get("x-request-id") || void 0;
@@ -270,25 +440,46 @@ var Logger = class _Logger {
       span_id: spanId,
       request_id: requestId || (vercelId ? vercelId.split("::").pop() : void 0),
       vercel_id: vercelId
-    });
+    }, this.state);
   }
-  /** Capture and report an error immediately (not batched). */
+  // ---------------------------------------------------------------------------
+  // Error capture
+  // ---------------------------------------------------------------------------
+  /**
+   * Capture and report an error immediately (not batched).
+   * Automatically attaches breadcrumbs from the buffer and user context.
+   */
   captureError(error, context) {
     const err = error instanceof Error ? error : new Error(String(error));
+    addBreadcrumb(this.state, {
+      type: "error",
+      message: err.message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const enrichedContext = { ...context?.context };
+    if (this.state.user) enrichedContext.user = this.state.user;
+    if (Object.keys(this.state.tags).length > 0) enrichedContext._tags = { ...this.state.tags };
+    if (Object.keys(this.state.contexts).length > 0) enrichedContext._contexts = { ...this.state.contexts };
     const report = {
       error_message: err.message,
       stack_trace: err.stack || "",
       severity: context?.severity || "medium",
-      context: context?.context,
+      context: Object.keys(enrichedContext).length > 0 ? enrichedContext : void 0,
       trace_id: this.requestMeta?.trace_id,
-      user_id: context?.userId,
-      breadcrumbs: context?.breadcrumbs
+      user_id: context?.userId || this.state.user?.id,
+      breadcrumbs: context?.breadcrumbs || [...this.state.breadcrumbs]
     };
-    this.transport.sendError(report);
+    const hookResult = this.applyBeforeSend({ type: "error", data: report });
+    if (hookResult === null) return;
+    this.transport.sendError(hookResult.data);
   }
+  // ---------------------------------------------------------------------------
+  // LLM usage
+  // ---------------------------------------------------------------------------
   /** Track LLM usage. Sends to /ingest/llm and logs for visibility. */
   llmUsage(report) {
-    this.transport.sendLLMUsage({
+    const metadata = this.mergeStateMetadata(report.metadata);
+    const payload = {
       model: report.model,
       provider: report.provider,
       operation: report.operation,
@@ -296,8 +487,11 @@ var Logger = class _Logger {
       output_tokens: report.outputTokens,
       cost_usd: report.costUsd || 0,
       latency_ms: report.latencyMs,
-      metadata: report.metadata
-    });
+      metadata
+    };
+    const hookResult = this.applyBeforeSend({ type: "llm", data: report });
+    if (hookResult === null) return;
+    this.transport.sendLLMUsage(payload);
     this.log("info", `LLM call: ${report.model} (${report.operation})`, {
       llm_usage: {
         model: report.model,
@@ -309,6 +503,9 @@ var Logger = class _Logger {
       }
     });
   }
+  // ---------------------------------------------------------------------------
+  // Tracing
+  // ---------------------------------------------------------------------------
   /** Start a span with automatic lifecycle (callback-based, recommended). */
   startSpan(operation, fn) {
     const inactive = this.startInactiveSpan(operation);
@@ -349,6 +546,11 @@ var Logger = class _Logger {
     const startTime = (/* @__PURE__ */ new Date()).toISOString();
     const startMs = Date.now();
     const childMeta = { ...this.requestMeta, trace_id: traceId, span_id: spanId };
+    addBreadcrumb(this.state, {
+      type: "function",
+      message: operation,
+      timestamp: startTime
+    });
     const span = {
       traceId,
       spanId,
@@ -364,16 +566,18 @@ var Logger = class _Logger {
           start_time: startTime,
           duration_ms: durationMs,
           status: options?.status || "ok",
-          metadata: options?.metadata
+          metadata: this.mergeStateMetadata(options?.metadata)
         };
-        this.transport.sendTrace(spanData);
+        const hookResult = this.applyBeforeSend({ type: "trace", data: spanData });
+        if (hookResult === null) return;
+        this.transport.sendTrace(hookResult.data);
       },
       startSpan: (childOp, fn) => {
-        const childLogger = new _Logger(this.config, this.contextName, childMeta);
+        const childLogger = new _Logger(this.config, this.contextName, childMeta, this.state);
         return childLogger.startSpan(childOp, fn);
       },
       startInactiveSpan: (childOp) => {
-        const childLogger = new _Logger(this.config, this.contextName, childMeta);
+        const childLogger = new _Logger(this.config, this.contextName, childMeta, this.state);
         return childLogger.startInactiveSpan(childOp);
       },
       getHeaders: () => ({
@@ -389,13 +593,28 @@ var Logger = class _Logger {
       return this.startSpan(operation, () => fn(...args));
     };
   }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
   /** Immediately flush all batched log entries. */
   flush() {
     this.batcher.flush();
   }
-  /** Stop the batch timer and flush remaining logs. */
-  destroy() {
-    this.batcher.destroy();
+  /**
+   * Stop the batch timer, flush remaining logs, and wait for in-flight requests.
+   *
+   * @param timeoutMs - Max time to wait for in-flight requests (default: 2000ms)
+   * @returns Promise that resolves when all data is sent or timeout is reached
+   *
+   * @example
+   * ```ts
+   * await logger.destroy()
+   * process.exit(0) // safe — data is confirmed sent
+   * ```
+   */
+  async destroy(timeoutMs) {
+    await this.batcher.destroy();
+    await this.transport.drain(timeoutMs);
   }
 };
 function createLogger(config) {
@@ -404,5 +623,7 @@ function createLogger(config) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Logger,
+  SDK_NAME,
+  SDK_VERSION,
   createLogger
 });