@runtime-digital-twin/sdk 1.0.2 → 1.0.3

package/README.md

@@ -91,6 +91,8 @@ await fastify.register(fastifyTracing, {
   headerAllowlist: [],         // Optional: Headers to capture
   maxBodySize: 10 * 1024 * 1024, // Optional: Max body size to capture (default: 10MB)
   enabled: true,              // Optional: Enable/disable tracing (default: true)
+  traceSampleRate: 1,         // Optional: 0–1; 1 = always, 0.1 = 10% of requests (default: 1)
+  alwaysTraceErrors: true,     // Optional: always capture trace for requests that error (default: true)
   // Upload options (optional)
   uploadUrl: process.env.WRAITH_API_URL + '/api/traces/ingest',
   apiKey: process.env.WRAITH_API_KEY,
@@ -136,6 +138,15 @@ WRAITH_API_KEY=your-api-key-here
 
 Traces are uploaded asynchronously after each request completes, so they don't slow down your application.
 
+### Sampling and errors
+
+- **traceSampleRate** (0–1): When set below 1, only that fraction of requests are traced (e.g. 0.1 = 10%). Reduces volume and cost while keeping a representative sample.
+- **alwaysTraceErrors**: When true (default), any request that ends in an error (Fastify `onError`) is traced and uploaded even if it was not sampled. Ensures failures are never missed.
+
+### Rate limits and 429
+
+If the ingest endpoint returns **429 Too Many Requests**, the uploader retries with exponential backoff (same as for 5xx). Use the **Retry-After** response header when present; the SDK respects backoff between attempts. To avoid hitting limits, reduce volume with **traceSampleRate** or increase **TRACE_INGEST_RATE_LIMIT_REQUESTS_PER_MIN** on the server.
+
 ## Modes
 
 ### Record Mode

package/dist/fastify-plugin.d.ts

@@ -8,6 +8,10 @@ export interface FastifyTracingOptions {
     headerAllowlist?: string[];
     maxBodySize?: number;
     enabled?: boolean;
+    /** Sample rate 0–1. 1 = always trace, 0 = never, 0.1 = 10% of requests. Default 1. */
+    traceSampleRate?: number;
+    /** When true, always capture a trace for requests that end in error (onError), even if not sampled. Default true. */
+    alwaysTraceErrors?: boolean;
     uploadUrl?: string;
     apiKey?: string;
     uploadOnComplete?: boolean;

package/dist/fastify-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fastify-plugin.d.ts","sourceRoot":"","sources":["../src/fastify-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAC;AAE3E,OAAO,EAKL,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAY/B,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACtC;CACF;AAID;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,kBAAkB,CAAC,qBAAqB,CAsRpE,CAAC;;AAGF,wBAGG"}
+{"version":3,"file":"fastify-plugin.d.ts","sourceRoot":"","sources":["../src/fastify-plugin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAC;AAE3E,OAAO,EAKL,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAY/B,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qHAAqH;IACrH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACtC;CACF;AAID;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,kBAAkB,CAAC,qBAAqB,CAyVpE,CAAC;;AAGF,wBAGG"}

package/dist/fastify-plugin.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fastifyTracing = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
 const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
 const trace_bundle_writer_1 = require("./trace-bundle-writer");
 const http_wrapper_1 = require("./http-wrapper");
@@ -15,7 +17,7 @@ const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
  * Fastify plugin for capturing HTTP request/response traces
  */
 const fastifyTracing = async (fastify, options) => {
-    const { serviceName, serviceVersion, environment, traceDir, headerAllowlist, maxBodySize = DEFAULT_MAX_BODY_SIZE, enabled = true, uploadUrl, apiKey, uploadOnComplete = true, } = options;
+    const { serviceName, serviceVersion, environment, traceDir, headerAllowlist, maxBodySize = DEFAULT_MAX_BODY_SIZE, enabled = true, traceSampleRate = 1, alwaysTraceErrors = true, uploadUrl, apiKey, uploadOnComplete = true, } = options;
     if (!enabled) {
         fastify.log.info("[SDK] Tracing is disabled");
         return;
@@ -27,30 +29,36 @@ const fastifyTracing = async (fastify, options) => {
     // Hook: onRequest - initialize trace but don't write request event yet (body not available)
     fastify.addHook("onRequest", async (request, reply) => {
         try {
+            const sampledIn = traceSampleRate >= 1 || (traceSampleRate > 0 && Math.random() < traceSampleRate);
+            request.traceSampledIn = sampledIn;
+            if (!sampledIn) {
+                request.traceBundle = null;
+                request.traceSpanId = null;
+                request.traceStartTime = null;
+                request.traceRequestBodyHash = null;
+                request.traceIncomingParentSpanId = null;
+                return;
+            }
             // Check for trace context propagation headers
             const incomingTraceId = request.headers['x-wraith-trace-id'];
             const incomingParentSpanId = request.headers['x-wraith-parent-span-id'];
             // Create trace bundle for this request
-            // Use incoming traceId if present (cross-service propagation), otherwise generate new one
             const traceBundle = await (0, trace_bundle_writer_1.createTrace)({
                 serviceName,
                 serviceVersion,
                 environment,
                 traceDir,
-                traceId: incomingTraceId, // Will be undefined if header not present, triggering new traceId generation
+                traceId: incomingTraceId,
             });
             const spanId = (0, trace_bundle_writer_1.generateSpanId)();
             const startTime = Date.now();
-            // Store on request for later use
             request.traceBundle = traceBundle;
             request.traceSpanId = spanId;
             request.traceStartTime = startTime;
-            request.traceRequestBodyHash = null; // Will be set in preHandler
-            // Store incoming parent span ID for use in preHandler
+            request.traceRequestBodyHash = null;
             request.traceIncomingParentSpanId = incomingParentSpanId || null;
         }
         catch (error) {
-            // Fail-open: log error but don't crash
             fastify.log.error(`[SDK] Failed to initialize trace: ${error}`);
         }
     });
@@ -179,8 +187,8 @@ const fastifyTracing = async (fastify, options) => {
             });
             // Auto-upload trace if configured
             if (uploadUrl && apiKey && uploadOnComplete !== false) {
-                // Upload asynchronously (don't block response)
                 const actualTraceDir = traceDir || './traces';
+                const tracePath = (0, path_1.join)(actualTraceDir, traceBundle.traceId);
                 (0, trace_uploader_1.uploadTrace)({
                     uploadUrl,
                     apiKey,
@@ -189,15 +197,22 @@ const fastifyTracing = async (fastify, options) => {
                     serviceName,
                     serviceVersion,
                     environment,
-                }).then(result => {
+                }).then(async (result) => {
                     if (result.success) {
-                        fastify.log.info(`[SDK] Trace uploaded: ${result.traceId}`);
+                        fastify.log.info({ traceId: result.traceId }, '[SDK] Trace uploaded');
+                        // Delete local trace dir after successful upload to avoid re-upload and unbounded disk growth
+                        try {
+                            await (0, promises_1.rm)(tracePath, { recursive: true, force: true });
+                        }
+                        catch (err) {
+                            fastify.log.debug({ traceId: traceBundle.traceId, err: err?.message }, '[SDK] Could not delete trace dir after upload');
+                        }
                     }
                     else {
-                        fastify.log.warn(`[SDK] Trace upload failed: ${result.error}`);
+                        fastify.log.warn({ traceId: traceBundle.traceId, error: result.error }, '[SDK] Trace upload failed');
                     }
                 }).catch(error => {
-                    fastify.log.error(`[SDK] Trace upload error: ${error}`);
+                    fastify.log.error({ traceId: traceBundle.traceId, error: error?.message }, '[SDK] Trace upload error');
                 });
             }
             // Clear trace context
@@ -210,13 +225,67 @@ const fastifyTracing = async (fastify, options) => {
             (0, http_wrapper_1.setTraceContext)(null, null);
         }
     });
-    // Hook: onError - capture errors
+    // Hook: onError - capture errors (always capture if alwaysTraceErrors and no bundle yet)
     fastify.addHook("onError", async (request, reply, error) => {
-        const traceBundle = request.traceBundle;
-        const spanId = request.traceSpanId;
-        if (!traceBundle || !spanId) {
+        let traceBundle = request.traceBundle;
+        let spanId = request.traceSpanId;
+        const wasSampledOut = !request.traceSampledIn;
+        if (wasSampledOut && alwaysTraceErrors) {
+            try {
+                const bundle = await (0, trace_bundle_writer_1.createTrace)({
+                    serviceName,
+                    serviceVersion,
+                    environment,
+                    traceDir,
+                });
+                const sid = (0, trace_bundle_writer_1.generateSpanId)();
+                traceBundle = bundle;
+                spanId = sid;
+                await bundle.writeEvent({
+                    type: "error",
+                    timestamp: Date.now(),
+                    spanId: sid,
+                    parentSpanId: null,
+                    error: {
+                        name: error.name || "Error",
+                        message: error.message || String(error),
+                        stack: error.stack || undefined,
+                    },
+                });
+                await bundle.complete({
+                    method: 'ERROR',
+                    path: '/error',
+                    headers: {},
+                });
+                if (uploadUrl && apiKey) {
+                    const actualTraceDir = traceDir || './traces';
+                    const tracePath = (0, path_1.join)(actualTraceDir, bundle.traceId);
+                    (0, trace_uploader_1.uploadTrace)({
+                        uploadUrl,
+                        apiKey,
+                        traceDir: actualTraceDir,
+                        traceId: bundle.traceId,
+                        serviceName,
+                        serviceVersion,
+                        environment,
+                    }).then(async (result) => {
+                        if (result.success) {
+                            try {
+                                // Delete local trace dir after successful upload to prevent re-upload and unbounded disk growth
+                                await (0, promises_1.rm)(tracePath, { recursive: true, force: true });
+                            }
+                            catch (_) { }
+                        }
+                    }).catch(() => { });
+                }
+            }
+            catch (err) {
+                fastify.log.error(`[SDK] Failed to capture error trace: ${err}`);
+            }
             return;
         }
+        if (!traceBundle || !spanId)
+            return;
         try {
             await traceBundle.writeEvent({
                 type: "error",

package/dist/trace-uploader.d.ts

@@ -19,7 +19,8 @@ export interface TraceUploadResult {
     error?: string;
 }
 /**
- * Upload trace to ingestion endpoint
+ * Upload trace to ingestion endpoint with retries (5xx, 429, network errors).
+ * Exponential backoff: 1s, 2s, 4s (capped at 8s).
  */
 export declare function uploadTrace(options: TraceUploadOptions): Promise<TraceUploadResult>;
 //# sourceMappingURL=trace-uploader.d.ts.map

package/dist/trace-uploader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-uploader.d.ts","sourceRoot":"","sources":["../src/trace-uploader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+CD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAiF5B"}
+{"version":3,"file":"trace-uploader.d.ts","sourceRoot":"","sources":["../src/trace-uploader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAmED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAwI5B"}

package/dist/trace-uploader.js

@@ -53,8 +53,26 @@ async function readTraceMeta(metaPath) {
         throw new Error(`Failed to read meta.json: ${error.message}`);
     }
 }
+const MAX_UPLOAD_ATTEMPTS = 3;
+const INITIAL_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 8000;
+function isRetryableStatus(status) {
+    return status >= 500 || status === 429;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function logUpload(event) {
+    try {
+        console.warn('[SDK]', JSON.stringify({ event: 'trace_upload', ...event }));
+    }
+    catch {
+        console.warn('[SDK] trace_upload', event);
+    }
+}
 /**
- * Upload trace to ingestion endpoint
+ * Upload trace to ingestion endpoint with retries (5xx, 429, network errors).
+ * Exponential backoff: 1s, 2s, 4s (capped at 8s).
  */
 async function uploadTrace(options) {
     const { uploadUrl, apiKey, traceDir, traceId, serviceName, serviceVersion, environment } = options;
@@ -89,7 +107,6 @@ async function uploadTrace(options) {
                 correlationIds: meta.correlationIds || [],
             },
             events: events.map(event => {
-                // Ensure all events have required base envelope fields
                 return {
                     ...event,
                     traceId: event.traceId || traceId,
@@ -98,31 +115,77 @@ async function uploadTrace(options) {
                 };
             }),
         };
-        // Upload to ingestion endpoint
-        const response = await fetch(uploadUrl, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${apiKey}`,
-            },
-            body: JSON.stringify(batch),
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            return {
-                success: false,
-                traceId,
-                error: `Upload failed: ${response.status} ${response.statusText} - ${errorText}`,
-            };
+        let lastError;
+        let lastStatus;
+        for (let attempt = 1; attempt <= MAX_UPLOAD_ATTEMPTS; attempt++) {
+            logUpload({ traceId, attempt });
+            try {
+                const response = await fetch(uploadUrl, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${apiKey}`,
+                    },
+                    body: JSON.stringify(batch),
+                });
+                lastStatus = response.status;
+                logUpload({ traceId, attempt, statusCode: response.status });
+                if (response.ok) {
+                    const result = await response.json();
+                    logUpload({ traceId, attempt, statusCode: response.status, success: true });
+                    return {
+                        success: true,
+                        traceId: result.traceId || traceId,
+                        blobRoot: result.blobRoot,
+                    };
+                }
+                const errorText = await response.text();
+                lastError = `${response.status} ${response.statusText} - ${errorText.substring(0, 200)}`;
+                if (!isRetryableStatus(response.status) || attempt === MAX_UPLOAD_ATTEMPTS) {
+                    logUpload({ traceId, attempt, statusCode: response.status, success: false, error: lastError?.substring(0, 200) });
+                    return {
+                        success: false,
+                        traceId,
+                        error: lastError,
+                    };
+                }
+                let backoffMs = Math.min(INITIAL_BACKOFF_MS * Math.pow(2, attempt - 1), MAX_BACKOFF_MS);
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    if (retryAfter != null) {
+                        const retryAfterMs = /^\d+$/.test(retryAfter.trim())
+                            ? parseInt(retryAfter.trim(), 10) * 1000
+                            : 0;
+                        if (retryAfterMs > 0) {
+                            backoffMs = Math.min(backoffMs, retryAfterMs);
+                        }
+                    }
+                }
+                await sleep(backoffMs);
+            }
+            catch (networkError) {
+                lastError = networkError.message || String(networkError);
+                logUpload({ traceId, attempt, success: false, error: lastError?.substring(0, 200) });
+                if (attempt === MAX_UPLOAD_ATTEMPTS) {
+                    return {
+                        success: false,
+                        traceId,
+                        error: lastError,
+                    };
+                }
+                const backoffMs = Math.min(INITIAL_BACKOFF_MS * Math.pow(2, attempt - 1), MAX_BACKOFF_MS);
+                await sleep(backoffMs);
+            }
         }
-        const result = await response.json();
+        logUpload({ traceId, attempt: MAX_UPLOAD_ATTEMPTS, statusCode: lastStatus, success: false, error: lastError?.substring(0, 200) });
         return {
-            success: true,
-            traceId: result.traceId || traceId,
-            blobRoot: result.blobRoot,
+            success: false,
+            traceId,
+            error: lastError || 'Upload failed after retries',
         };
     }
     catch (error) {
+        logUpload({ traceId, success: false, error: error.message?.substring(0, 200) });
         return {
             success: false,
             traceId,

package/package.json

@@ -1,35 +1,28 @@
 {
   "name": "@runtime-digital-twin/sdk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "SDK for capturing runtime behavior - automatic incident response and debugging with enhanced autofix support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "default": "./src/index.ts"
     },
     "./src/*": "./src/*",
     "./dist/*": "./dist/*"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
-    "@runtime-digital-twin/core": "^1.0.0",
     "fastify": "^4.24.0",
-    "fastify-plugin": "^4.5.0"
+    "fastify-plugin": "^4.5.0",
+    "@runtime-digital-twin/core": "1.0.1"
   },
   "devDependencies": {
-    "@jest/globals": "^29.7.0",
-    "@types/jest": "^29.5.0",
+    "@jest/globals": "^30.2.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.1.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
     "typescript": "^5.0.0"
   },
   "license": "MIT",
@@ -38,7 +31,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/alakhanpal23/Wraith-2.git",
+    "url": "git+https://github.com/usewraith/wraith.git",
     "directory": "packages/sdk"
   },
   "keywords": [
@@ -58,6 +51,11 @@
     "dist",
     "README.md",
     "LICENSE"
-  ]
-}
-
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  }
+}