@deeptracer/core 0.2.0

package/dist/index.cjs

@@ -0,0 +1,408 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Logger: () => Logger,
+  createLogger: () => createLogger
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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);
+  }
+  destroy() {
+    if (this.timer) clearInterval(this.timer);
+    this.flush();
+  }
+};
+
+// 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) {
+        console.warn(
+          `[@deeptracer/core] Failed to send logs: ${res.status} ${res.statusText}`
+        );
+      }
+    } 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) {
+        console.warn(
+          `[@deeptracer/core] Failed to send error: ${res.status} ${res.statusText}`
+        );
+      }
+    } catch {
+      console.warn("[@deeptracer/core] Failed to send error report");
+      console.error(error.error_message);
+    }
+  }
+  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");
+    }
+  }
+  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");
+    }
+  }
+};
+
+// 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;
+  requestMeta;
+  constructor(config, contextName, requestMeta) {
+    this.config = config;
+    this.contextName = contextName;
+    this.requestMeta = requestMeta;
+    this.transport = new Transport(config);
+    this.batcher = new Batcher(
+      { batchSize: config.batchSize, flushIntervalMs: config.flushIntervalMs },
+      (entries) => {
+        this.transport.sendLogs(entries);
+      }
+    );
+  }
+  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
+        }
+      };
+    }
+    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
+    };
+    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);
+      } else {
+        consoleFn(`${lvl} ${prefix} ${message}`);
+      }
+    }
+    this.batcher.add(entry);
+  }
+  /** 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);
+  }
+  /** Create a context-scoped logger. All logs include the context name. */
+  withContext(name) {
+    return new _Logger(this.config, name, this.requestMeta);
+  }
+  /** Create a request-scoped logger that extracts trace context from headers. */
+  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
+    });
+  }
+  /** Capture and report an error immediately (not batched). */
+  captureError(error, context) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const report = {
+      error_message: err.message,
+      stack_trace: err.stack || "",
+      severity: context?.severity || "medium",
+      context: context?.context,
+      trace_id: this.requestMeta?.trace_id,
+      user_id: context?.userId,
+      breadcrumbs: context?.breadcrumbs
+    };
+    this.transport.sendError(report);
+  }
+  /** Track LLM usage. Sends to /ingest/llm and logs for visibility. */
+  llmUsage(report) {
+    this.transport.sendLLMUsage({
+      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: report.metadata
+    });
+    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
+      }
+    });
+  }
+  /** 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 };
+    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: options?.metadata
+        };
+        this.transport.sendTrace(spanData);
+      },
+      startSpan: (childOp, fn) => {
+        const childLogger = new _Logger(this.config, this.contextName, childMeta);
+        return childLogger.startSpan(childOp, fn);
+      },
+      startInactiveSpan: (childOp) => {
+        const childLogger = new _Logger(this.config, this.contextName, childMeta);
+        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));
+    };
+  }
+  /** Immediately flush all batched log entries. */
+  flush() {
+    this.batcher.flush();
+  }
+  /** Stop the batch timer and flush remaining logs. */
+  destroy() {
+    this.batcher.destroy();
+  }
+};
+function createLogger(config) {
+  return new Logger(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Logger,
+  createLogger
+});

package/dist/index.d.cts

