@deeptracer/core 0.2.0 → 0.3.0

package/dist/chunk-BRUVRV5O.js

@@ -0,0 +1,601 @@
+// src/version.ts
+var SDK_VERSION = "0.3.0";
+var SDK_NAME = "core";
+
+// src/batcher.ts
+var Batcher = class {
+  constructor(config, onFlush) {
+    this.onFlush = onFlush;
+    this.batchSize = config.batchSize ?? 50;
+    this.flushIntervalMs = config.flushIntervalMs ?? 5e3;
+    this.startTimer();
+  }
+  buffer = [];
+  timer = null;
+  batchSize;
+  flushIntervalMs;
+  add(entry) {
+    this.buffer.push(entry);
+    if (this.buffer.length >= this.batchSize) {
+      this.flush();
+    }
+  }
+  flush() {
+    if (this.buffer.length === 0) return;
+    const entries = [...this.buffer];
+    this.buffer = [];
+    this.onFlush(entries);
+  }
+  startTimer() {
+    this.timer = setInterval(() => this.flush(), this.flushIntervalMs);
+  }
+  async destroy() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.flush();
+  }
+};
+
+// src/transport.ts
+var Transport = class {
+  constructor(config) {
+    this.config = config;
+  }
+  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 ${label}: ${res.status} ${res.statusText} (exhausted ${maxRetries} retries)`
+        );
+      } catch {
+        if (attempt < maxRetries) {
+          await this.sleep(this.jitter(baseDelays[attempt]));
+          continue;
+        }
+        console.warn(
+          `[@deeptracer/core] Failed to send ${label} (exhausted ${maxRetries} retries)`
+        );
+      }
+    }
+  }
+  /** 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) {
+    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) {
+    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);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+var _originalConsole = {
+  log: console.log,
+  info: console.info,
+  warn: console.warn,
+  error: console.error,
+  debug: console.debug
+};
+var Logger = class _Logger {
+  batcher;
+  transport;
+  contextName;
+  config;
+  state;
+  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 },
+      (entries) => {
+        this.transport.sendLogs(entries);
+      }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // 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;
+    if (dataOrError instanceof Error) {
+      error = dataOrError;
+    } else if (dataOrError && typeof dataOrError === "object" && !Array.isArray(dataOrError)) {
+      metadata = dataOrError;
+      error = maybeError;
+    } else if (dataOrError !== void 0) {
+      error = dataOrError;
+    }
+    if (error instanceof Error) {
+      metadata = {
+        ...metadata,
+        error: {
+          message: error.message,
+          name: error.name,
+          stack: error.stack
+        }
+      };
+    }
+    metadata = this.mergeStateMetadata(metadata);
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      message,
+      metadata,
+      context: this.contextName,
+      trace_id: this.requestMeta?.trace_id,
+      span_id: this.requestMeta?.span_id,
+      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 (finalEntry.metadata) {
+        consoleFn(`${lvl} ${prefix} ${message}`, finalEntry.metadata);
+      } else {
+        consoleFn(`${lvl} ${prefix} ${message}`);
+      }
+    }
+    addBreadcrumb(this.state, {
+      type: "log",
+      message: `[${level}] ${message}`,
+      timestamp: entry.timestamp
+    });
+    this.batcher.add(finalEntry);
+  }
+  /** Log a debug message. */
+  debug(message, dataOrError, error) {
+    this.log("debug", message, dataOrError, error);
+  }
+  /** Log an informational message. */
+  info(message, dataOrError, error) {
+    this.log("info", message, dataOrError, error);
+  }
+  /** Log a warning. */
+  warn(message, dataOrError, error) {
+    this.log("warn", message, dataOrError, error);
+  }
+  /** Log an error. */
+  error(message, dataOrError, error) {
+    this.log("error", message, dataOrError, error);
+  }
+  // ---------------------------------------------------------------------------
+  // 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, this.state);
+  }
+  /** 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;
+    const traceId = request.headers.get("x-trace-id") || void 0;
+    const spanId = request.headers.get("x-span-id") || void 0;
+    return new _Logger(this.config, this.contextName, {
+      trace_id: traceId,
+      span_id: spanId,
+      request_id: requestId || (vercelId ? vercelId.split("::").pop() : void 0),
+      vercel_id: vercelId
+    }, this.state);
+  }
+  // ---------------------------------------------------------------------------
+  // 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: Object.keys(enrichedContext).length > 0 ? enrichedContext : void 0,
+      trace_id: this.requestMeta?.trace_id,
+      user_id: context?.userId || this.state.user?.id,
+      breadcrumbs: context?.breadcrumbs || [...this.state.breadcrumbs]
+    };
+    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) {
+    const metadata = this.mergeStateMetadata(report.metadata);
+    const payload = {
+      model: report.model,
+      provider: report.provider,
+      operation: report.operation,
+      input_tokens: report.inputTokens,
+      output_tokens: report.outputTokens,
+      cost_usd: report.costUsd || 0,
+      latency_ms: report.latencyMs,
+      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,
+        provider: report.provider,
+        operation: report.operation,
+        input_tokens: report.inputTokens,
+        output_tokens: report.outputTokens,
+        latency_ms: report.latencyMs
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Tracing
+  // ---------------------------------------------------------------------------
+  /** Start a span with automatic lifecycle (callback-based, recommended). */
+  startSpan(operation, fn) {
+    const inactive = this.startInactiveSpan(operation);
+    const span = {
+      traceId: inactive.traceId,
+      spanId: inactive.spanId,
+      parentSpanId: inactive.parentSpanId,
+      operation: inactive.operation,
+      getHeaders: () => inactive.getHeaders()
+    };
+    let result;
+    try {
+      result = fn(span);
+    } catch (err) {
+      inactive.end({ status: "error" });
+      throw err;
+    }
+    if (result instanceof Promise) {
+      return result.then(
+        (value) => {
+          inactive.end({ status: "ok" });
+          return value;
+        },
+        (err) => {
+          inactive.end({ status: "error" });
+          throw err;
+        }
+      );
+    }
+    inactive.end({ status: "ok" });
+    return result;
+  }
+  /** Start a span with manual lifecycle. You must call span.end(). */
+  startInactiveSpan(operation) {
+    const traceId = this.requestMeta?.trace_id || generateId();
+    const parentSpanId = this.requestMeta?.span_id || "";
+    const spanId = generateId();
+    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,
+      parentSpanId,
+      operation,
+      end: (options) => {
+        const durationMs = Date.now() - startMs;
+        const spanData = {
+          trace_id: traceId,
+          span_id: spanId,
+          parent_span_id: parentSpanId,
+          operation,
+          start_time: startTime,
+          duration_ms: durationMs,
+          status: options?.status || "ok",
+          metadata: this.mergeStateMetadata(options?.metadata)
+        };
+        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, this.state);
+        return childLogger.startSpan(childOp, fn);
+      },
+      startInactiveSpan: (childOp) => {
+        const childLogger = new _Logger(this.config, this.contextName, childMeta, this.state);
+        return childLogger.startInactiveSpan(childOp);
+      },
+      getHeaders: () => ({
+        "x-trace-id": traceId,
+        "x-span-id": spanId
+      })
+    };
+    return span;
+  }
+  /** Wrap a function with automatic tracing and error capture. */
+  wrap(operation, fn) {
+    return (...args) => {
+      return this.startSpan(operation, () => fn(...args));
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  /** Immediately flush all batched log entries. */
+  flush() {
+    this.batcher.flush();
+  }
+  /**
+   * 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) {
+  return new Logger(config);
+}
+
+export {
+  SDK_VERSION,
+  SDK_NAME,
+  _originalConsole,
+  Logger,
+  createLogger
+};