@ibm/ibmi-mcp-server 0.1.0

package/dist/utils/security/sanitization.js

@@ -0,0 +1,472 @@
+/**
+ * @fileoverview Provides a comprehensive `Sanitization` class for various input cleaning and validation tasks.
+ * This module includes utilities for sanitizing HTML, strings, URLs, file paths, JSON, numbers,
+ * and for redacting sensitive information from data intended for logging.
+ * @module src/utils/security/sanitization
+ */
+import path from "path";
+import sanitizeHtml from "sanitize-html";
+import validator from "validator";
+import { JsonRpcErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, requestContextService } from "../index.js";
+/**
+ * A singleton class providing various methods for input sanitization.
+ * Aims to protect against common vulnerabilities like XSS and path traversal.
+ */
+export class Sanitization {
+    /** @private */
+    static instance;
+    /**
+     * Default list of field names considered sensitive for log redaction.
+     * Case-insensitive matching is applied.
+     * @private
+     */
+    sensitiveFields = [
+        "password",
+        "token",
+        "secret",
+        "key",
+        "apiKey",
+        "auth",
+        "credential",
+        "jwt",
+        "ssn",
+        "credit",
+        "card",
+        "cvv",
+        "authorization",
+    ];
+    /**
+     * Default configuration for HTML sanitization.
+     * @private
+     */
+    defaultHtmlSanitizeConfig = {
+        allowedTags: [
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "h5",
+            "h6",
+            "p",
+            "a",
+            "ul",
+            "ol",
+            "li",
+            "b",
+            "i",
+            "strong",
+            "em",
+            "strike",
+            "code",
+            "hr",
+            "br",
+            "div",
+            "table",
+            "thead",
+            "tbody",
+            "tr",
+            "th",
+            "td",
+            "pre",
+        ],
+        allowedAttributes: {
+            a: ["href", "name", "target"],
+            img: ["src", "alt", "title", "width", "height"],
+            "*": ["class", "id", "style"],
+        },
+        preserveComments: false,
+    };
+    /** @private */
+    constructor() { }
+    /**
+     * Retrieves the singleton instance of the `Sanitization` class.
+     * @returns The singleton `Sanitization` instance.
+     */
+    static getInstance() {
+        if (!Sanitization.instance) {
+            Sanitization.instance = new Sanitization();
+        }
+        return Sanitization.instance;
+    }
+    /**
+     * Sets or extends the list of sensitive field names for log sanitization.
+     * @param fields - An array of field names to add to the sensitive list.
+     */
+    setSensitiveFields(fields) {
+        this.sensitiveFields = [
+            ...new Set([
+                ...this.sensitiveFields,
+                ...fields.map((f) => f.toLowerCase()),
+            ]),
+        ];
+        const logContext = requestContextService.createRequestContext({
+            operation: "Sanitization.setSensitiveFields",
+            newSensitiveFieldCount: this.sensitiveFields.length,
+        });
+        logger.debug(logContext, "Updated sensitive fields list for log sanitization");
+    }
+    /**
+     * Gets a copy of the current list of sensitive field names.
+     * @returns An array of sensitive field names.
+     */
+    getSensitiveFields() {
+        return [...this.sensitiveFields];
+    }
+    /**
+     * Sanitizes an HTML string by removing potentially malicious tags and attributes.
+     * @param input - The HTML string to sanitize.
+     * @param config - Optional custom configuration for `sanitize-html`.
+     * @returns The sanitized HTML string. Returns an empty string if input is falsy.
+     */
+    sanitizeHtml(input, config) {
+        if (!input)
+            return "";
+        const effectiveConfig = {
+            allowedTags: config?.allowedTags ?? this.defaultHtmlSanitizeConfig.allowedTags,
+            allowedAttributes: config?.allowedAttributes ??
+                this.defaultHtmlSanitizeConfig.allowedAttributes,
+            transformTags: config?.transformTags, // Can be undefined
+            preserveComments: config?.preserveComments ??
+                this.defaultHtmlSanitizeConfig.preserveComments,
+        };
+        const options = {
+            allowedTags: effectiveConfig.allowedTags,
+            allowedAttributes: effectiveConfig.allowedAttributes,
+            transformTags: effectiveConfig.transformTags,
+        };
+        if (effectiveConfig.preserveComments) {
+            // Ensure allowedTags is an array before spreading
+            const baseTags = Array.isArray(options.allowedTags)
+                ? options.allowedTags
+                : [];
+            options.allowedTags = [...baseTags, "!--"];
+        }
+        return sanitizeHtml(input, options);
+    }
+    /**
+     * Sanitizes a string based on its intended context (e.g., HTML, URL, text).
+     * **Important:** `context: 'javascript'` is disallowed due to security risks.
+     *
+     * @param input - The string to sanitize.
+     * @param options - Options specifying the sanitization context.
+     * @returns The sanitized string. Returns an empty string if input is falsy.
+     * @throws {McpError} If `options.context` is 'javascript', or URL validation fails.
+     */
+    sanitizeString(input, options = {}) {
+        if (!input)
+            return "";
+        const context = options.context ?? "text";
+        switch (context) {
+            case "html": {
+                const config = {};
+                if (options.allowedTags) {
+                    config.allowedTags = options.allowedTags;
+                }
+                if (options.allowedAttributes) {
+                    config.allowedAttributes = this.convertAttributesFormat(options.allowedAttributes);
+                }
+                return this.sanitizeHtml(input, config);
+            }
+            case "attribute":
+                return sanitizeHtml(input, { allowedTags: [], allowedAttributes: {} });
+            case "url":
+                if (!validator.isURL(input, {
+                    protocols: ["http", "https"],
+                    require_protocol: true,
+                    require_host: true,
+                })) {
+                    logger.warning(requestContextService.createRequestContext({
+                        operation: "Sanitization.sanitizeString.urlWarning",
+                        invalidUrlAttempt: input,
+                    }), "Potentially invalid URL detected during string sanitization (context: url)");
+                    return "";
+                }
+                return validator.trim(input);
+            case "javascript":
+                logger.error(requestContextService.createRequestContext({
+                    operation: "Sanitization.sanitizeString.jsAttempt",
+                    inputSnippet: input.substring(0, 50),
+                }), "Attempted JavaScript sanitization via sanitizeString, which is disallowed.");
+                throw new McpError(JsonRpcErrorCode.ValidationError, "JavaScript sanitization is not supported through sanitizeString due to security risks.");
+            case "text":
+            default:
+                return sanitizeHtml(input, { allowedTags: [], allowedAttributes: {} });
+        }
+    }
+    /**
+     * Converts attribute format for `sanitizeHtml`.
+     * @param attrs - Attributes in `{ tagName: ['attr1'] }` format.
+     * @returns Attributes in `sanitize-html` expected format.
+     * @private
+     */
+    convertAttributesFormat(attrs) {
+        return attrs;
+    }
+    /**
+     * Sanitizes a URL string by validating its format and protocol.
+     * @param input - The URL string to sanitize.
+     * @param allowedProtocols - Array of allowed URL protocols. Default: `['http', 'https']`.
+     * @returns The sanitized and trimmed URL string.
+     * @throws {McpError} If the URL is invalid or uses a disallowed protocol.
+     */
+    sanitizeUrl(input, allowedProtocols = ["http", "https"]) {
+        try {
+            const trimmedInput = input.trim();
+            if (!validator.isURL(trimmedInput, {
+                protocols: allowedProtocols,
+                require_protocol: true,
+                require_host: true,
+            })) {
+                throw new Error("Invalid URL format or protocol not in allowed list.");
+            }
+            const lowercasedInput = trimmedInput.toLowerCase();
+            if (lowercasedInput.startsWith("javascript:") ||
+                lowercasedInput.startsWith("data:") ||
+                lowercasedInput.startsWith("vbscript:")) {
+                throw new Error("Disallowed pseudo-protocol (javascript:, data:, or vbscript:) in URL.");
+            }
+            return trimmedInput;
+        }
+        catch (error) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, error instanceof Error
+                ? error.message
+                : "Invalid or unsafe URL provided.", { input });
+        }
+    }
+    /**
+     * Sanitizes a file path to prevent path traversal and normalize format.
+     * @param input - The file path string to sanitize.
+     * @param options - Options to control sanitization behavior.
+     * @returns An object with the sanitized path and sanitization metadata.
+     * @throws {McpError} If the path is invalid or unsafe.
+     */
+    sanitizePath(input, options = {}) {
+        const originalInput = input;
+        const effectiveOptions = {
+            toPosix: options.toPosix ?? false,
+            allowAbsolute: options.allowAbsolute ?? false,
+            rootDir: options.rootDir ? path.resolve(options.rootDir) : undefined,
+        };
+        let wasAbsoluteInitially = false;
+        try {
+            if (!input || typeof input !== "string")
+                throw new Error("Invalid path input: must be a non-empty string.");
+            if (input.includes("\0"))
+                throw new Error("Path contains null byte, which is disallowed.");
+            let normalized = path.normalize(input);
+            wasAbsoluteInitially = path.isAbsolute(normalized);
+            if (effectiveOptions.toPosix) {
+                normalized = normalized.replace(/\\/g, "/");
+            }
+            let finalSanitizedPath;
+            if (effectiveOptions.rootDir) {
+                const fullPath = path.resolve(effectiveOptions.rootDir, normalized);
+                if (!fullPath.startsWith(effectiveOptions.rootDir + path.sep) &&
+                    fullPath !== effectiveOptions.rootDir) {
+                    throw new Error("Path traversal detected: attempts to escape the defined root directory.");
+                }
+                finalSanitizedPath = path.relative(effectiveOptions.rootDir, fullPath);
+                finalSanitizedPath =
+                    finalSanitizedPath === "" ? "." : finalSanitizedPath;
+                if (path.isAbsolute(finalSanitizedPath) &&
+                    !effectiveOptions.allowAbsolute) {
+                    throw new Error("Path resolved to absolute outside root when absolute paths are disallowed.");
+                }
+            }
+            else {
+                if (path.isAbsolute(normalized)) {
+                    if (!effectiveOptions.allowAbsolute) {
+                        throw new Error("Absolute paths are disallowed by current options.");
+                    }
+                    else {
+                        finalSanitizedPath = normalized;
+                    }
+                }
+                else {
+                    const resolvedAgainstCwd = path.resolve(normalized);
+                    const currentWorkingDir = path.resolve(".");
+                    if (!resolvedAgainstCwd.startsWith(currentWorkingDir + path.sep) &&
+                        resolvedAgainstCwd !== currentWorkingDir) {
+                        throw new Error("Relative path traversal detected (escapes current working directory context).");
+                    }
+                    finalSanitizedPath = normalized;
+                }
+            }
+            return {
+                sanitizedPath: finalSanitizedPath,
+                originalInput,
+                wasAbsolute: wasAbsoluteInitially,
+                convertedToRelative: wasAbsoluteInitially &&
+                    !path.isAbsolute(finalSanitizedPath) &&
+                    !effectiveOptions.allowAbsolute,
+                optionsUsed: effectiveOptions,
+            };
+        }
+        catch (error) {
+            logger.warning(requestContextService.createRequestContext({
+                operation: "Sanitization.sanitizePath.error",
+                originalPathInput: originalInput,
+                pathOptionsUsed: effectiveOptions,
+                errorMessage: error instanceof Error ? error.message : String(error),
+            }), "Path sanitization error");
+            throw new McpError(JsonRpcErrorCode.ValidationError, error instanceof Error
+                ? error.message
+                : "Invalid or unsafe path provided.", { input: originalInput });
+        }
+    }
+    /**
+     * Sanitizes a JSON string by parsing it to validate its format.
+     * Optionally checks if the JSON string exceeds a maximum allowed size.
+     * @template T The expected type of the parsed JSON object. Defaults to `unknown`.
+     * @param input - The JSON string to sanitize/validate.
+     * @param maxSize - Optional maximum allowed size of the JSON string in bytes.
+     * @returns The parsed JavaScript object.
+     * @throws {McpError} If input is not a string, too large, or invalid JSON.
+     */
+    sanitizeJson(input, maxSize) {
+        try {
+            if (typeof input !== "string")
+                throw new Error("Invalid input: expected a JSON string.");
+            if (maxSize !== undefined && Buffer.byteLength(input, "utf8") > maxSize) {
+                throw new McpError(JsonRpcErrorCode.ValidationError, `JSON string exceeds maximum allowed size of ${maxSize} bytes.`, { actualSize: Buffer.byteLength(input, "utf8"), maxSize });
+            }
+            return JSON.parse(input);
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(JsonRpcErrorCode.ValidationError, error instanceof Error ? error.message : "Invalid JSON format.", {
+                inputPreview: input.length > 100 ? `${input.substring(0, 100)}...` : input,
+            });
+        }
+    }
+    /**
+     * Validates and sanitizes a numeric input, converting strings to numbers.
+     * Clamps the number to `min`/`max` if provided.
+     * @param input - The number or string to validate and sanitize.
+     * @param min - Minimum allowed value (inclusive).
+     * @param max - Maximum allowed value (inclusive).
+     * @returns The sanitized (and potentially clamped) number.
+     * @throws {McpError} If input is not a valid number, NaN, or Infinity.
+     */
+    sanitizeNumber(input, min, max) {
+        let value;
+        if (typeof input === "string") {
+            const trimmedInput = input.trim();
+            if (trimmedInput === "" || !validator.isNumeric(trimmedInput)) {
+                throw new McpError(JsonRpcErrorCode.ValidationError, "Invalid number format: input is empty or not numeric.", { input });
+            }
+            value = parseFloat(trimmedInput);
+        }
+        else if (typeof input === "number") {
+            value = input;
+        }
+        else {
+            throw new McpError(JsonRpcErrorCode.ValidationError, "Invalid input type: expected number or string.", { input: String(input) });
+        }
+        if (isNaN(value) || !isFinite(value)) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, "Invalid number value (NaN or Infinity).", { input });
+        }
+        let clamped = false;
+        const originalValueForLog = value;
+        if (min !== undefined && value < min) {
+            value = min;
+            clamped = true;
+        }
+        if (max !== undefined && value > max) {
+            value = max;
+            clamped = true;
+        }
+        if (clamped) {
+            logger.debug(requestContextService.createRequestContext({
+                operation: "Sanitization.sanitizeNumber.clamped",
+                originalInput: String(input),
+                parsedValue: originalValueForLog,
+                minValue: min,
+                maxValue: max,
+                clampedValue: value,
+            }), "Number clamped to range.");
+        }
+        return value;
+    }
+    /**
+     * Sanitizes input for logging by redacting sensitive fields.
+     * Creates a deep clone and replaces values of fields matching `this.sensitiveFields`
+     * (case-insensitive substring match) with "[REDACTED]".
+     *
+     * It uses `structuredClone` if available for a high-fidelity deep clone.
+     * If `structuredClone` is not available (e.g., in older Node.js environments),
+     * it falls back to `JSON.parse(JSON.stringify(input))`. This fallback has limitations:
+     * - `Date` objects are converted to ISO date strings.
+     * - `undefined` values within objects are removed.
+     * - `Map`, `Set`, `RegExp` objects are converted to empty objects (`{}`).
+     * - Functions are removed.
+     * - `BigInt` values will throw an error during `JSON.stringify` unless a `toJSON` method is provided.
+     * - Circular references will cause `JSON.stringify` to throw an error.
+     *
+     * @param input - The input data to sanitize for logging.
+     * @returns A sanitized (deep cloned) version of the input, safe for logging.
+     *   Returns original input if not object/array, or "[Log Sanitization Failed]" on error.
+     */
+    sanitizeForLogging(input) {
+        try {
+            if (!input || typeof input !== "object")
+                return input;
+            const clonedInput = typeof globalThis.structuredClone === "function"
+                ? globalThis.structuredClone(input)
+                : JSON.parse(JSON.stringify(input));
+            this.redactSensitiveFields(clonedInput);
+            return clonedInput;
+        }
+        catch (error) {
+            logger.error(requestContextService.createRequestContext({
+                operation: "Sanitization.sanitizeForLogging.error",
+                errorMessage: error instanceof Error ? error.message : String(error),
+            }), "Error during log sanitization, returning placeholder.");
+            return "[Log Sanitization Failed]";
+        }
+    }
+    /**
+     * Recursively redacts sensitive fields in an object or array in place.
+     * @param obj - The object or array to redact.
+     * @private
+     */
+    redactSensitiveFields(obj) {
+        if (!obj || typeof obj !== "object")
+            return;
+        if (Array.isArray(obj)) {
+            obj.forEach((item) => this.redactSensitiveFields(item));
+            return;
+        }
+        for (const key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                const value = obj[key];
+                // Split camelCase and snake_case/kebab-case keys into words
+                const keyWords = key
+                    .replace(/([A-Z])/g, " $1") // Add space before uppercase letters
+                    .toLowerCase()
+                    .split(/[\s_-]+/); // Split by space, underscore, or hyphen
+                const isSensitive = keyWords.some((word) => this.sensitiveFields.includes(word));
+                if (isSensitive) {
+                    obj[key] = "[REDACTED]";
+                }
+                else if (value && typeof value === "object") {
+                    this.redactSensitiveFields(value);
+                }
+            }
+        }
+    }
+}
+/**
+ * Singleton instance of the `Sanitization` class.
+ * Use this for all input sanitization tasks.
+ */
+export const sanitization = Sanitization.getInstance();
+/**
+ * Convenience function calling `sanitization.sanitizeForLogging`.
+ * @param input - The input data to sanitize.
+ * @returns A sanitized version of the input, safe for logging.
+ */
+export const sanitizeInputForLogging = (input) => sanitization.sanitizeForLogging(input);
+//# sourceMappingURL=sanitization.js.map

