unnbound-logger-sdk 3.0.0 → 3.0.1

package/dist/axios.d.ts

@@ -0,0 +1,9 @@
+import { Axios } from 'axios';
+import { HttpOptions } from './types';
+/**
+ * Wraps an axios instance to add tracing and span tracking
+ * @param axios - The axios instance to wrap
+ * @param options - Configuration options for HTTP tracing
+ * @returns The wrapped axios instance with span tracking
+ */
+export declare const traceAxios: (client: Axios, { ignoreTraceRoutes, traceHeaderKey, }?: HttpOptions) => Axios;

package/dist/axios.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceAxios = void 0;
+const axios_1 = require("axios");
+const types_1 = require("./types");
+const storage_1 = require("./storage");
+const utils_1 = require("./utils");
+const span_1 = require("./span");
+const buildOutgoingHttpPayload = (config, res) => ({
+    type: 'http',
+    http: {
+        url: [config.baseURL, config.url].filter(Boolean).join(''),
+        method: config.method?.toUpperCase() || 'GET',
+        incoming: false,
+        request: {
+            headers: config.headers,
+            body: (0, utils_1.safeJsonParse)(config.data),
+        },
+        response: res
+            ? {
+                headers: res?.headers,
+                status: res.status,
+                body: (0, utils_1.safeJsonParse)(res.data),
+            }
+            : undefined,
+    },
+});
+/**
+ * Wraps an axios instance to add tracing and span tracking
+ * @param axios - The axios instance to wrap
+ * @param options - Configuration options for HTTP tracing
+ * @returns The wrapped axios instance with span tracking
+ */
+const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes, traceHeaderKey = types_1.defaultTraceHeaderKey, } = {
+    ignoreTraceRoutes: types_1.defaultIgnoreTraceRoutes,
+    traceHeaderKey: types_1.defaultTraceHeaderKey,
+}) => {
+    const createSpanWrappedRequest = (originalMethod, method) => {
+        const { headers: defaultHeaders, ...partialDefaultConfig } = client.defaults;
+        const headers = { ...defaultHeaders.common, ...(method && defaultHeaders[method]) };
+        const defaultConfig = { ...partialDefaultConfig, headers };
+        return async (config) => {
+            config = (0, axios_1.mergeConfig)(defaultConfig, config);
+            // Determine the actual config and URL
+            const url = [config.baseURL, config.url].filter(Boolean).join('');
+            // 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];
+            config = { ...config, headers: { ...config.headers, [traceHeaderKey]: traceId } };
+            // Execute the request within a span
+            return (0, span_1.startSpan)(`Outgoing HTTP request`, () => originalMethod(config), (options) => {
+                if (!options)
+                    return buildOutgoingHttpPayload(config);
+                if (options.error)
+                    return buildOutgoingHttpPayload(config, (0, axios_1.isAxiosError)(options.error) ? options.error.response : undefined);
+                return buildOutgoingHttpPayload(config, options.result);
+            });
+        };
+    };
+    const request = client.request.bind(client);
+    const tracedRequest = createSpanWrappedRequest(request);
+    client.request = tracedRequest;
+    ['post', 'put', 'patch'].forEach((method) => {
+        const func = createSpanWrappedRequest(request, method);
+        client[method] = (url, data, config) => func({ ...config, url, data });
+    });
+    ['delete', 'get', 'head', 'options'].forEach((method) => {
+        const func = createSpanWrappedRequest(request, method);
+        client[method] = (url, config) => func({ ...config, url });
+    });
+    return client;
+};
+exports.traceAxios = traceAxios;

package/dist/http.js

@@ -0,0 +1 @@
+"use strict";

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * unnbound-logger
+ *
+ * A structured logging library built on Pino with TypeScript support.
+ * Provides consistent, well-typed logging across different operational contexts.
+ */
+export type { LogLevel, LogType, HttpMethod, Log, LogTransaction, SftpLog, HttpLog, SftpPayload, } from './types';
+export type { UnnboundLogger } from './logger';
+export { logger } from './logger';
+export { startSpan } from './span';
+export { traceAxios } from './axios';
+export { traceMiddleware } from './middleware';

package/dist/logger.d.ts