@@ -0,0 +1,221 @@
+/**
+ * Configuration for creating a DeepTracer logger instance.
+ *
+ * @example
+ * ```ts
+ * const config: LoggerConfig = {
+ *   product: "my-app",
+ *   service: "api-server",
+ *   environment: "production",
+ *   endpoint: "https://deeptracer.example.com",
+ *   apiKey: "dt_live_xxx",
+ * }
+ * ```
+ */
+interface LoggerConfig {
+    /** Product name (e.g., "spotbeam", "macro") */
+    product: string;
+    /** Service name (e.g., "api", "worker", "web") */
+    service: string;
+    /** Deployment environment */
+    environment: "production" | "staging";
+    /** DeepTracer ingestion endpoint URL */
+    endpoint: string;
+    /** DeepTracer API key for authentication */
+    apiKey: string;
+    /** Number of log entries to batch before sending. Default: 50 */
+    batchSize?: number;
+    /** Milliseconds between automatic batch flushes. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Enable console output for all log calls (useful for local development) */
+    debug?: boolean;
+}
+/** Log severity level */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * A single log entry sent to the DeepTracer backend.
+ * Created internally by the Logger — you don't construct these manually.
+ */
+interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    metadata?: Record<string, unknown>;
+    trace_id?: string;
+    span_id?: string;
+    request_id?: string;
+    vercel_id?: string;
+    context?: string;
+}
+/**
+ * Error report sent to DeepTracer for tracking and alerting.
+ */
+interface ErrorReport {
+    error_message: string;
+    stack_trace: string;
+    severity: "low" | "medium" | "high" | "critical";
+    context?: Record<string, unknown>;
+    trace_id?: string;
+    user_id?: string;
+    breadcrumbs?: Array<{
+        type: string;
+        message: string;
+        timestamp: string;
+    }>;
+}
+/**
+ * LLM usage report for tracking AI costs and performance.
+ */
+interface LLMUsageReport {
+    model: string;
+    provider: string;
+    operation: string;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    costUsd?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Raw span data sent to the DeepTracer backend.
+ */
+interface SpanData {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string;
+    operation: string;
+    start_time: string;
+    duration_ms: number;
+    status: "ok" | "error";
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A span representing a unit of work within a trace.
+ * Returned by the callback-based `startSpan()` — lifecycle is managed automatically.
+ */
+interface Span {
+    /** Trace ID linking all spans in a distributed trace */
+    traceId: string;
+    /** Unique ID for this span */
+    spanId: string;
+    /** ID of the parent span (empty string if root span) */
+    parentSpanId: string;
+    /** Operation name (e.g., "db-query", "fetch-user") */
+    operation: string;
+    /** Returns headers for propagating trace context to downstream services */
+    getHeaders(): Record<string, string>;
+}
+/**
+ * A span with manual lifecycle control. You must call `.end()` when done.
+ */
+interface InactiveSpan extends Span {
+    /** End the span and send timing data to DeepTracer */
+    end(options?: {
+        status?: "ok" | "error";
+        metadata?: Record<string, unknown>;
+    }): void;
+    /** Create a child span with callback-based lifecycle (auto-ends) */
+    startSpan<T>(operation: string, fn: (span: Span) => T): T;
+    /** Create a child span with manual lifecycle (you must call .end()) */
+    startInactiveSpan(operation: string): InactiveSpan;
+}
+/**
+ * Options for HTTP middleware (Hono, Express).
+ */
+interface MiddlewareOptions {
+    /** Custom function to generate the span operation name. Default: "{METHOD} {path}" */
+    operationName?: (method: string, path: string) => string;
+    /** Paths to exclude from tracing (e.g., ["/health", "/ready"]) */
+    ignorePaths?: string[];
+}
+
+/**
+ * Original console methods, preserved before any interception.
+ * Used internally by the Logger's debug output to avoid infinite loops
+ * when captureConsole() is active.
+ *
+ * @internal Exported for use by @deeptracer/node and @deeptracer/browser.
+ */
+declare const _originalConsole: {
+    log: (...data: any[]) => void;
+    info: (...data: any[]) => void;
+    warn: (...data: any[]) => void;
+    error: (...data: any[]) => void;
+    debug: (...data: any[]) => void;
+};
+/**
+ * DeepTracer Logger — lightweight observability SDK for logging, errors, tracing, and LLM usage.
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from "@deeptracer/core"
+ *
+ * const logger = createLogger({
+ *   product: "my-app",
+ *   service: "api",
+ *   environment: "production",
+ *   endpoint: "https://deeptracer.example.com",
+ *   apiKey: "dt_live_xxx",
+ * })
+ *
+ * logger.info("Server started", { port: 3000 })
+ * ```
+ */
+declare class Logger {
+    private batcher;
+    private transport;
+    protected contextName?: string;
+    protected config: LoggerConfig;
+    protected requestMeta?: {
+        trace_id?: string;
+        span_id?: string;
+        request_id?: string;
+        vercel_id?: string;
+    };
+    constructor(config: LoggerConfig, contextName?: string, requestMeta?: {
+        trace_id?: string;
+        span_id?: string;
+        request_id?: string;
+        vercel_id?: string;
+    });
+    private log;
+    /** Log a debug message. */
+    debug(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Log an informational message. */
+    info(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Log a warning. */
+    warn(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Log an error. */
+    error(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Create a context-scoped logger. All logs include the context name. */
+    withContext(name: string): Logger;
+    /** Create a request-scoped logger that extracts trace context from headers. */
+    forRequest(request: Request): Logger;
+    /** Capture and report an error immediately (not batched). */
+    captureError(error: Error | unknown, context?: {
+        severity?: "low" | "medium" | "high" | "critical";
+        userId?: string;
+        context?: Record<string, unknown>;
+        breadcrumbs?: Array<{
+            type: string;
+            message: string;
+            timestamp: string;
+        }>;
+    }): void;
+    /** Track LLM usage. Sends to /ingest/llm and logs for visibility. */
+    llmUsage(report: LLMUsageReport): void;
+    /** Start a span with automatic lifecycle (callback-based, recommended). */
+    startSpan<T>(operation: string, fn: (span: Span) => T): T;
+    /** Start a span with manual lifecycle. You must call span.end(). */
+    startInactiveSpan(operation: string): InactiveSpan;
+    /** Wrap a function with automatic tracing and error capture. */
+    wrap<TArgs extends unknown[], TReturn>(operation: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /** Immediately flush all batched log entries. */
+    flush(): void;
+    /** Stop the batch timer and flush remaining logs. */
+    destroy(): void;
+}
+/** Create a new DeepTracer logger instance. */
+declare function createLogger(config: LoggerConfig): Logger;
+
+export { type ErrorReport, type InactiveSpan, type LLMUsageReport, type LogEntry, type LogLevel, Logger, type LoggerConfig, type MiddlewareOptions, type Span, type SpanData, _originalConsole as _, createLogger };