package/dist/utils/security/sanitization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitization.js","sourceRoot":"","sources":["../../../src/utils/security/sanitization.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,YAAY,MAAM,eAAe,CAAC;AACzC,OAAO,SAAS,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAwDjE;;;GAGG;AACH,MAAM,OAAO,YAAY;IACvB,eAAe;IACP,MAAM,CAAC,QAAQ,CAAe;IAEtC;;;;OAIG;IACK,eAAe,GAAa;QAClC,UAAU;QACV,OAAO;QACP,QAAQ;QACR,KAAK;QACL,QAAQ;QACR,MAAM;QACN,YAAY;QACZ,KAAK;QACL,KAAK;QACL,QAAQ;QACR,MAAM;QACN,KAAK;QACL,eAAe;KAChB,CAAC;IAEF;;;OAGG;IACK,yBAAyB,GAAuB;QACtD,WAAW,EAAE;YACX,IAAI;YACJ,IAAI;YACJ,IAAI;YACJ,IAAI;YACJ,IAAI;YACJ,IAAI;YACJ,GAAG;YACH,GAAG;YACH,IAAI;YACJ,IAAI;YACJ,IAAI;YACJ,GAAG;YACH,GAAG;YACH,QAAQ;YACR,IAAI;YACJ,QAAQ;YACR,MAAM;YACN,IAAI;YACJ,IAAI;YACJ,KAAK;YACL,OAAO;YACP,OAAO;YACP,OAAO;YACP,IAAI;YACJ,IAAI;YACJ,IAAI;YACJ,KAAK;SACN;QACD,iBAAiB,EAAE;YACjB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;YAC7B,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC;YAC/C,GAAG,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC;SAC9B;QACD,gBAAgB,EAAE,KAAK;KACxB,CAAC;IAEF,eAAe;IACf,gBAAuB,CAAC;IAExB;;;OAGG;IACI,MAAM,CAAC,WAAW;QACvB,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;YAC3B,YAAY,CAAC,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;QAC7C,CAAC;QACD,OAAO,YAAY,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACI,kBAAkB,CAAC,MAAgB;QACxC,IAAI,CAAC,eAAe,GAAG;YACrB,GAAG,IAAI,GAAG,CAAC;gBACT,GAAG,IAAI,CAAC,eAAe;gBACvB,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;aACtC,CAAC;SACH,CAAC;QACF,MAAM,UAAU,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YAC5D,SAAS,EAAE,iCAAiC;YAC5C,sBAAsB,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM;SACpD,CAAC,CAAC;QACH,MAAM,CAAC,KAAK,CACV,UAAU,EACV,oDAAoD,CACrD,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,kBAAkB;QACvB,OAAO,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACI,YAAY,CAAC,KAAa,EAAE,MAA2B;QAC5D,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QACtB,MAAM,eAAe,GAAG;YACtB,WAAW,EACT,MAAM,EAAE,WAAW,IAAI,IAAI,CAAC,yBAAyB,CAAC,WAAW;YACnE,iBAAiB,EACf,MAAM,EAAE,iBAAiB;gBACzB,IAAI,CAAC,yBAAyB,CAAC,iBAAiB;YAClD,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,mBAAmB;YACzD,gBAAgB,EACd,MAAM,EAAE,gBAAgB;gBACxB,IAAI,CAAC,yBAAyB,CAAC,gBAAgB;SAClD,CAAC;QAEF,MAAM,OAAO,GAA0B;YACrC,WAAW,EAAE,eAAe,CAAC,WAAW;YACxC,iBAAiB,EAAE,eAAe,CAAC,iBAAiB;YACpD,aAAa,EAAE,eAAe,CAAC,aAAa;SAC7C,CAAC;QAEF,IAAI,eAAe,CAAC,gBAAgB,EAAE,CAAC;YACrC,kDAAkD;YAClD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC;gBACjD,CAAC,CAAC,OAAO,CAAC,WAAW;gBACrB,CAAC,CAAC,EAAE,CAAC;YACP,OAAO,CAAC,WAAW,GAAG,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;OAQG;IACI,cAAc,CACnB,KAAa,EACb,UAAiC,EAAE;QAEnC,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QAEtB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;QAE1C,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAuB,EAAE,CAAC;gBACtC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;oBACxB,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;gBAC3C,CAAC;gBACD,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;oBAC9B,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAC,uBAAuB,CACrD,OAAO,CAAC,iBAAiB,CAC1B,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC1C,CAAC;YACD,KAAK,WAAW;gBACd,OAAO,YAAY,CAAC,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,CAAC,CAAC;YACzE,KAAK,KAAK;gBACR,IACE,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE;oBACtB,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;oBAC5B,gBAAgB,EAAE,IAAI;oBACtB,YAAY,EAAE,IAAI;iBACnB,CAAC,EACF,CAAC;oBACD,MAAM,CAAC,OAAO,CACZ,qBAAqB,CAAC,oBAAoB,CAAC;wBACzC,SAAS,EAAE,wCAAwC;wBACnD,iBAAiB,EAAE,KAAK;qBACzB,CAAC,EACF,4EAA4E,CAC7E,CAAC;oBACF,OAAO,EAAE,CAAC;gBACZ,CAAC;gBACD,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC/B,KAAK,YAAY;gBACf,MAAM,CAAC,KAAK,CACV,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,uCAAuC;oBAClD,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;iBACrC,CAAC,EACF,4EAA4E,CAC7E,CAAC;gBACF,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,wFAAwF,CACzF,CAAC;YACJ,KAAK,MAAM,CAAC;YACZ;gBACE,OAAO,YAAY,CAAC,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,uBAAuB,CAC7B,KAA+B;QAE/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACI,WAAW,CAChB,KAAa,EACb,mBAA6B,CAAC,MAAM,EAAE,OAAO,CAAC;QAE9C,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;YAClC,IACE,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,EAAE;gBAC7B,SAAS,EAAE,gBAAgB;gBAC3B,gBAAgB,EAAE,IAAI;gBACtB,YAAY,EAAE,IAAI;aACnB,CAAC,EACF,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;YACzE,CAAC;YACD,MAAM,eAAe,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;YACnD,IACE,eAAe,CAAC,UAAU,CAAC,aAAa,CAAC;gBACzC,eAAe,CAAC,UAAU,CAAC,OAAO,CAAC;gBACnC,eAAe,CAAC,UAAU,CAAC,WAAW,CAAC,EACvC,CAAC;gBACD,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;YACJ,CAAC;YACD,OAAO,YAAY,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,KAAK,YAAY,KAAK;gBACpB,CAAC,CAAC,KAAK,CAAC,OAAO;gBACf,CAAC,CAAC,iCAAiC,EACrC,EAAE,KAAK,EAAE,CACV,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACI,YAAY,CACjB,KAAa,EACb,UAA+B,EAAE;QAEjC,MAAM,aAAa,GAAG,KAAK,CAAC;QAC5B,MAAM,gBAAgB,GAAwB;YAC5C,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;YACjC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,KAAK;YAC7C,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;SACrE,CAAC;QAEF,IAAI,oBAAoB,GAAG,KAAK,CAAC;QAEjC,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;gBACrC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;YACrE,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;YAEnE,IAAI,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACvC,oBAAoB,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;YAEnD,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;gBAC7B,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC9C,CAAC;YAED,IAAI,kBAA0B,CAAC;YAE/B,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;gBAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBACpE,IACE,CAAC,QAAQ,CAAC,UAAU,CAAC,gBAAgB,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC;oBACzD,QAAQ,KAAK,gBAAgB,CAAC,OAAO,EACrC,CAAC;oBACD,MAAM,IAAI,KAAK,CACb,yEAAyE,CAC1E,CAAC;gBACJ,CAAC;gBACD,kBAAkB,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;gBACvE,kBAAkB;oBAChB,kBAAkB,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC;gBACvD,IACE,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC;oBACnC,CAAC,gBAAgB,CAAC,aAAa,EAC/B,CAAC;oBACD,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;oBAChC,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,CAAC;wBACpC,MAAM,IAAI,KAAK,CACb,mDAAmD,CACpD,CAAC;oBACJ,CAAC;yBAAM,CAAC;wBACN,kBAAkB,GAAG,UAAU,CAAC;oBAClC,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;oBACpD,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC5C,IACE,CAAC,kBAAkB,CAAC,UAAU,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC;wBAC5D,kBAAkB,KAAK,iBAAiB,EACxC,CAAC;wBACD,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;oBACJ,CAAC;oBACD,kBAAkB,GAAG,UAAU,CAAC;gBAClC,CAAC;YACH,CAAC;YAED,OAAO;gBACL,aAAa,EAAE,kBAAkB;gBACjC,aAAa;gBACb,WAAW,EAAE,oBAAoB;gBACjC,mBAAmB,EACjB,oBAAoB;oBACpB,CAAC,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC;oBACpC,CAAC,gBAAgB,CAAC,aAAa;gBACjC,WAAW,EAAE,gBAAgB;aAC9B,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,OAAO,CACZ,qBAAqB,CAAC,oBAAoB,CAAC;gBACzC,SAAS,EAAE,iCAAiC;gBAC5C,iBAAiB,EAAE,aAAa;gBAChC,eAAe,EAAE,gBAAgB;gBACjC,YAAY,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aACrE,CAAC,EACF,yBAAyB,CAC1B,CAAC;YACF,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,KAAK,YAAY,KAAK;gBACpB,CAAC,CAAC,KAAK,CAAC,OAAO;gBACf,CAAC,CAAC,kCAAkC,EACtC,EAAE,KAAK,EAAE,aAAa,EAAE,CACzB,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACI,YAAY,CAAc,KAAa,EAAE,OAAgB;QAC9D,IAAI,CAAC;YACH,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAC3B,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC5D,IAAI,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,EAAE,CAAC;gBACxE,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,+CAA+C,OAAO,SAAS,EAC/D,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAC1D,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAM,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,QAAQ;gBAAE,MAAM,KAAK,CAAC;YAC3C,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,EAC/D;gBACE,YAAY,EACV,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK;aAC/D,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACI,cAAc,CACnB,KAAsB,EACtB,GAAY,EACZ,GAAY;QAEZ,IAAI,KAAa,CAAC;QAClB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;YAClC,IAAI,YAAY,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC9D,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,uDAAuD,EACvD,EAAE,KAAK,EAAE,CACV,CAAC;YACJ,CAAC;YACD,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,gDAAgD,EAChD,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CACzB,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,yCAAyC,EACzC,EAAE,KAAK,EAAE,CACV,CAAC;QACJ,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,mBAAmB,GAAG,KAAK,CAAC;QAClC,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;YACrC,KAAK,GAAG,GAAG,CAAC;YACZ,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;YACrC,KAAK,GAAG,GAAG,CAAC;YACZ,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,KAAK,CACV,qBAAqB,CAAC,oBAAoB,CAAC;gBACzC,SAAS,EAAE,qCAAqC;gBAChD,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC;gBAC5B,WAAW,EAAE,mBAAmB;gBAChC,QAAQ,EAAE,GAAG;gBACb,QAAQ,EAAE,GAAG;gBACb,YAAY,EAAE,KAAK;aACpB,CAAC,EACF,0BAA0B,CAC3B,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACI,kBAAkB,CAAC,KAAc;QACtC,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAC;YAEtD,MAAM,WAAW,GACf,OAAO,UAAU,CAAC,eAAe,KAAK,UAAU;gBAC9C,CAAC,CAAC,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC;gBACnC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;YACxC,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;YACxC,OAAO,WAAW,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CACV,qBAAqB,CAAC,oBAAoB,CAAC;gBACzC,SAAS,EAAE,uCAAuC;gBAClD,YAAY,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aACrE,CAAC,EACF,uDAAuD,CACxD,CAAC;YACF,OAAO,2BAA2B,CAAC;QACrC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,qBAAqB,CAAC,GAAY;QACxC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO;QAE5C,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;YACxD,OAAO;QACT,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;YACtB,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;gBACnD,MAAM,KAAK,GAAI,GAA+B,CAAC,GAAG,CAAC,CAAC;gBAEpD,4DAA4D;gBAC5D,MAAM,QAAQ,GAAG,GAAG;qBACjB,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,qCAAqC;qBAChE,WAAW,EAAE;qBACb,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,wCAAwC;gBAE7D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CACzC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CACpC,CAAC;gBAEF,IAAI,WAAW,EAAE,CAAC;oBACf,GAA+B,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;gBACvD,CAAC;qBAAM,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9C,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,KAAc,EAAW,EAAE,CACjE,YAAY,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC"}