@@ -0,0 +1,15 @@
+import pino from 'pino';
+export interface UnnboundLogger extends Omit<pino.Logger, 'trace' | 'debug' | 'error' | 'info' | 'warn'> {
+    trace(object: {}, message: string): void;
+    trace(message: string): void;
+    debug(object: {}, message: string): void;
+    debug(message: string): void;
+    info(object: {}, message: string): void;
+    info(message: string): void;
+    warn(object: {}, message: string): void;
+    warn(message: string): void;
+    error<O extends {
+        err: unknown;
+    }>(object: O, message: string): void;
+}
+export declare const logger: UnnboundLogger;

package/dist/logger.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const pino_1 = __importDefault(require("pino"));
+const storage_1 = require("./storage");
+exports.logger = (0, pino_1.default)({
+    level: process.env.LOG_LEVEL ?? 'info',
+    base: {
+        environment: process.env.ENVIRONMENT,
+        workflowId: process.env.UNNBOUND_WORKFLOW_ID,
+        workflowUrl: process.env.UNNBOUND_WORKFLOW_URL,
+        serviceId: process.env.UNNBOUND_SERVICE_ID,
+        deploymentId: process.env.UNNBOUND_DEPLOYMENT_ID,
+    },
+    mixin: () => ({ ...storage_1.storage.getStore() }),
+    serializers: {
+        req: pino_1.default.stdSerializers.req,
+        res: pino_1.default.stdSerializers.res,
+        err: pino_1.default.stdSerializers.err,
+    },
+    // Let CloudWatch handle timestamps
+    timestamp: false,
+    // Change message field from 'msg' to 'message'
+    messageKey: 'message',
+    formatters: {
+        level: (level) => ({ level }),
+    },
+    redact: {
+        paths: [
+            'http.request.headers.authorization',
+            'http.response.headers.authorization',
+            'http.request.headers.Authorization',
+            'http.response.headers.Authorization',
+            'err.config',
+        ],
+        remove: true,
+    },
+});
+process.on('uncaughtException', (err, origin) => {
+    exports.logger.error({ err, origin }, `Uncaught exception.`);
+});

package/dist/middleware.d.ts

@@ -0,0 +1,3 @@
+import { RequestHandler } from 'express';
+import { HttpOptions } from './types';
+export declare const traceMiddleware: ({ ignoreTraceRoutes, traceHeaderKey, }?: HttpOptions) => RequestHandler;

package/dist/middleware.js

@@ -0,0 +1,70 @@
+"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 getFullUrl = (req) => {
+    const url = req.originalUrl || req.url;
+    if (url?.startsWith('http://') || url?.startsWith('https://'))
+        return url;
+    // Check if we have a workflow URL configured (preferred method)
+    if (process.env.UNNBOUND_WORKFLOW_URL) {
+        // Use workflow URL as the base URL
+        return `${process.env.UNNBOUND_WORKFLOW_URL.replace(/\/$/, '')}${url}`;
+    }
+    // Fallback to constructing from request info for incoming requests
+    const protocol = req.protocol || (req.secure ? 'https' : 'http');
+    const host = req.get('host') || req.get('x-forwarded-host') || 'localhost';
+    return `${protocol}://${host}${url}`;
+};
+const buildIncomingHttpPayload = (req, res, body) => ({
+    type: 'http',
+    http: {
+        url: getFullUrl(req),
+        method: req.method,
+        ip: (0, utils_1.normalizeIp)(req.ip),
+        incoming: true,
+        request: {
+            headers: req.headers,
+            body: (0, utils_1.safeJsonParse)(req.body),
+        },
+        response: res
+            ? {
+                headers: res?.headers,
+                status: res.statusCode,
+                body: (0, utils_1.safeJsonParse)(body),
+            }
+            : undefined,
+    },
+});
+const traceMiddleware = ({ ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes, traceHeaderKey = types_1.defaultTraceHeaderKey, } = {
+    ignoreTraceRoutes: types_1.defaultIgnoreTraceRoutes,
+    traceHeaderKey: types_1.defaultTraceHeaderKey,
+}) => async (req, res, next) => {
+    if ((0, utils_1.shouldIgnorePath)(req.path, ignoreTraceRoutes))
+        return next();
+    const traceId = req.header(traceHeaderKey) || (0, uuid_1.v4)();
+    res.setHeader(traceHeaderKey, traceId);
+    return await storage_1.storage.run({ [storage_1.ContextAttribute.TraceId]: traceId }, async () => {
+        return await (0, span_1.startSpan)('Incoming HTTP request', async () => {
+            return new Promise((resolve) => {
+                // Capture response body for logging
+                const send = res.send.bind(res);
+                res.send = (body) => {
+                    res.locals.body = body;
+                    return send(body);
+                };
+                res.on('finish', () => resolve());
+                return next();
+            });
+        }, (o) => {
+            return buildIncomingHttpPayload(req, o
+                ? { statusCode: res.statusCode, headers: res.getHeaders() }
+                : undefined, res.locals.body);
+        });
+    });
+};
+exports.traceMiddleware = traceMiddleware;

