unnbound-logger-sdk 2.0.4 → 2.0.6

package/README.md

@@ -48,12 +48,14 @@ All logs follow a standardized format:
 
 ```typescript
 interface Log<T extends LogType = 'general'> {
+  logId: string; // Unique identifier for each log entry
   level: LogLevel; // "info" | "debug" | "error" | "warn"
   type: T; // "general" | "httpRequest" | "httpResponse" | "sftpTransaction" | "dbQueryTransaction"
   message: string;
+  workflowId: string; // Workflow tracking (empty string if not set)
   traceId: string;
   requestId: string;
-  deploymentId: string; // Automatically populated from DEPLOYMENT_ID environment variable
+  deploymentId: string; // Automatically populated from UNNBOUND_DEPLOYMENT_ID
   error?: SerializableError; // Only present for Error objects
 }
 
@@ -62,24 +64,44 @@ interface LogTransaction<T extends LogType> extends Log<T> {
 }
 ```
 
-## Deployment Tracking
+## Workflow and Deployment Tracking
 
-The logger automatically includes a `deploymentId` field in all log entries. This field is populated from the `DEPLOYMENT_ID` environment variable, allowing you to track logs across different deployments of your application.
+### Workflow Tracking
+
+The logger includes a `workflowId` field in all log entries for tracking operations across services:
+
+```bash
+# Set the workflow ID in your environment
+export UNNBOUND_WORKFLOW_ID="order-processing-12345"
+
+# Or in your deployment configuration  
+UNNBOUND_WORKFLOW_ID=order-processing-12345
+```
+
+```typescript
+// Create a logger - workflowId is automatically set from environment
+const logger = new UnnboundLogger();
+// All logs will include the workflowId from UNNBOUND_WORKFLOW_ID environment variable
+```
+
+### Deployment Tracking
+
+The logger automatically includes a `deploymentId` field in all log entries. This field is populated from the `UNNBOUND_DEPLOYMENT_ID` environment variable, allowing you to track logs per deployment.
 
 ```bash
 # Set the deployment ID in your environment
-export DEPLOYMENT_ID="v1.2.3-prod-20231201"
+export UNNBOUND_DEPLOYMENT_ID="v1.2.3-prod-20231201"
 
 # Or in your deployment configuration
-DEPLOYMENT_ID=v1.2.3-prod-20231201
+UNNBOUND_DEPLOYMENT_ID=v1.2.3-prod-20231201
 ```
 
-If the `DEPLOYMENT_ID` environment variable is not set, the `deploymentId` field will be an empty string. This field helps with:
+If the environment variables are not set, the fields will be empty strings. These fields help with:
 
-- Tracking logs across different application deployments
-- Correlating issues with specific releases
-- Monitoring deployment health and performance
-- Debugging problems in specific deployment versions
+- **Workflow ID**: Unique identifier for the workflow
+- **Deployment ID**: Tracking logs across different application deployments
+- **Correlating issues**: Link problems to specific workflows and releases
+- **Monitoring**: Track health and performance across workflows and deployments
 
 ## HTTP Request/Response Logging
 