package/dist/utils/telemetry/instrumentation.d.ts

@@ -0,0 +1,8 @@
+import { NodeSDK } from "@opentelemetry/sdk-node";
+export declare let sdk: NodeSDK | null;
+/**
+ * Gracefully shuts down the OpenTelemetry SDK.
+ * This function is called during the application's shutdown sequence.
+ */
+export declare function shutdownOpenTelemetry(): Promise<void>;
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/utils/telemetry/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/instrumentation.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAYlD,eAAO,IAAI,GAAG,EAAE,OAAO,GAAG,IAAW,CAAC;AA0GtC;;;GAGG;AACH,wBAAsB,qBAAqB,kBAO1C"}

package/dist/utils/telemetry/instrumentation.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview OpenTelemetry SDK initialization and lifecycle management.
+ * This file MUST be imported before any other module in the application's
+ * entry point (`src/index.ts`) to ensure all modules are correctly instrumented.
+ * It handles both the initialization (startup) and graceful shutdown of the SDK.
+ * @module src/utils/telemetry/instrumentation
+ */
+import { config } from "../../config/index.js";
+import { DiagConsoleLogger, DiagLogLevel, diag } from "@opentelemetry/api";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { BatchSpanProcessor, TraceIdRatioBasedSampler, } from "@opentelemetry/sdk-trace-node";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions/incubating";
+export let sdk = null;
+if (config.openTelemetry.enabled) {
+    // --- Custom Diagnostic Logger for OpenTelemetry ---
+    // This logger uses the standard console to avoid circular dependencies with the main application logger.
+    class OtelDiagnosticLogger extends DiagConsoleLogger {
+    }
+    /**
+     * A custom SpanProcessor that writes ended spans to a log file using Pino.
+     */
+    class FileSpanProcessor {
+        forceFlush() {
+            return Promise.resolve();
+        }
+        onStart(_span) { }
+        onEnd(span) {
+            const loggableSpan = {
+                traceId: span.spanContext().traceId,
+                spanId: span.spanContext().spanId,
+                name: span.name,
+                kind: span.kind,
+                startTime: span.startTime,
+                endTime: span.endTime,
+                duration: span.duration,
+                status: span.status,
+                attributes: span.attributes,
+                events: span.events,
+            };
+            // Dynamically import the logger in a non-blocking way to prevent circular dependencies.
+            import("../internal/logger.js")
+                .then(({ logger }) => {
+                logger.info({ span: loggableSpan }, "Trace Span End");
+            })
+                .catch((err) => {
+                diag.error("Failed to dynamically import logger for OTel span.", err);
+            });
+        }
+        shutdown() {
+            return Promise.resolve();
+        }
+    }
+    try {
+        const otelLogLevel = DiagLogLevel[config.openTelemetry.logLevel] ?? DiagLogLevel.INFO;
+        diag.setLogger(new OtelDiagnosticLogger(), otelLogLevel);
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: config.openTelemetry.serviceName,
+            [ATTR_SERVICE_VERSION]: config.openTelemetry.serviceVersion,
+            "deployment.environment.name": config.environment,
+        });
+        let spanProcessor;
+        if (config.openTelemetry.tracesEndpoint) {
+            diag.info(`Using OTLP exporter for traces, endpoint: ${config.openTelemetry.tracesEndpoint}`);
+            const traceExporter = new OTLPTraceExporter({
+                url: config.openTelemetry.tracesEndpoint,
+            });
+            spanProcessor = new BatchSpanProcessor(traceExporter);
+        }
+        else {
+            diag.info("No OTLP endpoint configured. Using FileSpanProcessor for local trace logging.");
+            spanProcessor = new FileSpanProcessor();
+        }
+        const metricReader = config.openTelemetry.metricsEndpoint
+            ? new PeriodicExportingMetricReader({
+                exporter: new OTLPMetricExporter({
+                    url: config.openTelemetry.metricsEndpoint,
+                }),
+                exportIntervalMillis: 15000,
+            })
+            : undefined;
+        sdk = new NodeSDK({
+            resource,
+            spanProcessors: [spanProcessor],
+            metricReader,
+            sampler: new TraceIdRatioBasedSampler(config.openTelemetry.samplingRatio),
+            instrumentations: [
+                getNodeAutoInstrumentations({
+                    "@opentelemetry/instrumentation-http": {
+                        enabled: true,
+                        ignoreIncomingRequestHook: (req) => req.url === "/healthz",
+                    },
+                    "@opentelemetry/instrumentation-fs": { enabled: false },
+                }),
+            ],
+        });
+        sdk.start();
+        diag.info(`OpenTelemetry initialized for ${config.openTelemetry.serviceName} v${config.openTelemetry.serviceVersion}`);
+    }
+    catch (error) {
+        diag.error("Error initializing OpenTelemetry", error);
+        process.exit(1);
+    }
+}
+/**
+ * Gracefully shuts down the OpenTelemetry SDK.
+ * This function is called during the application's shutdown sequence.
+ */
+export async function shutdownOpenTelemetry() {
+    if (sdk) {
+        await sdk
+            .shutdown()
+            .then(() => diag.info("OpenTelemetry terminated"))
+            .catch((error) => diag.error("Error terminating OpenTelemetry", error));
+    }
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/utils/telemetry/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../../../src/utils/telemetry/instrumentation.ts"],"names":[],"mappings":"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"}

package/dist/utils/telemetry/semconv.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Defines local OpenTelemetry semantic convention constants to ensure
+ * stability and avoid dependency conflicts with different versions of
+ * `@opentelemetry/semantic-conventions`.
+ * @module src/utils/telemetry/semconv
+ */
+/**
+ * The method or function name, or equivalent (usually rightmost part of the code unit's name).
+ */
+export declare const ATTR_CODE_FUNCTION = "code.function";
+/**
+ * The "namespace" within which `code.function` is defined.
+ * Usually the qualified class or module name, etc.
+ */
+export declare const ATTR_CODE_NAMESPACE = "code.namespace";
+//# sourceMappingURL=semconv.d.ts.map

package/dist/utils/telemetry/semconv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semconv.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/semconv.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC"}