package/dist/sftp.d.ts

@@ -0,0 +1,10 @@
+import { SftpPayload } from './types';
+/**
+ * Builds a SFTP payload
+ * @param payload - SFTP payload
+ * @returns The SFTP payload
+ */
+export declare const buildSftpPayload: (payload: SftpPayload) => {
+    type: string;
+    sftp: SftpPayload;
+};

package/dist/sftp.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSftpPayload = void 0;
+/**
+ * Builds a SFTP payload
+ * @param payload - SFTP payload
+ * @returns The SFTP payload
+ */
+const buildSftpPayload = (payload) => ({
+    type: 'sftp',
+    sftp: payload,
+});
+exports.buildSftpPayload = buildSftpPayload;

package/dist/span.d.ts

@@ -0,0 +1,16 @@
+type LogPayloadGetterOptions<T> = {
+    error: unknown;
+    result?: never;
+} | {
+    error?: never;
+    result: T;
+};
+type LogPayloadGetter<T> = object | ((o?: LogPayloadGetterOptions<T>) => object);
+/**
+ * Starts a span that tracks the duration of a callback
+ * @param spanName - The span name to use for logging
+ * @param callback - The async callback to execute
+ * @returns The result of the callback
+ */
+export declare const startSpan: <T>(spanName: string, callback: () => Promise<T>, getter?: LogPayloadGetter<T>) => Promise<T>;
+export {};

package/dist/span.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSpan = void 0;
+const uuid_1 = require("uuid");
+const storage_1 = require("./storage");
+const logger_1 = require("./logger");
+/**
+ * Starts a span that tracks the duration of a callback
+ * @param spanName - The span name to use for logging
+ * @param callback - The async callback to execute
+ * @returns The result of the callback
+ */
+const startSpan = async (spanName, callback, getter) => {
+    const spanId = (0, uuid_1.v4)();
+    const start = performance.now();
+    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,
+    }, async () => {
+        logger_1.logger.info({ ...getLogPayload(getter) }, `${spanName} started.`);
+        try {
+            const result = await callback();
+            logger_1.logger.info({ ...getLogPayload(getter, { result }), duration: getDuration(start) }, `${spanName} completed.`);
+            return result;
+        }
+        catch (error) {
+            logger_1.logger.error({ ...getLogPayload(getter, { error }), err: error, duration: getDuration(start) }, `${spanName} failed.`);
+            throw error;
+        }
+    });
+};
+exports.startSpan = startSpan;
+const getLogPayload = (getter, o) => {
+    if (typeof getter !== 'function')
+        return getter;
+    return getter(o);
+};
+const getDuration = (start) => Math.round(performance.now() - start);

package/dist/storage.d.ts

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