@@ -326,14 +348,21 @@ The main logger class that provides all logging functionality using Pino.
 new UnnboundLogger(options?: LoggerOptions)
 ```
 
+**LoggerOptions:**
+- `traceHeaderKey?: string` - Custom trace header name (default: 'unnbound-trace-id')
+- `ignoreTraceRoutes?: string[]` - Routes to ignore in Express middleware
+- `ignoreAxiosTraceRoutes?: string[]` - Routes to ignore in Axios middleware
+
+**Note:** `workflowId` and `deploymentId` are configured via environment variables (`UNNBOUND_WORKFLOW_ID`, `UNNBOUND_DEPLOYMENT_ID`).
+
 #### Methods
 
-- `log(level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
-- `error(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
-- `warn(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
-- `info(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
-- `debug(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
-- `httpRequest(req: Request, options?: HttpRequestLogOptions): string`
-- `httpResponse(res: Response, req: Request, options: HttpResponseLogOptions): void`
-- `sftpTransaction(operation: SftpOperation, options?: SftpTransactionLogOptions): void`
-- `dbQueryTransaction(query: DbQuery, options?: DbQueryTransactionLogOptions): void`
+- `log(level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log`
+- `error(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log`
+- `warn(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log`
+- `info(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log`
+- `debug(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log`
+- `httpRequest(req: Request, options?: HttpRequestLogOptions): HttpRequestLog`
+- `httpResponse(res: Response, req: Request, options: HttpResponseLogOptions): HttpResponseLog`
+- `sftpTransaction(operation: SftpOperation, options?: SftpTransactionLogOptions): SftpTransactionLog`
+- `dbQueryTransaction(query: DbQuery, options?: DbQueryTransactionLogOptions): DbQueryTransactionLog`

package/dist/types.d.ts

@@ -19,10 +19,12 @@ export interface SerializableError {
     stack?: string;
 }
 export interface Log<T extends LogType = 'general'> {
+    logId: string;
     level: LogLevel;
     type: T;
     message: string;
     deploymentId: string;
+    workflowId: string;
     traceId: string;
     requestId: string;
     error?: SerializableError;
@@ -75,12 +77,6 @@ export interface DbQueryTransactionLog extends LogTransaction<'dbQueryTransactio
  * Configuration options for the logger
  */
 export interface LoggerOptions {
-    /** Default log level */
-    defaultLevel?: LogLevel;
-    /** Optional service name to include in logs */
-    serviceName?: string;
-    /** Optional environment name to include in logs */
-    environment?: string;
     /** Optional trace header key */
     traceHeaderKey?: string;
     /** Routes to ignore in trace middleware (supports glob patterns) */

package/dist/unnbound-logger.d.ts

@@ -1,4 +1,4 @@
-import { LogLevel, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions } from './types';
+import { LogLevel, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions, Log, HttpRequestLog, HttpResponseLog, SftpTransactionLog, DbQueryTransactionLog } from './types';
 import { Request, Response, NextFunction } from 'express';
 import { InternalAxiosRequestConfig } from 'axios';
 declare module 'axios' {
@@ -14,9 +14,7 @@ declare module 'axios' {
  */
 export declare class UnnboundLogger {
     private logger;
-    private defaultLevel;
-    private serviceName?;
-    private environment?;
+    private workflowId;
     private deploymentId;
     private traceHeaderKey;
     private ignoreTraceRoutes;
@@ -39,31 +37,31 @@ export declare class UnnboundLogger {
      * @param message - Log message
      * @param options - Additional logging options
      */
-    log(level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    log(level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log;
     /**
      * Logs an error message
      * @param message - Error message or object
      * @param options - Additional logging options
      */
-    error(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    error(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log;
     /**
      * Logs a warning message
      * @param message - Warning message
      * @param options - Additional logging options
      */
-    warn(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    warn(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log;
     /**
      * Logs an info message
      * @param message - Info message
      * @param options - Additional logging options
      */
-    info(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    info(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log;
     /**
      * Logs a debug message
      * @param message - Debug message
      * @param options - Additional logging options
      */
-    debug(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    debug(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log;
     /**
      * Constructs the full URL from request information
      * @param req - Express request object
@@ -76,14 +74,14 @@ export declare class UnnboundLogger {
      * @param options - Additional logging options
      * @returns The request ID for correlating with the response
      */
-    httpRequest(req: Request, options?: HttpRequestLogOptions): string;
+    httpRequest(req: Request, options?: HttpRequestLogOptions): HttpRequestLog;
     /**
      * Logs an HTTP response
      * @param res - Express response object
      * @param req - Express request object
      * @param options - Additional logging options
      */
-    httpResponse(res: Response, req: Request, options?: HttpResponseLogOptions): void;
+    httpResponse(res: Response, req: Request, options?: HttpResponseLogOptions): HttpResponseLog;
     /**
      * Logs an SFTP transaction
      * @param operation - SFTP operation details
@@ -98,7 +96,7 @@ export declare class UnnboundLogger {
         bytesTransferred?: number;
         filesListed?: number;
         sourcePath?: string;
-    }, options?: SftpTransactionLogOptions): void;
+    }, options?: SftpTransactionLogOptions): SftpTransactionLog;
     /**
      * Logs a database query transaction
      * @param query - Database query details
@@ -111,7 +109,7 @@ export declare class UnnboundLogger {
         status: 'success' | 'failure';
         rowsReturned?: number;
         rowsAffected?: number;
-    }, options?: DbQueryTransactionLogOptions): void;
+    }, options?: DbQueryTransactionLogOptions): DbQueryTransactionLog;
     traceMiddleware: (req: Request, res: Response, next: NextFunction) => void;
     axiosTraceMiddleware: {
         onFulfilled: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig;

package/dist/unnbound-logger.js

@@ -32,7 +32,7 @@ class UnnboundLogger {
             res.setHeader(this.traceHeaderKey, traceId);
             trace_context_1.traceContext.run(traceId, () => {
                 // Log the incoming request
-                const requestId = this.httpRequest(req, { traceId });
+                const reqLog = this.httpRequest(req, { traceId });
                 // Capture response body for logging
                 const originalSend = res.send;
                 res.send = function (body) {
@@ -41,7 +41,7 @@ class UnnboundLogger {
                 };
                 // Log the response when it finishes
                 res.on('finish', () => {
-                    this.httpResponse(res, req, { requestId, traceId });
+                    this.httpResponse(res, req, { requestId: reqLog.requestId, traceId });
                 });
                 next();
             });
@@ -168,20 +168,15 @@ class UnnboundLogger {
                 return Promise.reject(error);
             }
         };
-        this.defaultLevel = options.defaultLevel || 'info';
-        this.serviceName = options.serviceName;
-        this.environment = options.environment;
-        this.deploymentId = process.env.DEPLOYMENT_ID || '';
+        this.workflowId = process.env.UNNBOUND_WORKFLOW_ID || '';
+        this.deploymentId = process.env.UNNBOUND_DEPLOYMENT_ID || '';
         this.traceHeaderKey = options.traceHeaderKey || 'unnbound-trace-id';
         this.ignoreTraceRoutes = options.ignoreTraceRoutes || [];
         this.ignoreAxiosTraceRoutes = options.ignoreAxiosTraceRoutes || [];
         // Create Pino logger
         this.logger = (0, pino_1.default)({
-            level: this.defaultLevel,
-            base: {
-                ...(this.serviceName && { service: this.serviceName }),
-                ...(this.environment && { environment: this.environment }),
-            },
+            level: 'info',
+            base: {}, // Disable all default base fields (pid, hostname)
             timestamp: false, // Let CloudWatch handle timestamps
             formatters: {
                 level: (label) => {
@@ -214,10 +209,19 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     log(level, message, options = {}) {
+        const logId = (0, uuid_1.v4)();
         const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, uuid_1.v4)();
         const requestId = options.requestId || (0, uuid_1.v4)();
         let logEntry;
-        const { traceId: optionTraceId, requestId: optionRequestId, ...restOptions } = options;
+        const { traceId: optionTraceId, requestId: optionRequestId, level: optionLevel, ...restOptions } = options;
+        const baseEntry = {
+            logId,
+            type: 'general',
+            workflowId: this.workflowId,
+            traceId,
+            requestId,
+            deploymentId: this.deploymentId,
+        };
         if (message instanceof Error) {
             const error = {
                 name: message.name,
@@ -225,10 +229,7 @@ class UnnboundLogger {
                 stack: message.stack,
             };
             logEntry = {
-                type: 'general',
-                traceId,
-                requestId,
-                deploymentId: this.deploymentId,
+                ...baseEntry,
                 message: message.name,
                 error,
                 ...restOptions,
@@ -236,10 +237,7 @@ class UnnboundLogger {
         }
         else if (typeof message === 'string') {
             logEntry = {
-                type: 'general',
-                traceId,
-                requestId,
-                deploymentId: this.deploymentId,
+                ...baseEntry,
                 message,
                 ...restOptions,
             };
@@ -247,16 +245,16 @@ class UnnboundLogger {
         else {
             // If message is an object, it's part of the log entry
             logEntry = {
-                type: 'general',
-                traceId,
-                requestId,
-                deploymentId: this.deploymentId,
+                ...baseEntry,
                 ...message,
                 message: message.message || 'Structured log data',
                 ...restOptions,
             };
         }
-        this.logger[level](logEntry);
+        // Separate the message from the log data and explicitly exclude any level field
+        const { message: logMessage, level: excludedLevel, ...logData } = logEntry;
+        this.logger[level](logData, logMessage);
+        return logEntry;
     }
     /**
      * Logs an error message
@@ -264,7 +262,7 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     error(message, options = {}) {
-        this.log('error', message, options);
+        return this.log('error', message, options);
     }
     /**
      * Logs a warning message
@@ -272,7 +270,7 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     warn(message, options = {}) {
-        this.log('warn', message, options);
+        return this.log('warn', message, options);
     }
     /**
      * Logs an info message
@@ -280,7 +278,7 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     info(message, options = {}) {
-        this.log('info', message, options);
+        return this.log('info', message, options);
     }
     /**
      * Logs a debug message
@@ -288,7 +286,7 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     debug(message, options = {}) {
-        this.log('debug', message, options);
+        return this.log('debug', message, options);
     }
     /**
      * Constructs the full URL from request information
@@ -319,6 +317,7 @@ class UnnboundLogger {
      * @returns The request ID for correlating with the response
      */
     httpRequest(req, options = {}) {
+        const logId = (0, uuid_1.v4)();
         const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, uuid_1.v4)();
         const requestId = options.requestId || (0, uuid_1.v4)();
         const startTime = options.startTime || Date.now();
@@ -327,10 +326,13 @@ class UnnboundLogger {
             req.res.locals.requestId = requestId;
             req.res.locals.startTime = startTime;
             req.res.locals.traceId = traceId;
+            req.res.locals.workflowId = this.workflowId;
         }
         const logEntry = {
+            logId,
             type: 'httpRequest',
             message: req.ip === 'outgoing' ? 'Outgoing HTTP Request' : 'Incoming HTTP Request',
+            workflowId: this.workflowId,
             traceId,
             requestId,
             deploymentId: this.deploymentId,
@@ -343,8 +345,8 @@ class UnnboundLogger {
                 body: (0, logger_utils_1.safeJsonParse)(req.body),
             },
         };
-        this.log(options.level || 'info', logEntry);
-        return requestId;
+        const result = this.log(options.level || 'info', logEntry);
+        return result;
     }
     /**
      * Logs an HTTP response
@@ -353,12 +355,14 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     httpResponse(res, req, options = {}) {
+        const logId = (0, uuid_1.v4)();
         const requestId = res.locals.requestId || options.requestId || (0, uuid_1.v4)();
         const startTime = res.locals.startTime || options.startTime || Date.now();
+        const workflowId = res.locals.workflowId || this.workflowId;
         const traceId = res.locals.traceId || options.traceId || trace_context_1.traceContext.getTraceId() || (0, uuid_1.v4)();
         const duration = options.duration || (Date.now() - startTime);
         // Determine log level based on status code
-        let level = options.level || this.defaultLevel;
+        let level = options.level || 'info';
         if (!options.level) {
             if (res.statusCode >= 400) {
                 level = 'error';
@@ -368,8 +372,10 @@ class UnnboundLogger {
             }
         }
         const logEntry = {
+            logId,
             type: 'httpResponse',
             message: (0, http_status_messages_1.getStatusMessage)(res.statusCode),
+            workflowId: workflowId || '',
             traceId,
             requestId,
             deploymentId: this.deploymentId,
@@ -383,7 +389,8 @@ class UnnboundLogger {
                 body: (0, logger_utils_1.safeJsonParse)(res.locals.body),
             },
         };
-        this.log(level, logEntry);
+        const result = this.log(level, logEntry);
+        return result;
     }
     /**
      * Logs an SFTP transaction
@@ -391,20 +398,24 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     sftpTransaction(operation, options = {}) {
+        const logId = (0, uuid_1.v4)();
         const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, uuid_1.v4)();
         const requestId = options.requestId || (0, uuid_1.v4)();
         const duration = options.duration || (options.startTime ? Date.now() - options.startTime : 0);
         const level = operation.status === 'success' ? 'info' : 'error';
         const logEntry = {
+            logId,
             type: 'sftpTransaction',
             message: `SFTP ${operation.operation} ${operation.status} - ${operation.path}`,
+            workflowId: this.workflowId,
             traceId,
             requestId,
             deploymentId: this.deploymentId,
             duration,
             sftp: operation,
         };
-        this.log(level, logEntry);
+        const result = this.log(level, logEntry);
+        return result;
     }
     /**
      * Logs a database query transaction
@@ -412,20 +423,24 @@ class UnnboundLogger {
      * @param options - Additional logging options
      */
     dbQueryTransaction(query, options = {}) {
+        const logId = (0, uuid_1.v4)();
         const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, uuid_1.v4)();
         const requestId = options.requestId || (0, uuid_1.v4)();
         const duration = options.duration || (options.startTime ? Date.now() - options.startTime : 0);
         const level = query.status === 'success' ? 'info' : 'error';
         const logEntry = {
+            logId,
             type: 'dbQueryTransaction',
             message: `DB Query ${query.status} - ${query.vendor}`,
+            workflowId: this.workflowId,
             traceId,
             requestId,
             deploymentId: this.deploymentId,
             duration,
             db: query,
         };
-        this.log(level, logEntry);
+        const result = this.log(level, logEntry);
+        return result;
     }
 }
 exports.UnnboundLogger = UnnboundLogger;

package/dist/utils/http-status-messages.js

@@ -49,7 +49,7 @@ exports.httpStatusDetails = {
 function getStatusMessage(statusCode) {
     const status = exports.httpStatusDetails[statusCode];
     if (status) {
-        return `${status.message} - ${status.description}`;
+        return `${statusCode} ${status.message} - ${status.description}`;
     }
-    return 'Unknown Status';
+    return `${statusCode} Unknown Status`;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unnbound-logger-sdk",
-  "version": "2.0.4",
-  "description": "A structured logging library with TypeScript support using Pino. Provides consistent, well-typed logging across different operational contexts with automatic trace ID propagation.",
+  "version": "2.0.6",
+  "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.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {