@tracewayapp/backend 0.2.0

package/dist/index.d.ts

@@ -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 };