package/dist/storage.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storage = exports.ContextAttribute = 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/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Type definitions for structured logging library
+ */
+/**
+ * Available log levels
+ */
+export type LogLevel = 'info' | 'debug' | 'error' | 'warn';
+/**
+ * Available log types
+ */
+export type LogType = 'general' | 'http' | 'sftp' | 'dbQueryTransaction';
+/**
+ * HTTP methods supported for HTTP logging
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+export interface Log<T extends LogType = 'general'> {
+    level: LogLevel;
+    message: string;
+    traceId: string;
+    spanId?: string;
+    type: T;
+    serviceId: string;
+    deploymentId: string;
+    workflowId: string;
+    err?: unknown;
+}
+export interface LogTransaction<T extends LogType> extends Log<T> {
+    duration?: number;
+}
+export interface HttpLog extends LogTransaction<'http'> {
+    http: {
+        url: string;
+        method: string;
+        ip?: string;
+        request: {
+            headers: Record<string, string>;
+            body?: unknown;
+        };
+        response?: {
+            headers: Record<string, string>;
+            status: number;
+            body?: unknown;
+        };
+    };
+}
+export type SftpOperation = 'connect' | 'upload' | 'download' | 'list' | 'delete' | 'rename' | 'stat' | 'exists' | 'realPath' | 'get' | 'put' | 'cwd' | 'mkdir' | 'rmdir' | 'chmod' | 'append' | 'uploadDir' | 'downloadDir' | 'end';
+export interface SftpPayload {
+    host: string;
+    operation: SftpOperation;
+    path?: string;
+    bytes?: number;
+    destinationPath?: string;
+    files?: number;
+}
+export interface SftpLog extends LogTransaction<'sftp'> {
+    sftp: SftpPayload;
+}
+export interface HttpOptions {
+    ignoreTraceRoutes?: string[];
+    traceHeaderKey?: string;
+}
+export declare const defaultIgnoreTraceRoutes: string[];
+export declare const defaultTraceHeaderKey = "x-unnbound-trace-id";

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Type definitions for structured logging library
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultTraceHeaderKey = exports.defaultIgnoreTraceRoutes = void 0;
+exports.defaultIgnoreTraceRoutes = ['/health', '/healthcheck'];
+exports.defaultTraceHeaderKey = 'x-unnbound-trace-id';

package/dist/unnbound-logger.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Core logger implementation
+ */
+import pino from 'pino';
+import { LogLevel, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, DbQueryTransactionLogOptions, Log, HttpRequestLog, HttpResponseLog, DbQueryTransactionLog } from './types';
+import { Request, Response, NextFunction } from 'express';
+import { InternalAxiosRequestConfig } from 'axios';
+declare module 'axios' {
+    interface InternalAxiosRequestConfig {
+        metadata?: {
+            startTime: number;
+            requestId?: string;
+        };
+    }
+}
+export declare const logger: pino.Logger;
+/**
+ * UnnboundLogger provides typed, structured logging using Pino
+ */
+export declare class UnnboundLogger {
+    private logger;
+    private workflowId;
+    private workflowUrl;
+    private serviceId;
+    private deploymentId;
+    private traceHeaderKey;
+    private ignoreTraceRoutes;
+    private ignoreAxiosTraceRoutes;
+    /**
+     * Creates a new UnnboundLogger instance
+     * @param options - Configuration options for the logger
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Checks if a path matches any of the ignore patterns
+     * @param path - The path to check
+     * @param patterns - Array of glob patterns to match against
+     * @returns boolean indicating if the path should be ignored
+     */
+    private shouldIgnorePath;
+    /**
+     * Logs a general message
+     * @param level - Log level
+     * @param message - Log message
+     * @param options - Additional logging options
+     */
+    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): Log;
+    /**
+     * Logs a warning message
+     * @param message - Warning message
+     * @param options - Additional logging options
+     */
+    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): Log;
+    /**
+     * Logs a debug message
+     * @param message - Debug message
+     * @param options - Additional logging options
+     */
+    debug(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): Log;
+    /**
+     * Constructs the full URL from request information
+     * @param req - Express request object
+     * @returns Full URL string
+     */
+    private constructFullUrl;
+    /**
+     * Logs an HTTP request
+     * @param req - Express request object
+     * @param options - Additional logging options
+     * @returns The request ID for correlating with the response
+     */
+    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): HttpResponseLog;
+    /**
+     * Logs a database query transaction
+     * @param query - Database query details
+     * @param options - Additional logging options
+     */
+    dbQueryTransaction(query: {
+        instance: string;
+        vendor: 'postgres' | 'mysql' | 'mssql' | 'mongodb';
+        query?: string;
+        status: 'success' | 'failure';
+        rowsReturned?: number;
+        rowsAffected?: number;
+    }, options?: DbQueryTransactionLogOptions): DbQueryTransactionLog;
+    traceMiddleware: (req: Request, res: Response, next: NextFunction) => void;
+    axiosTraceMiddleware: {
+        onFulfilled: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig;
+        onRejected: (error: any) => any;
+    };
+    axiosResponseInterceptor: {
+        onFulfilled: (response: any) => any;
+        onRejected: (error: any) => any;
+    };
+}