unnbound-logger-sdk 3.0.2 → 3.0.4

package/README.md

@@ -240,6 +240,22 @@ The Axios middleware:
 - Creates spans for each HTTP request
 - Supports request/response filtering through configuration
 
+## Manual tracing
+
+In case the function doesn't run inside an HTTP handler (for example a cron job), you can assign a trace id manually by using the `withTrace` function:
+
+```typescript
+import { withTrace } from 'unnbound-logger';
+
+const operation = async (value: number) => {
+  // This will log a { traceId, value }
+  logger.info('Processing value', { value });
+  return value * 2;
+};
+
+setInterval(() => withTrace(() => operation(13)), 1000);
+```
+
 ## Function Tracing with startSpan
 
 The `startSpan` function allows you to wrap any async operation with automatic span tracking and logging. This is particularly useful for maintaining consistent trace IDs across async operations and distributed systems:
@@ -262,6 +278,8 @@ const result = await startSpan('Processing operation', operation, () => ({
 const result = await startSpan('Processing operation', () => operation(21)); // Returns 42
 ```
 
+_Note: In case the `traceId` is missing from the context, `startSpan` will generate one. It is recommended to use a single `traceId` across your handler though, so always consider using `traceMiddleware` and `withTrace` to inject the `traceId` instead of relying on `startSpan` to create one._
+
 ### Async Operations
 
 The span context is maintained across async operations:

package/dist/axios.js

@@ -46,7 +46,7 @@ const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRout
             // Check if this request should be ignored
             if ((0, utils_1.shouldIgnorePath)(url, ignoreTraceRoutes))
                 return originalMethod(config);
-            const traceId = storage_1.storage.getStore()?.[storage_1.ContextAttribute.TraceId];
+            const traceId = storage_1.storage.getStore()?.traceId;
             config = { ...config, headers: { ...config.headers, [traceHeaderKey]: traceId } };
             // Execute the request within a span
             return (0, span_1.startSpan)(`Outgoing HTTP request`, () => originalMethod(config), (options) => {

package/dist/index.d.ts

@@ -7,6 +7,7 @@
 export type { LogLevel, LogType, HttpMethod, Log, LogTransaction, SftpLog, HttpLog, SftpPayload, } from './types';
 export type { UnnboundLogger } from './logger';
 export { logger } from './logger';
+export { withTrace, getTraceId } from './trace';
 export { startSpan } from './span';
 export { traceAxios } from './axios';
 export { traceMiddleware } from './middleware';

package/dist/index.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.traceMiddleware = exports.traceAxios = exports.startSpan = exports.logger = void 0;
+exports.traceMiddleware = exports.traceAxios = exports.startSpan = exports.getTraceId = exports.withTrace = exports.logger = void 0;
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
+var trace_1 = require("./trace");
+Object.defineProperty(exports, "withTrace", { enumerable: true, get: function () { return trace_1.withTrace; } });
+Object.defineProperty(exports, "getTraceId", { enumerable: true, get: function () { return trace_1.getTraceId; } });
 var span_1 = require("./span");
 Object.defineProperty(exports, "startSpan", { enumerable: true, get: function () { return span_1.startSpan; } });
 var axios_1 = require("./axios");

package/dist/middleware.js

@@ -1,11 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.traceMiddleware = void 0;
-const uuid_1 = require("uuid");
-const storage_1 = require("./storage");
 const span_1 = require("./span");
 const types_1 = require("./types");
 const utils_1 = require("./utils");
+const trace_1 = require("./trace");
 const getFullUrl = (req) => {
     const url = req.originalUrl || req.url;
     if (url?.startsWith('http://') || url?.startsWith('https://'))
@@ -46,9 +45,9 @@ const traceMiddleware = ({ ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes,
 }) => async (req, res, next) => {
     if ((0, utils_1.shouldIgnorePath)(req.path, ignoreTraceRoutes))
         return next();
-    const traceId = req.header(traceHeaderKey) || (0, uuid_1.v4)();
+    const traceId = req.header(traceHeaderKey) || (0, trace_1.getTraceId)();
     res.setHeader(traceHeaderKey, traceId);
-    return await storage_1.storage.run({ [storage_1.ContextAttribute.TraceId]: traceId }, async () => {
+    return await (0, trace_1.withTrace)(async () => {
         return await (0, span_1.startSpan)('Incoming HTTP request', async () => {
             return new Promise((resolve) => {
                 // Capture response body for logging
@@ -62,9 +61,12 @@ const traceMiddleware = ({ ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes,
             });
         }, (o) => {
             return buildIncomingHttpPayload(req, o
-                ? { statusCode: res.statusCode, headers: res.getHeaders() }
+                ? {
+                    statusCode: res.statusCode,
+                    headers: res.getHeaders(),
+                }
                 : undefined, res.locals.body);
         });
-    });
+    }, { traceId });
 };
 exports.traceMiddleware = traceMiddleware;

package/dist/span.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.startSpan = void 0;
 const uuid_1 = require("uuid");
 const storage_1 = require("./storage");
+const trace_1 = require("./trace");
 const logger_1 = require("./logger");
 /**
  * Starts a span that tracks the duration of a callback
@@ -16,9 +17,8 @@ const startSpan = async (spanName, callback, getter) => {
     const previous = storage_1.storage.getStore();
     return storage_1.storage.run({
         ...previous,
-        [storage_1.ContextAttribute.SpanId]: previous?.[storage_1.ContextAttribute.SpanId]
-            ? `${spanId} ${previous?.[storage_1.ContextAttribute.SpanId]}`
-            : spanId,
+        traceId: previous?.traceId ?? (0, trace_1.getTraceId)(),
+        spanId: previous?.spanId ? `${spanId} ${previous?.spanId}` : spanId,
     }, async () => {
         logger_1.logger.info({ ...getLogPayload(getter) }, `${spanName} started.`);
         try {

package/dist/storage.d.ts

@@ -1,10 +1,6 @@
 import { AsyncLocalStorage } from 'async_hooks';
-export declare enum ContextAttribute {
-    TraceId = "traceId",
-    SpanId = "spanId"
-}
 export interface Context {
-    [ContextAttribute.TraceId]?: string;
-    [ContextAttribute.SpanId]?: string;
+    traceId?: string;
+    spanId?: string;
 }
 export declare const storage: AsyncLocalStorage<Context>;

package/dist/storage.js

@@ -1,10 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.storage = exports.ContextAttribute = void 0;
+exports.storage = void 0;
 const async_hooks_1 = require("async_hooks");
-var ContextAttribute;
-(function (ContextAttribute) {
-    ContextAttribute["TraceId"] = "traceId";
-    ContextAttribute["SpanId"] = "spanId";
-})(ContextAttribute || (exports.ContextAttribute = ContextAttribute = {}));
 exports.storage = new async_hooks_1.AsyncLocalStorage();

package/dist/trace.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generates a trace ID
+ * @returns A trace ID
+ */
+export declare const getTraceId: () => string;
+/**
+ * Runs a callback with a trace ID
+ * @param callback - The callback to run
+ * @param extra - Extra context to add to the trace
+ * @returns The result of the callback
+ */
+export declare const withTrace: <T, E extends {
+    traceId?: string;
+}>(callback: () => T, extra?: E) => T;

package/dist/trace.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTrace = exports.getTraceId = void 0;
+const uuid_1 = require("uuid");
+const storage_1 = require("./storage");
+/**
+ * Generates a trace ID
+ * @returns A trace ID
+ */
+const getTraceId = () => (0, uuid_1.v4)();
+exports.getTraceId = getTraceId;
+/**
+ * Runs a callback with a trace ID
+ * @param callback - The callback to run
+ * @param extra - Extra context to add to the trace
+ * @returns The result of the callback
+ */
+const withTrace = (callback, extra) => {
+    return storage_1.storage.run({ ...storage_1.storage.getStore(), ...extra, traceId: extra?.traceId ?? (0, exports.getTraceId)() }, callback);
+};
+exports.withTrace = withTrace;

package/dist/types.d.ts

@@ -43,7 +43,7 @@ export interface HttpLog extends LogTransaction<'http'> {
         };
     };
 }
-export type SftpOperation = 'connect' | 'upload' | 'download' | 'list' | 'delete' | 'rename' | 'stat' | 'exists' | 'realPath' | 'get' | 'put' | 'cwd' | 'mkdir' | 'rmdir' | 'chmod' | 'append' | 'uploadDir' | 'downloadDir' | 'end';
+export type SftpOperation = 'connect' | 'upload' | 'download' | 'list' | 'delete' | 'rename' | 'stat' | 'exists' | 'realPath' | 'get' | 'put' | 'cwd' | 'mkdir' | 'rmdir' | 'chmod' | 'append' | 'uploadDir' | 'downloadDir' | 'close';
 export interface SftpPayload {
     host: string;
     operation: SftpOperation;
@@ -51,6 +51,8 @@ export interface SftpPayload {
     bytes?: number;
     destinationPath?: string;
     files?: number;
+    content?: string;
+    exists?: string | false;
 }
 export interface SftpLog extends LogTransaction<'sftp'> {
     sftp: SftpPayload;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unnbound-logger-sdk",
   "description": "A structured logging library with TypeScript support using Pino. Provides consistent, well-typed logging with automatic logId, workflowId, traceId, and deploymentId tracking across operational contexts.",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "keywords": [
@@ -19,7 +19,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/unnbounddev/unnbound-sdks.git"
+    "url": "git+https://github.com/unnbounddev/unnbound-sdks.git"
   },
   "homepage": "https://github.com/unnbounddev/unnbound-sdks#readme",
   "bugs": {