@tracewayapp/backend 0.2.0

package/README.md

@@ -0,0 +1,368 @@
+# @tracewayapp/backend
+
+Traceway SDK for Node.js backends. Core telemetry collection library.
+
+## Quick Start
+
+```ts
+import * as traceway from "@tracewayapp/backend";
+
+traceway.init("your-token@https://your-traceway-server.com/api/report", {
+  version: "1.0.0",
+  debug: true,
+});
+
+// Capture an error
+traceway.captureException(new Error("something broke"));
+
+// Capture a message
+traceway.captureMessage("Deployment completed");
+
+// Capture a custom metric
+traceway.captureMetric("queue.length", 42);
+
+// Graceful shutdown
+await traceway.shutdown();
+```
+
+## Architecture
+
+### Two Modes of Operation
+
+The SDK supports both **manual** and **automatic** context propagation:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Your Application                             │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌─────────────────────────────────────────────────────────────┐    │
+│  │                   AsyncLocalStorage                          │    │
+│  │  ┌─────────────────────────────────────────────────────┐    │    │
+│  │  │ TraceContext (per request/task)                      │    │    │
+│  │  │  - traceId: string                                   │    │    │
+│  │  │  - spans: Span[]                                     │    │    │
+│  │  │  - attributes: Record<string, string>                │    │    │
+│  │  │  - startedAt: Date                                   │    │    │
+│  │  │  - statusCode, bodySize, clientIP, endpoint          │    │    │
+│  │  └─────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────┘    │
+│                              │                                       │
+│    withTraceContext() ───────┘                                       │
+│                                                                      │
+│  captureException() ──────► auto-detects context ──────┐            │
+│  captureMessage() ────────► auto-detects context ──────┤            │
+│  endSpan() ───────────────► auto-adds to context ──────┤            │
+│  captureCurrentTrace() ───► reads from context ────────┤            │
+│                                                        ▼            │
+│                                            ┌────────────────────┐   │
+│                                            │ CollectionFrameStore│   │
+│                                            │ (global singleton)  │   │
+│                                            └────────────────────┘   │
+│                                                        │            │
+│                                               gzip + POST           │
+│                                                        ▼            │
+│                                                  Traceway API       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Automatic Context Propagation (Recommended)
+
+The SDK uses Node.js `AsyncLocalStorage` to automatically propagate trace context through async operations:
+
+```ts
+import * as traceway from "@tracewayapp/backend";
+
+traceway.init("token@https://api.traceway.io/api/report");
+
+// Wrap your request handler
+app.get("/api/users", (req, res) => {
+  traceway.withTraceContext(
+    { endpoint: `${req.method} ${req.path}`, clientIP: req.ip },
+    async () => {
+      // All operations inside automatically belong to this trace
+
+      const span = traceway.startSpan("db-query");
+      const users = await db.query("SELECT * FROM users");
+      traceway.endSpan(span); // Auto-added to trace context
+
+      // Exceptions auto-link to trace
+      if (!users.length) {
+        traceway.captureMessage("No users found");
+      }
+
+      res.json(users);
+
+      // Capture the trace at the end
+      traceway.setTraceResponseInfo(200, JSON.stringify(users).length);
+      traceway.captureCurrentTrace();
+    }
+  );
+});
+```
+
+### Context API
+
+| Function | Description |
+|----------|-------------|
+| `withTraceContext(options, fn)` | Run function within a new trace context |
+| `getTraceContext()` | Get current context (or undefined) |
+| `getTraceId()` | Get current trace ID (or undefined) |
+| `hasTraceContext()` | Check if inside a trace context |
+| `setTraceAttribute(key, value)` | Set attribute on current trace |
+| `setTraceAttributes(attrs)` | Set multiple attributes |
+| `setTraceResponseInfo(status, size?)` | Set HTTP response info |
+| `addSpanToContext(span)` | Manually add a span |
+| `getTraceSpans()` | Get all spans in current trace |
+| `getTraceDuration()` | Get elapsed time in ms |
+| `forkTraceContext(fn)` | Fork context for parallel ops |
+| `captureCurrentTrace()` | Capture trace from context |
+
+### Building Framework Middleware
+
+The context API makes it easy to build framework-specific middleware:
+
+```ts
+// Express middleware
+import * as traceway from "@tracewayapp/backend";
+
+export function tracewayMiddleware() {
+  return (req, res, next) => {
+    traceway.withTraceContext(
+      {
+        endpoint: `${req.method} ${req.path}`,
+        clientIP: req.ip,
+        attributes: { userAgent: req.get("User-Agent") || "" },
+      },
+      () => {
+        // Intercept response to capture trace
+        const originalEnd = res.end;
+        res.end = function (...args) {
+          traceway.setTraceResponseInfo(
+            res.statusCode,
+            res.get("Content-Length") ? parseInt(res.get("Content-Length")) : 0
+          );
+          traceway.captureCurrentTrace();
+          return originalEnd.apply(this, args);
+        };
+
+        next();
+      }
+    );
+  };
+}
+
+// Usage
+app.use(tracewayMiddleware());
+app.get("/api/users", async (req, res) => {
+  // Context is already set up - just use the SDK
+  const span = traceway.startSpan("fetch-users");
+  try {
+    const users = await getUsers();
+    traceway.endSpan(span);
+    res.json(users);
+  } catch (err) {
+    traceway.endSpan(span);
+    traceway.captureException(err); // Auto-linked to request trace
+    res.status(500).json({ error: "Internal error" });
+  }
+});
+```
+
+```ts
+// Fastify plugin
+import * as traceway from "@tracewayapp/backend";
+
+export const tracewayPlugin = (fastify, opts, done) => {
+  fastify.addHook("onRequest", (request, reply, done) => {
+    traceway.withTraceContext(
+      {
+        endpoint: `${request.method} ${request.url}`,
+        clientIP: request.ip,
+      },
+      () => done()
+    );
+  });
+
+  fastify.addHook("onResponse", (request, reply, done) => {
+    traceway.setTraceResponseInfo(reply.statusCode);
+    traceway.captureCurrentTrace();
+    done();
+  });
+
+  done();
+};
+```
+
+### Manual Mode (Legacy)
+
+You can still use explicit parameter passing if preferred:
+
+```ts
+import * as traceway from "@tracewayapp/backend";
+import { generateUUID } from "@tracewayapp/core";
+
+const traceId = generateUUID();
+const spans: Span[] = [];
+
+const span = traceway.startSpan("operation");
+// ... do work ...
+spans.push(traceway.endSpan(span, false)); // false = don't auto-add to context
+
+traceway.captureTrace(traceId, "GET /api", 150, new Date(), 200, 1024, "127.0.0.1", {}, spans);
+traceway.captureExceptionWithAttributes(err, {}, traceId);
+```
+
+## Public API
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `init(connectionString, options?)` | Initialize the SDK (throws if already initialized) |
+| `shutdown()` | Stop timers, flush remaining data, and await final upload |
+
+### Capture Functions
+
+| Function | Description |
+|----------|-------------|
+| `captureException(error)` | Capture error (auto-detects trace context) |
+| `captureExceptionWithAttributes(error, attrs?, traceId?)` | Capture with explicit context |
+| `captureMessage(msg, attrs?)` | Capture message (auto-detects trace context) |
+| `captureMetric(name, value)` | Capture a custom metric |
+| `captureTrace(...)` | Capture HTTP trace (manual mode) |
+| `captureTask(...)` | Capture background task (manual mode) |
+| `captureCurrentTrace()` | Capture trace from current context |
+
+### Span Functions
+
+| Function | Description |
+|----------|-------------|
+| `startSpan(name)` | Start a span (returns `SpanHandle`) |
+| `endSpan(span, addToContext?)` | End span (auto-adds to context by default) |
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `shouldSample(isError)` | Check if trace should be recorded |
+| `measureTask(title, fn)` | Execute function as auto-captured task |
+
+### Span Handle vs Span Object
+
+`startSpan()` returns a **span handle** for tracking:
+```ts
+interface SpanHandle {
+  id: string;        // UUID
+  name: string;      // Operation name
+  startTime: string; // ISO timestamp
+  startedAt: number; // Unix ms (for duration calc)
+}
+```
+
+`endSpan()` returns a **Span object** for the trace:
+```ts
+interface Span {
+  id: string;        // Same UUID
+  name: string;      // Operation name
+  startTime: string; // ISO timestamp
+  duration: number;  // Nanoseconds
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean` | `false` | Enable debug logging to console |
+| `maxCollectionFrames` | `number` | `12` | Ring buffer capacity for pending frames |
+| `collectionInterval` | `number` | `5000` | Frame rotation interval (ms) |
+| `uploadThrottle` | `number` | `2000` | Minimum gap between uploads (ms) |
+| `metricsInterval` | `number` | `30000` | System metrics collection interval (ms) |
+| `version` | `string` | `""` | Application version sent with reports |
+| `serverName` | `string` | hostname | Server identifier sent with reports |
+| `sampleRate` | `number` | `1.0` | Normal trace sampling rate (0.0-1.0) |
+| `errorSampleRate` | `number` | `1.0` | Error trace sampling rate (0.0-1.0) |
+
+## Collection Frame Lifecycle
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ 1. COLLECT                                                        │
+│    captureException/Trace/Metric ──► Current CollectionFrame     │
+│                                                                   │
+│ 2. ROTATE (every collectionInterval ms)                          │
+│    Current frame ──► Send Queue (ring buffer, max 12 frames)     │
+│                                                                   │
+│ 3. UPLOAD (respects uploadThrottle)                              │
+│    Send Queue ──► gzip ──► POST /api/report                      │
+│    Headers: Authorization: Bearer {token}                        │
+│             Content-Type: application/json                        │
+│             Content-Encoding: gzip                                │
+│                                                                   │
+│ 4. CLEANUP                                                        │
+│    200 OK ──► Remove frames from queue                           │
+│    Failure ──► Retain frames for retry                           │
+│                                                                   │
+│ 5. SHUTDOWN                                                       │
+│    shutdown() ──► Rotate current ──► Upload all ──► Stop timers  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Auto-Collected Metrics
+
+Every `metricsInterval` ms (default: 30s), these metrics are automatically captured:
+
+| Name | Description | Unit |
+|------|-------------|------|
+| `mem.used` | Process RSS memory | MB |
+| `mem.total` | Total system memory | MB |
+| `cpu.used_pcnt` | CPU usage (delta-based) | % (0-100) |
+
+## Sampling
+
+Use sampling to reduce data volume in high-traffic applications:
+
+```ts
+traceway.init(connectionString, {
+  sampleRate: 0.1,      // Record 10% of normal traces
+  errorSampleRate: 1.0, // Record 100% of error traces
+});
+
+// In your code, check before capturing:
+if (traceway.shouldSample(isError)) {
+  traceway.captureTrace(...);
+}
+```
+
+The `measureTask()` function automatically respects sampling rates.
+
+## Comparison with Go Client
+
+| Go Client Feature | JS Backend Equivalent |
+|-------------------|----------------------|
+| `Init(connectionString, opts...)` | `init(connectionString, options)` |
+| `StartTrace(ctx) context.Context` | `withTraceContext(options, fn)` |
+| `GetTraceFromContext(ctx)` | `getTraceContext()` |
+| `GetTraceIdFromContext(ctx)` | `getTraceId()` |
+| `GetAttributesFromContext(ctx)` | `getTraceContext()?.attributes` |
+| `WithAttributes(ctx, fn)` | `setTraceAttribute()` / `setTraceAttributes()` |
+| `StartSpan(ctx, name)` | `startSpan(name)` (auto-adds on `endSpan()`) |
+| `CaptureException(err)` | `captureException(err)` (auto-detects context) |
+| `CaptureExceptionWithContext(ctx, err)` | `captureException(err)` inside `withTraceContext()` |
+| `CaptureTrace(tc, ...)` | `captureCurrentTrace()` or `captureTrace(...)` |
+| `CaptureTask(tc, ...)` | `captureCurrentTrace()` with `isTask: true` |
+| `MeasureTask(title, fn)` | `measureTask(title, fn)` |
+| `Recover()` / `RecoverWithContext(ctx)` | Use try/catch with `captureException()` |
+| `tracewayhttp.New(...)` | Build with `withTraceContext()` (see examples) |
+| `tracewaygin.New(...)` | Build with `withTraceContext()` (see examples) |
+| `tracewaydb.NewTwDB(...)` | Wrap DB calls with `startSpan()`/`endSpan()` |
+
+## Thread Safety
+
+The SDK is designed for concurrent use in Node.js:
+- `AsyncLocalStorage` provides request isolation automatically
+- `CollectionFrameStore` uses synchronous operations (Node.js event loop)
+- Timer callbacks are non-blocking via `unref()`
+- `shutdown()` is async and awaits the final upload
+- Parallel requests each get their own isolated trace context

