@justanalyticsapp/node 0.1.0

package/dist/span.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/span.ts
+ * @description Span class for distributed tracing with high-resolution timing.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ *
+ * Each Span records a timed operation within a trace. Spans are created by
+ * `JA.startSpan()` and automatically ended when the callback completes.
+ * The `toJSON()` method serializes the span to the exact format expected by
+ * `POST /api/ingest/spans` (see the Zod schema in route.ts).
+ *
+ * Timing uses `process.hrtime.bigint()` for nanosecond-resolution monotonic
+ * measurement, then converts to integer milliseconds via Math.round.
+ *
+ * References:
+ * - src/app/api/ingest/spans/route.ts (Zod schema the payload must match)
+ * - W3C Trace Context (traceId/spanId format)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Span = void 0;
+const id_1 = require("./utils/id");
+/**
+ * Span represents a single timed operation within a distributed trace.
+ *
+ * Spans are created by `JA.startSpan()` and ended either automatically
+ * when the callback completes, or manually via `span.end()`.
+ *
+ * @example
+ * ```typescript
+ * JA.startSpan('process-order', (span) => {
+ *   span.setAttribute('order.id', '12345');
+ *   span.addEvent('payment.processed');
+ *   // span.end() is called automatically
+ * });
+ * ```
+ */
+class Span {
+    constructor(params) {
+        this._endTime = null;
+        this._duration = null;
+        this._status = 'unset';
+        this._statusMessage = null;
+        this._events = [];
+        this._ended = false;
+        this.id = (0, id_1.generateSpanId)();
+        this.traceId = params.traceId;
+        this.parentSpanId = params.parentSpanId;
+        this.operationName = params.operationName;
+        this.serviceName = params.serviceName;
+        this.kind = params.kind;
+        this.startTime = new Date();
+        this.startHrTime = process.hrtime.bigint();
+        this._attributes = { ...(params.attributes || {}) };
+    }
+    /**
+     * Set a single attribute on the span.
+     *
+     * @param key - Attribute key (e.g. "http.method", "db.statement")
+     * @param value - Attribute value
+     * @returns this (for chaining)
+     */
+    setAttribute(key, value) {
+        if (this._ended)
+            return this;
+        this._attributes[key] = value;
+        return this;
+    }
+    /**
+     * Set multiple attributes on the span.
+     *
+     * @param attrs - Key-value pairs to merge into attributes
+     * @returns this (for chaining)
+     */
+    setAttributes(attrs) {
+        if (this._ended)
+            return this;
+        Object.assign(this._attributes, attrs);
+        return this;
+    }
+    /**
+     * Set the span's status.
+     *
+     * @param status - One of 'ok', 'error', 'unset'
+     * @param message - Optional status message (typically for errors)
+     * @returns this (for chaining)
+     */
+    setStatus(status, message) {
+        if (this._ended)
+            return this;
+        this._status = status;
+        this._statusMessage = message ?? null;
+        return this;
+    }
+    /**
+     * Add a timestamped event to the span.
+     *
+     * Events represent notable moments during the span's lifetime
+     * (e.g. "cache.miss", "retry.attempt", "payment.processed").
+     *
+     * @param name - Event name
+     * @param attributes - Optional event attributes
+     * @returns this (for chaining)
+     */
+    addEvent(name, attributes) {
+        if (this._ended)
+            return this;
+        const event = {
+            name,
+            timestamp: new Date().toISOString(),
+        };
+        if (attributes) {
+            event.attributes = attributes;
+        }
+        this._events.push(event);
+        return this;
+    }
+    /**
+     * Update the operation name after span creation.
+     *
+     * Used by auto-instrumentation integrations to refine the operation name
+     * after additional context is available (e.g., Express route matching
+     * provides `/api/users/:id` instead of the raw URL `/api/users/42`).
+     *
+     * No-op if the span has already ended.
+     *
+     * @param name - The new operation name
+     * @returns this (for chaining)
+     */
+    updateOperationName(name) {
+        if (this._ended)
+            return this;
+        this.operationName = name;
+        return this;
+    }
+    /**
+     * Mark the span as ended.
+     *
+     * Calculates duration using `process.hrtime.bigint()` for sub-millisecond
+     * precision, then rounds to an integer millisecond value to match the
+     * server's `z.number().int()` Zod validation.
+     *
+     * Calling `end()` multiple times is a no-op (idempotent).
+     */
+    end() {
+        if (this._ended)
+            return;
+        this._ended = true;
+        this._endTime = new Date();
+        const endHrTime = process.hrtime.bigint();
+        // Convert nanoseconds to integer milliseconds
+        this._duration = Math.round(Number(endHrTime - this.startHrTime) / 1000000);
+    }
+    /** Whether this span has been ended */
+    get isEnded() {
+        return this._ended;
+    }
+    /**
+     * Serialize the span to the JSON payload format expected by
+     * `POST /api/ingest/spans`.
+     *
+     * The output matches the Zod schema defined in
+     * `src/app/api/ingest/spans/route.ts` exactly:
+     * - `id`: 16-char hex
+     * - `traceId`: 32-char hex
+     * - `parentSpanId`: 16-char hex or null
+     * - `operationName`: string (1-256 chars)
+     * - `serviceName`: string (1-128 chars)
+     * - `kind`: one of the SpanKind values
+     * - `startTime`: ISO 8601 string
+     * - `endTime`: ISO 8601 string or null
+     * - `duration`: integer milliseconds or null
+     * - `status`: one of the SpanStatus values
+     * - `statusMessage`: string or null
+     * - `attributes`: object
+     * - `events`: array of event objects
+     */
+    toJSON() {
+        return {
+            id: this.id,
+            traceId: this.traceId,
+            parentSpanId: this.parentSpanId,
+            operationName: this.operationName,
+            serviceName: this.serviceName,
+            kind: this.kind,
+            startTime: this.startTime.toISOString(),
+            endTime: this._endTime ? this._endTime.toISOString() : null,
+            duration: this._duration,
+            status: this._status,
+            statusMessage: this._statusMessage,
+            attributes: { ...this._attributes },
+            events: [...this._events],
+        };
+    }
+}
+exports.Span = Span;
+//# sourceMappingURL=span.js.map