package/dist/index.d.mts

@@ -0,0 +1,232 @@
+import { Span, TracewayOptions, MetricRecord, ExceptionStackTrace, Trace } from '@tracewayapp/core';
+export { CollectionFrame, ExceptionStackTrace, MetricRecord, ReportRequest, Span, Trace, TracewayOptions } from '@tracewayapp/core';
+import { AsyncLocalStorage } from 'async_hooks';
+
+declare function init(connectionString: string, options?: TracewayOptions): void;
+declare function captureException(error: Error): void;
+declare function captureExceptionWithAttributes(error: Error, attributes?: Record<string, string>, traceId?: string): void;
+declare function captureMessage(msg: string, attributes?: Record<string, string>): void;
+declare function captureMetric(name: string, value: number): void;
+declare function captureTrace(traceId: string, endpoint: string, durationMs: number, startedAt: Date, statusCode: number, bodySize: number, clientIP: string, attributes?: Record<string, string>, spans?: Span[]): void;
+declare function captureTask(traceId: string, taskName: string, durationMs: number, startedAt: Date, attributes?: Record<string, string>, spans?: Span[]): void;
+/** Handle returned by startSpan for tracking span timing */
+interface SpanHandle {
+    id: string;
+    name: string;
+    startTime: string;
+    startedAt: number;
+}
+/**
+ * Start a new span. If within a trace context, the span will be
+ * automatically added to the trace when ended.
+ */
+declare function startSpan(name: string): SpanHandle;
+/**
+ * End a span and get the completed Span object.
+ * If within a trace context, automatically adds the span to the trace.
+ *
+ * @param addToContext - If true (default), adds span to current trace context
+ */
+declare function endSpan(span: SpanHandle, addToContext?: boolean): Span;
+/**
+ * Capture the current trace context as a trace.
+ * Call this at the end of a request/task to record the trace.
+ *
+ * @example
+ * ```ts
+ * // In Express middleware (after response)
+ * withTraceContext({ endpoint: `${req.method} ${req.path}` }, async () => {
+ *   await handleRequest(req, res);
+ *   setTraceResponseInfo(res.statusCode, contentLength);
+ *   captureCurrentTrace(); // Records the trace with all spans
+ * });
+ * ```
+ */
+declare function captureCurrentTrace(): void;
+declare function shouldSample(isError: boolean): boolean;
+declare function measureTask(title: string, fn: () => void | Promise<void>): void;
+declare function shutdown(): Promise<void>;
+
+/**
+ * Trace context stored in AsyncLocalStorage.
+ * Automatically propagates through async operations.
+ */
+interface TraceContext {
+    /** Unique trace identifier (UUID v4) */
+    traceId: string;
+    /** Whether this is a background task (vs HTTP request) */
+    isTask: boolean;
+    /** When the trace started */
+    startedAt: Date;
+    /** Collected spans within this trace */
+    spans: Span[];
+    /** Key-value attributes for this trace */
+    attributes: Record<string, string>;
+    /** For HTTP traces: endpoint like "GET /api/users" */
+    endpoint?: string;
+    /** For HTTP traces: response status code */
+    statusCode?: number;
+    /** For HTTP traces: response body size */
+    bodySize?: number;
+    /** For HTTP traces: client IP address */
+    clientIP?: string;
+}
+/**
+ * Options for creating a new trace context.
+ */
+interface TraceContextOptions {
+    /** Custom trace ID (auto-generated if not provided) */
+    traceId?: string;
+    /** Mark as background task instead of HTTP trace */
+    isTask?: boolean;
+    /** Initial attributes */
+    attributes?: Record<string, string>;
+    /** HTTP endpoint (e.g., "GET /api/users") */
+    endpoint?: string;
+    /** Client IP address */
+    clientIP?: string;
+}
+declare const asyncLocalStorage: AsyncLocalStorage<TraceContext>;
+/**
+ * Get the current trace context, if any.
+ * Returns undefined if not within a trace context.
+ */
+declare function getTraceContext(): TraceContext | undefined;
+/**
+ * Get the current trace ID, if within a trace context.
+ */
+declare function getTraceId(): string | undefined;
+/**
+ * Check if currently within a trace context.
+ */
+declare function hasTraceContext(): boolean;
+/**
+ * Run a function within a new trace context.
+ * All async operations within will have access to this context.
+ *
+ * @example
+ * ```ts
+ * // HTTP request handler
+ * withTraceContext({ endpoint: "GET /api/users", clientIP: req.ip }, async () => {
+ *   const users = await db.query("SELECT * FROM users");
+ *   captureException(new Error("oops")); // Auto-linked to trace
+ *   return users;
+ * });
+ *
+ * // Background task
+ * withTraceContext({ isTask: true, endpoint: "process-emails" }, async () => {
+ *   await processEmails();
+ * });
+ * ```
+ */
+declare function withTraceContext<T>(options: TraceContextOptions, fn: () => T): T;
+/**
+ * Run a function within a trace context, automatically capturing the trace on completion.
+ * This is a convenience wrapper that handles timing and capture automatically.
+ *
+ * @example
+ * ```ts
+ * // In Express middleware
+ * app.use((req, res, next) => {
+ *   runWithTraceContext(
+ *     {
+ *       endpoint: `${req.method} ${req.path}`,
+ *       clientIP: req.ip,
+ *       attributes: { userId: req.user?.id },
+ *     },
+ *     async () => {
+ *       await next();
+ *       // Status code and body size set via setTraceResponseInfo()
+ *     },
+ *     { captureOnEnd: true }
+ *   );
+ * });
+ * ```
+ */
+declare function runWithTraceContext<T>(options: TraceContextOptions, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Add a completed span to the current trace context.
+ * No-op if not within a trace context.
+ */
+declare function addSpanToContext(span: Span): void;
+/**
+ * Set an attribute on the current trace context.
+ * No-op if not within a trace context.
+ */
+declare function setTraceAttribute(key: string, value: string): void;
+/**
+ * Set multiple attributes on the current trace context.
+ * No-op if not within a trace context.
+ */
+declare function setTraceAttributes(attributes: Record<string, string>): void;
+/**
+ * Set HTTP response info on the current trace context.
+ * Used by framework adapters after the response is sent.
+ */
+declare function setTraceResponseInfo(statusCode: number, bodySize?: number): void;
+/**
+ * Get all spans from the current trace context.
+ * Returns empty array if not within a trace context.
+ */
+declare function getTraceSpans(): Span[];
+/**
+ * Get the duration in milliseconds since the trace started.
+ * Returns 0 if not within a trace context.
+ */
+declare function getTraceDuration(): number;
+/**
+ * Fork the current trace context for a sub-operation.
+ * Useful for parallel operations that should have isolated spans.
+ * Returns undefined if not within a trace context.
+ */
+declare function forkTraceContext<T>(fn: () => T): T | undefined;
+
+declare function formatErrorStackTrace(error: Error): string;
+
+declare function collectMetrics(): MetricRecord[];
+declare function resetCpuTracking(): void;
+
+interface CollectionFrameStoreOptions {
+    apiUrl: string;
+    token: string;
+    debug: boolean;
+    maxCollectionFrames: number;
+    collectionInterval: number;
+    uploadThrottle: number;
+    metricsInterval: number;
+    version: string;
+    serverName: string;
+    sampleRate: number;
+    errorSampleRate: number;
+}
+declare class CollectionFrameStore {
+    private current;
+    private currentSetAt;
+    private sendQueue;
+    private lastUploadStarted;
+    private collectionTimer;
+    private metricsTimer;
+    private readonly apiUrl;
+    private readonly token;
+    private readonly debug;
+    private readonly collectionInterval;
+    private readonly uploadThrottle;
+    private readonly metricsInterval;
+    private readonly version;
+    private readonly serverName;
+    readonly sampleRate: number;
+    readonly errorSampleRate: number;
+    constructor(options: CollectionFrameStoreOptions);
+    private tick;
+    private ensureCurrent;
+    addException(exception: ExceptionStackTrace): void;
+    addMetric(metric: MetricRecord): void;
+    addTrace(trace: Trace): void;
+    private rotateCurrentCollectionFrame;
+    private processSendQueue;
+    private triggerUpload;
+    private collectSystemMetrics;
+    shutdown(): Promise<void>;
+}
+
+export { CollectionFrameStore, type CollectionFrameStoreOptions, type SpanHandle, type TraceContext, type TraceContextOptions, addSpanToContext, captureCurrentTrace, captureException, captureExceptionWithAttributes, captureMessage, captureMetric, captureTask, captureTrace, collectMetrics, endSpan, forkTraceContext, formatErrorStackTrace, getTraceContext, getTraceDuration, getTraceId, getTraceSpans, hasTraceContext, init, measureTask, resetCpuTracking, runWithTraceContext, setTraceAttribute, setTraceAttributes, setTraceResponseInfo, shouldSample, shutdown, startSpan, asyncLocalStorage as traceContextStorage, withTraceContext };