package/dist/span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.js","sourceRoot":"","sources":["../src/span.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @file packages/node-sdk/src/transport.ts
+ * @description Batched HTTP transport for sending span and error data to the JustAnalytics server.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ * Updated for Story 041 - Server-Side Error Tracking via SDK
+ * Updated for Story 046 - SDK Log Integration
+ * Updated for Story 048 - Infrastructure Metrics Collection
+ *
+ * The BatchTransport collects ended spans, error events, log entries, and
+ * infrastructure metrics in separate in-memory buffers and periodically
+ * flushes them to their respective endpoints:
+ * - Spans: `POST /api/ingest/spans` (batched, 1-100 per request)
+ * - Errors: `POST /api/ingest/errors` (individual, one per request)
+ * - Logs: `POST /api/ingest/logs` (batched, 1-100 per request)
+ * - Metrics: `POST /api/ingest/metrics` (batched, 1-500 per request)
+ *
+ * It uses Node.js built-in `http`/`https` modules (not fetch, not axios)
+ * for maximum compatibility with Node.js 18+.
+ *
+ * Flush behavior:
+ * - Timer-based: flushes every `flushIntervalMs` milliseconds (default: 2000)
+ * - Size-based: flushes immediately when buffer reaches `maxBatchSize` (default: 100)
+ * - Manual: `flush()` can be called explicitly
+ *
+ * Error handling:
+ * - HTTP 429 (rate limited): doubles flush interval for 60 seconds, then resets
+ * - Network errors / non-2xx: logs warning (in debug mode), drops the batch
+ * - Never throws unhandled exceptions that could crash the host process
+ *
+ * References:
+ * - src/app/api/ingest/spans/route.ts (target endpoint and expected payload format)
+ * - src/app/api/ingest/errors/route.ts (error ingestion endpoint)
+ */
+import { SpanPayload } from './span';
+import { ServerErrorPayload } from './errors';
+import { LogPayload } from './logger';
+import { MetricPayload } from './integrations/metrics';
+/** Configuration options for BatchTransport */
+export interface TransportOptions {
+    /** Base URL of the JustAnalytics server */
+    serverUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Flush interval in milliseconds */
+    flushIntervalMs: number;
+    /** Maximum spans per batch before immediate flush */
+    maxBatchSize: number;
+    /** Enable debug logging */
+    debug: boolean;
+}
+/**
+ * BatchTransport collects spans and errors in memory and sends them
+ * in batches to the JustAnalytics ingestion endpoints.
+ *
+ * Uses Node.js built-in `http`/`https` modules for HTTP communication.
+ * Implements timer-based and size-based flushing with 429 backoff.
+ */
+export declare class BatchTransport {
+    private buffer;
+    private errorBuffer;
+    private logBuffer;
+    private metricBuffer;
+    private readonly flushIntervalMs;
+    private readonly maxBatchSize;
+    private readonly serverUrl;
+    private readonly apiKey;
+    private readonly debug;
+    private timer;
+    /** Independent flushing guards for spans, errors, logs, and metrics */
+    private isFlushingSpans;
+    private isFlushingErrors;
+    private isFlushingLogs;
+    private isFlushingMetrics;
+    /** Original flush interval for resetting after 429 backoff */
+    private readonly originalFlushIntervalMs;
+    /** Current effective flush interval (may be doubled during backoff) */
+    private currentFlushIntervalMs;
+    /** Timer for resetting flush interval after 429 backoff */
+    private backoffResetTimer;
+    constructor(options: TransportOptions);
+    /**
+     * Enqueue a span payload for batched sending.
+     *
+     * If the buffer reaches `maxBatchSize`, triggers an immediate flush.
+     *
+     * @param span - Serialized span payload to enqueue
+     */
+    enqueue(span: SpanPayload): void;
+    /**
+     * Enqueue an error event payload for batched sending.
+     * Errors are flushed alongside spans on the periodic timer.
+     *
+     * @param payload - Error event payload to enqueue
+     */
+    enqueueError(payload: ServerErrorPayload): void;
+    /**
+     * Enqueue a log entry payload for batched sending.
+     * Logs are flushed alongside spans and errors on the periodic timer.
+     *
+     * If the buffer reaches `maxBatchSize`, triggers an immediate flush.
+     *
+     * @param entry - Log entry payload to enqueue
+     */
+    enqueueLog(entry: LogPayload): void;
+    /**
+     * Enqueue an infrastructure metric payload for batched sending.
+     * Metrics are flushed alongside spans, errors, and logs on the periodic timer.
+     *
+     * If the buffer reaches `maxBatchSize`, triggers an immediate flush.
+     *
+     * @param metric - Metric data point payload to enqueue
+     */
+    enqueueMetric(metric: MetricPayload): void;
+    /**
+     * Send a single error immediately (non-batched).
+     * Used for uncaughtException where the process is about to exit.
+     *
+     * Fire-and-forget: the promise result is intentionally not awaited
+     * by the caller because the process is exiting.
+     *
+     * @param payload - Error event payload to send immediately
+     */
+    sendErrorImmediate(payload: ServerErrorPayload): void;
+    /**
+     * Flush all pending spans and errors to the server.
+     *
+     * Delegates to `flushSpans()` and `flushErrors()` in parallel.
+     * Each sub-method has its own isFlushing guard.
+     *
+     * @returns Promise that resolves when both flushes complete
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush all pending span payloads to `POST /api/ingest/spans`.
+     *
+     * Sends all buffered spans in a single HTTP request.
+     * The buffer is cleared before sending, so new spans that arrive
+     * during the flush are queued for the next flush.
+     *
+     * @returns Promise that resolves when the flush completes (or fails)
+     */
+    private flushSpans;
+    /**
+     * Flush all pending error event payloads to `POST /api/ingest/errors`.
+     *
+     * Each error is sent as an individual POST request because the server-side
+     * fingerprinting and upsert logic operates on individual events.
+     *
+     * @returns Promise that resolves when all errors are sent (or dropped)
+     */
+    flushErrors(): Promise<void>;
+    /**
+     * Start the periodic flush timer.
+     *
+     * Uses `setInterval` with the current effective flush interval.
+     * The timer is `unref()`'d so it does not keep the process alive.
+     */
+    start(): void;
+    /**
+     * Stop the periodic flush timer.
+     */
+    stop(): void;
+    /**
+     * Number of spans currently in the buffer awaiting flush.
+     */
+    get pendingCount(): number;
+    /**
+     * Number of errors currently in the error buffer awaiting flush.
+     */
+    get pendingErrorCount(): number;
+    /**
+     * Number of log entries currently in the buffer awaiting flush.
+     */
+    get pendingLogCount(): number;
+    /**
+     * Number of metrics currently in the buffer awaiting flush.
+     */
+    get pendingMetricCount(): number;
+    /**
+     * Send a batch of spans via HTTP POST to /api/ingest/spans.
+     *
+     * Uses Node.js built-in `http` or `https` module based on the server URL
+     * protocol. Handles HTTP 429 with backoff.
+     *
+     * @param batch - Array of span payloads to send
+     */
+    private sendBatch;
+    /**
+     * Send a batch of error events via HTTP POST.
+     * Each error is sent as an individual POST to /api/ingest/errors
+     * because the server-side fingerprinting and upsert logic operates
+     * on individual events.
+     *
+     * @param batch - Array of error payloads to send
+     */
+    private sendErrorBatch;
+    /**
+     * Send a single error event via HTTP POST to /api/ingest/errors.
+     *
+     * @param payload - Error event payload to send
+     */
+    private sendSingleError;
+    /**
+     * Flush all pending log entry payloads to POST /api/ingest/logs.
+     *
+     * Sends all buffered logs in a single HTTP POST request.
+     * The buffer is cleared before sending, so new logs that arrive
+     * during the flush are queued for the next flush.
+     *
+     * @returns Promise that resolves when the flush completes (or fails)
+     */
+    private flushLogs;
+    /**
+     * Send a batch of log entries via HTTP POST to /api/ingest/logs.
+     *
+     * Uses Node.js built-in `http`/`https` module based on the server URL
+     * protocol. Handles HTTP 429 with backoff.
+     *
+     * @param batch - Array of log entry payloads to send
+     */
+    private sendLogBatch;
+    /**
+     * Flush all pending metric payloads to POST /api/ingest/metrics.
+     *
+     * Sends all buffered metrics in a single HTTP POST request.
+     * The buffer is cleared before sending, so new metrics that arrive
+     * during the flush are queued for the next flush.
+     *
+     * @returns Promise that resolves when the flush completes (or fails)
+     */
+    private flushMetrics;
+    /**
+     * Send a batch of metrics via HTTP POST to /api/ingest/metrics.
+     *
+     * Uses Node.js built-in `http`/`https` module based on the server URL
+     * protocol. Handles HTTP 429 with backoff.
+     *
+     * @param batch - Array of metric payloads to send
+     */
+    private sendMetricBatch;
+    /**
+     * Handle HTTP 429 backoff: double the flush interval for 60 seconds, then reset.
+     */
+    private handleBackoff;
+}