@adobe-commerce/aio-toolkit 1.0.13 → 1.0.15

package/dist/index.js

@@ -1321,7 +1321,96 @@ var new_relic_default = NewRelicTelemetry;
 // src/framework/telemetry/index.ts
 var _Telemetry = class _Telemetry {
   /**
-   * Create a logger with standard configuration and automatic metadata injection.
+   * Create a new Telemetry instance
+   *
+   * Initializes the telemetry manager with optional runtime parameters.
+   * Parameters can be set later using setParams() if not provided during construction.
+   *
+   * @param params - Optional runtime parameters containing telemetry configuration
+   *
+   * @example
+   * ```typescript
+   * const telemetry = new Telemetry({
+   *   ENABLE_TELEMETRY: true,
+   *   LOG_LEVEL: 'debug',
+   *   action_type: 'webhook'
+   * });
+   * ```
+   */
+  constructor(params = void 0) {
+    /**
+     * Runtime parameters containing telemetry configuration
+     *
+     * Stores the action parameters including telemetry flags (ENABLE_TELEMETRY),
+     * provider configuration (NEW_RELIC_*), log levels, and request context.
+     *
+     * @private
+     */
+    this.params = void 0;
+    /**
+     * Logger instance
+     *
+     * Stores the logger instance for the telemetry instance.
+     *
+     * @private
+     */
+    this.logger = void 0;
+    this.params = params;
+  }
+  /**
+   * Get the current runtime parameters
+   *
+   * Returns the parameters stored in this telemetry instance, or an empty object
+   * if no parameters have been set. These parameters control telemetry behavior
+   * and provide context for logging and tracing.
+   *
+   * @returns Runtime parameters object (never undefined, returns empty object if not set)
+   *
+   * @example
+   * ```typescript
+   * const currentParams = telemetry.getParams();
+   * if (currentParams.ENABLE_TELEMETRY) {
+   *   // telemetry is enabled
+   * }
+   * ```
+   */
+  getParams() {
+    return this.params || {};
+  }
+  /**
+   * Set or update the runtime parameters
+   *
+   * Updates the parameters used by this telemetry instance. This is typically
+   * called by the initialize() method when the action receives runtime parameters,
+   * but can be used to update configuration at any time.
+   *
+   * @param params - New runtime parameters to store
+   *
+   * @example
+   * ```typescript
+   * telemetry.setParams({
+   *   ENABLE_TELEMETRY: true,
+   *   NEW_RELIC_TELEMETRY: true,
+   *   LOG_LEVEL: 'info'
+   * });
+   * const logger = telemetry.createLogger('my-action');
+   * ```
+   */
+  setParams(params) {
+    this.params = params;
+  }
+  /**
+   * Get the logger instance
+   *
+   * Returns the logger instance for the telemetry instance.
+   *
+   * @returns Logger instance
+   */
+  getLogger() {
+    return this.logger;
+  }
+  /**
+   * Create a logger with standard configuration and automatic metadata injection
    *
    * This method creates a structured logger and wraps it to automatically add
    * contextual metadata to all log calls:
@@ -1333,50 +1422,30 @@ var _Telemetry = class _Telemetry {
    * automatically appear in all logs sent to New Relic if ENABLE_TELEMETRY is true.
    *
    * @param name - Logger name (typically action name)
-   * @param params - Runtime parameters containing LOG_LEVEL, optional ENABLE_TELEMETRY, ENVIRONMENT, action_type, and __ow_headers
    * @returns Configured logger instance with automatic metadata injection
    *
-   * @example Basic string message
-   * ```typescript
-   * const logger = Telemetry.createLogger("my-action", params);
-   * logger.info("Processing started");
-   * // Logs: "Processing started"
-   * ```
-   *
-   * @example JSON object message with automatic metadata
+   * @example
    * ```typescript
-   * const logger = Telemetry.createLogger("my-action", {
-   *   ...params,
-   *   action_type: "webhook",
-   *   __ow_headers: { 'x-adobe-commerce-request-id': 'req-123' }
-   * });
-   * logger.info({
-   *   message: "User action completed",
-   *   user_id: "123"
-   * });
-   * // In New Relic: {
-   * //   message: "User action completed",
-   * //   user_id: "123",
-   * //   "x-adobe-commerce-request-id": "req-123",
-   * //   "action.type": "webhook",
-   * //   environment: "development",
-   * //   ...
-   * // }
+   * const logger = telemetry.createLogger('my-action');
+   * logger.info({ message: 'User action completed', user_id: '123' });
+   * // In New Relic: includes message, user_id, request-id, action.type, environment
    * ```
    */
-  static createLogger(name, params) {
-    const baseLogger = !params.ENABLE_TELEMETRY ? import_aio_sdk.Core.Logger(name, {
-      level: params.LOG_LEVEL || "info"
-    }) : (0, import_aio_lib_telemetry3.getLogger)(name, {
-      level: params.LOG_LEVEL || "info"
+  createLogger(name) {
+    let baseLogger = import_aio_sdk.Core.Logger(name, {
+      level: this.params?.LOG_LEVEL || "info"
     });
+    if (this.params?.ENABLE_TELEMETRY === true) {
+      const helpers = (0, import_aio_lib_telemetry3.getInstrumentationHelpers)();
+      baseLogger = helpers.logger;
+    }
     const metadata = {};
-    const headers = params.__ow_headers;
+    const headers = this.params?.__ow_headers;
     const requestId = headers?.["x-adobe-commerce-request-id"];
     if (requestId && requestId !== "") {
       metadata["x-adobe-commerce-request-id"] = requestId;
     }
-    const actionType = params.action_type;
+    const actionType = this.params?.action_type;
     if (actionType && actionType !== "") {
       metadata["action.type"] = actionType;
     }
@@ -1413,10 +1482,11 @@ var _Telemetry = class _Telemetry {
         }
       }, "error")
     };
-    return {
+    this.logger = {
       ...baseLogger,
       ...wrapper
     };
+    return this.logger;
   }
   /**
    * Extract structured error information for logging
@@ -1430,13 +1500,13 @@ var _Telemetry = class _Telemetry {
    * @example
    * ```typescript
    * try {
-   *   // some operation
+   *   await processOrder(orderId);
    * } catch (error) {
-   *   logger.error("Operation failed", Telemetry.formatError(error));
+   *   logger.error({ message: 'Operation failed', ...telemetry.formatError(error) });
    * }
    * ```
    */
-  static formatError(error) {
+  formatError(error) {
     if (error instanceof Error) {
       return {
         error_name: error.name,
@@ -1446,6 +1516,77 @@ var _Telemetry = class _Telemetry {
     }
     return { error: String(error) };
   }
+  /**
+   * Get the current OpenTelemetry span for adding attributes and events
+   *
+   * This method provides access to the currently active span, allowing you to
+   * add custom attributes and events for enhanced observability in New Relic.
+   *
+   * **IMPORTANT**: This must be called within an active trace context
+   * (i.e., inside a function that has been wrapped by Telemetry.initialize()).
+   * If called outside an active context or if ENABLE_TELEMETRY is false, it returns null.
+   *
+   * @returns The current span object, or null if no active span exists
+   *
+   * @example
+   * ```typescript
+   * const processOrder = async (orderId: string) => {
+   *   const span = telemetry.getCurrentSpan();
+   *   if (span) {
+   *     span.setAttribute('order.id', orderId);
+   *     span.setAttribute('order.status', 'processing');
+   *     span.addEvent('processing-started');
+   *   }
+   *   // ... process order logic ...
+   * };
+   * ```
+   */
+  getCurrentSpan() {
+    if (this.params?.ENABLE_TELEMETRY === true) {
+      const helpers = (0, import_aio_lib_telemetry3.getInstrumentationHelpers)();
+      return helpers?.currentSpan || null;
+    }
+    return null;
+  }
+  /**
+   * Instrument a function with OpenTelemetry for distributed tracing
+   *
+   * This method wraps any function with OpenTelemetry instrumentation,
+   * creating a child span in the current trace context. Use this to create
+   * detailed spans for specific operations within your action.
+   *
+   * **IMPORTANT**: The instrumented function must be called within an active trace context
+   * (i.e., inside a function that has been wrapped by Telemetry.initialize()).
+   * If called outside an active context, the span will not be created or exported.
+   *
+   * @param spanName - Name for the span (appears in New Relic as the span name)
+   * @param fn - The function to instrument (sync or async)
+   * @returns The instrumented function that creates a child span when called
+   *
+   * @example
+   * ```typescript
+   * const fetchUserData = telemetry.instrument(
+   *   'fetch-user-data',
+   *   async (userId: string) => {
+   *     const span = telemetry.getCurrentSpan();
+   *     if (span) {
+   *       span.setAttribute('user.id', userId);
+   *       span.addEvent('fetching-started');
+   *     }
+   *     const response = await fetch(`/api/users/${userId}`);
+   *     return response.json();
+   *   }
+   * );
+   * const userData = await fetchUserData('123');
+   * ```
+   */
+  instrument(spanName, fn) {
+    return (0, import_aio_lib_telemetry3.instrument)(fn, {
+      spanConfig: {
+        spanName
+      }
+    });
+  }
   /**
    * Initialize telemetry for a runtime action with provider fallback chain
    *
@@ -1463,60 +1604,20 @@ var _Telemetry = class _Telemetry {
    * is returned to alert you of the misconfiguration. This prevents silently running
    * without telemetry when you expect it to be working.
    *
-   * Environment Configuration:
-   * Pass params.ENVIRONMENT to set the environment field in all logs.
-   * This can be set via environment variables in your action configuration.
-   *
    * @param action - The runtime action function to instrument
    * @returns The instrumented action ready for export
    *
-   * @example Single provider (New Relic) - Valid configuration
-   * ```typescript
-   * // Environment:
-   * // ENABLE_TELEMETRY=true
-   * // NEW_RELIC_TELEMETRY=true
-   * // NEW_RELIC_SERVICE_NAME=my-service
-   * // NEW_RELIC_LICENSE_KEY=xxxxx
-   *
-   * export const main = Telemetry.initialize(myAction);
-   * // ✅ Uses New Relic telemetry
-   * ```
-   *
-   * @example New Relic enabled but misconfigured - Returns error response
-   * ```typescript
-   * // Environment:
-   * // ENABLE_TELEMETRY=true
-   * // NEW_RELIC_TELEMETRY=true
-   * // NEW_RELIC_SERVICE_NAME=my-service
-   * // Missing NEW_RELIC_LICENSE_KEY!
-   *
-   * export const main = Telemetry.initialize(myAction);
-   * // ❌ Returns { error: { statusCode: 500, body: { error: "Telemetry configuration error: NEW_RELIC_LICENSE_KEY is required" } } }
-   * // This is intentional - you want to know your telemetry config is broken!
-   * ```
-   *
-   * @example Multi-provider fallback
-   * ```typescript
-   * // Environment:
-   * // ENABLE_TELEMETRY=true
-   * // NEW_RELIC_TELEMETRY=false  // Skip New Relic
-   * // GRAFANA_TELEMETRY=true      // Use Grafana instead
-   *
-   * export const main = Telemetry.initialize(myAction);
-   * // ✅ Skips New Relic, tries Grafana (when implemented)
-   * ```
-   *
-   * @example No telemetry
+   * @example
    * ```typescript
-   * // Environment:
-   * // ENABLE_TELEMETRY=false (or not set)
-   *
-   * export const main = Telemetry.initialize(myAction);
-   * // ✅ Returns original action without instrumentation
+   * const telemetry = new Telemetry();
+   * export const main = telemetry.initialize(myAction);
+   * // Environment: ENABLE_TELEMETRY=true, NEW_RELIC_TELEMETRY=true
+   * // Result: Uses New Relic telemetry with full distributed tracing
    * ```
    */
-  static initialize(action) {
+  initialize(action) {
     return async (params) => {
+      this.setParams(params);
       const newRelicTelemetry = new new_relic_default();
       if (newRelicTelemetry.canInitialize(params)) {
         try {
@@ -1591,7 +1692,7 @@ var _RuntimeAction = class _RuntimeAction {
    * @param requiredHeaders - Required header names (case-insensitive)
    * @param action - User-defined action function that receives:
    *   - params: All request parameters including __ow_* runtime parameters
-   *   - ctx: Context object with logger and headers
+   *   - ctx: Context object with logger, headers, and telemetry
    * @returns Wrapped action function ready to be exported as Adobe I/O Runtime entrypoint
    *
    * @example With All Options
@@ -1601,10 +1702,16 @@ var _RuntimeAction = class _RuntimeAction {
    *   [HttpMethod.POST],
    *   ['orderId', 'customerId'],
    *   ['authorization', 'x-api-key'],
-   *   async (params, { logger, headers }) => {
+   *   async (params, { logger, headers, telemetry }) => {
    *     const { orderId, customerId } = params;
    *     logger.info({ message: 'Processing order', orderId, customerId });
    *
+   *     // Access current span for custom instrumentation
+   *     const span = telemetry.getCurrentSpan();
+   *     if (span) {
+   *       span.setAttribute('order.id', orderId);
+   *     }
+   *
    *     // Your business logic here
    *     const result = await processOrderLogic(orderId, customerId);
    *
@@ -1627,11 +1734,13 @@ var _RuntimeAction = class _RuntimeAction {
   static execute(name = "main", httpMethods = [], requiredParams = [], requiredHeaders = [], action = async (_params) => {
     return { statusCode: 200 /* OK */, body: {} };
   }) {
+    const telemetry = new telemetry_default();
     const runtimeAction = /* @__PURE__ */ __name(async (params) => {
       if (!params.action_type) {
         params.action_type = _RuntimeAction.getActionType();
       }
-      const logger = telemetry_default.createLogger(name, params);
+      telemetry.setParams(params);
+      const logger = telemetry.createLogger(name);
       try {
         logger.debug({
           message: `${_RuntimeAction.getActionTypeName()} execution started`
@@ -1648,18 +1757,26 @@ var _RuntimeAction = class _RuntimeAction {
             body: params.__ow_body || {}
           })
         );
-        const validationError = _RuntimeAction.validateRequest(
+        const validationError = _RuntimeAction.validateRequestWithInstrumentation(
+          name,
           params,
           requiredParams,
           requiredHeaders,
           httpMethods,
-          logger,
-          name
+          telemetry,
+          logger
         );
         if (validationError) {
           return validationError;
         }
-        const result = await action(params, { logger, headers: params.__ow_headers || {} });
+        const result = await _RuntimeAction.executeActionWithInstrumentation(
+          name,
+          params.__ow_headers || {},
+          params,
+          action,
+          telemetry,
+          logger
+        );
         logger.debug(
           JSON.stringify({
             message: `${_RuntimeAction.getActionTypeName()} execution completed`,
@@ -1683,7 +1800,108 @@ var _RuntimeAction = class _RuntimeAction {
         return response_default.error(500 /* INTERNAL_ERROR */, "server error");
       }
     }, "runtimeAction");
-    return telemetry_default.initialize(runtimeAction);
+    return telemetry.initialize(runtimeAction);
+  }
+  /**
+   * Executes user's action with OpenTelemetry instrumentation
+   *
+   * This method wraps the action execution with distributed tracing instrumentation,
+   * creating a span that tracks execution metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param headers - Request headers
+   * @param params - Request parameters
+   * @param action - The user's action function to execute
+   * @param telemetry - Telemetry instance for instrumentation
+   * @param logger - Logger instance
+   * @returns Promise resolving to the action result
+   *
+   * @private
+   */
+  static async executeActionWithInstrumentation(name, headers, params, action, telemetry, logger) {
+    const instrumentedAction = telemetry.instrument(
+      `runtime.action.${name}.execute`,
+      async (actionName, actionHeaders, actionParams, actionFn, actionTelemetry, actionLogger) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("action.name", actionName);
+          span.setAttribute("action.type", actionParams.action_type || "unknown");
+          span.setAttribute("action.has_headers", !!actionHeaders);
+          span.addEvent("action-execution-started");
+        }
+        const result = await actionFn(actionParams, {
+          logger: actionLogger,
+          headers: actionHeaders,
+          telemetry: actionTelemetry
+        });
+        if (span) {
+          const statusCode = "statusCode" in result ? result.statusCode : result.error.statusCode;
+          span.setAttribute("action.response_status", statusCode);
+          span.setAttribute("action.has_error", "error" in result);
+          span.addEvent("action-execution-completed", {
+            statusCode
+          });
+        }
+        return result;
+      }
+    );
+    return instrumentedAction(name, headers, params, action, telemetry, logger);
+  }
+  /**
+   * Validates incoming request with OpenTelemetry instrumentation
+   *
+   * This method wraps the validation logic with distributed tracing instrumentation,
+   * creating a span that tracks validation metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param params - Request parameters including __ow_* runtime parameters
+   * @param requiredParams - List of required parameter names to validate
+   * @param requiredHeaders - List of required header names to validate (case-insensitive)
+   * @param httpMethods - Allowed HTTP methods. Empty array skips HTTP method validation
+   * @param telemetry - Telemetry instance for instrumentation
+   * @param logger - Logger instance for error logging
+   * @returns RuntimeActionResponseType with error details if validation fails, null if valid
+   *
+   * @private
+   */
+  static validateRequestWithInstrumentation(name, params, requiredParams, requiredHeaders, httpMethods, telemetry, logger) {
+    const instrumentedValidate = telemetry.instrument(
+      `runtime.action.${name}.validate`,
+      (actionName, actionParams, actionRequiredParams, actionRequiredHeaders, actionHttpMethods, actionTelemetry, actionLogger) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("validation.required_params", actionRequiredParams.join(","));
+          span.setAttribute("validation.required_headers", actionRequiredHeaders.join(","));
+          span.setAttribute("validation.allowed_methods", actionHttpMethods.join(","));
+          span.setAttribute("validation.request_method", actionParams.__ow_method || "unknown");
+        }
+        const validationResult = _RuntimeAction.validateRequest(
+          actionName,
+          actionParams,
+          actionRequiredParams,
+          actionRequiredHeaders,
+          actionHttpMethods,
+          actionLogger
+        );
+        if (span) {
+          span.setAttribute("validation.passed", validationResult === null);
+          if (validationResult) {
+            const statusCode = "statusCode" in validationResult ? validationResult.statusCode : validationResult.error.statusCode;
+            span.setAttribute("validation.error_code", statusCode);
+          }
+        }
+        return validationResult;
+      }
+    );
+    return instrumentedValidate(
+      name,
+      params,
+      requiredParams,
+      requiredHeaders,
+      httpMethods,
+      telemetry,
+      logger
+    );
   }
   /**
    * Validates incoming request against required parameters, headers, and HTTP methods
@@ -1693,12 +1911,12 @@ var _RuntimeAction = class _RuntimeAction {
    * 2. Checks for missing required headers (case-insensitive)
    * 3. Validates the HTTP method against allowed methods list
    *
+   * @param _name - Action name for logging (currently unused)
    * @param params - Request parameters including __ow_* runtime parameters
    * @param requiredParams - List of required parameter names to validate
    * @param requiredHeaders - List of required header names to validate (case-insensitive)
    * @param httpMethods - Allowed HTTP methods. Empty array skips HTTP method validation
    * @param logger - Logger instance for error logging (child logger with request ID if present)
-   * @param name - Action name for logging
    * @returns RuntimeActionResponseType with error details if validation fails, null if valid
    *
    * @private
@@ -1718,7 +1936,7 @@ var _RuntimeAction = class _RuntimeAction {
    * }
    * ```
    */
-  static validateRequest(params, requiredParams, requiredHeaders, httpMethods, logger, _name) {
+  static validateRequest(_name, params, requiredParams, requiredHeaders, httpMethods, logger) {
     const errorMessage = validator_default.checkMissingRequestInputs(params, requiredParams, requiredHeaders) ?? "";
     if (errorMessage) {
       logger.error({
@@ -1798,11 +2016,15 @@ var _EventConsumerAction = class _EventConsumerAction {
    *   'webhook-processor',
    *   ['eventType', 'eventData'],
    *   ['x-webhook-signature'],
-   *   async (params, { logger, headers }) => {
+   *   async (params, { logger, headers, telemetry }) => {
    *     logger.info({
    *       message: 'Processing webhook',
    *       eventType: params.eventType
    *     });
+   *     const span = telemetry.getCurrentSpan();
+   *     if (span) {
+   *       span.setAttribute('event.type', params.eventType);
+   *     }
    *     // Process event...
    *     return { statusCode: 200, body: { processed: true } };
    *   }
@@ -1812,9 +2034,10 @@ var _EventConsumerAction = class _EventConsumerAction {
   static execute(name = "main", requiredParams = [], requiredHeaders = [], action = async (_params) => {
     return { statusCode: 200 /* OK */, body: {} };
   }) {
+    const telemetry = new telemetry_default();
     const eventConsumerAction = /* @__PURE__ */ __name(async (params) => {
       params.action_type = "event-consumer-action";
-      const logger = telemetry_default.createLogger(name, params);
+      const logger = telemetry.createLogger(name);
       try {
         logger.debug({
           message: "Event consumer action execution started"
@@ -1827,7 +2050,13 @@ var _EventConsumerAction = class _EventConsumerAction {
           message: "Event consumer action parameters received",
           parameters: params
         });
-        const errorMessage = validator_default.checkMissingRequestInputs(params, requiredParams, requiredHeaders) || "";
+        const errorMessage = _EventConsumerAction.validateWithInstrumentation(
+          name,
+          params,
+          requiredParams,
+          requiredHeaders,
+          telemetry
+        );
         if (errorMessage) {
           logger.error({
             message: "Event consumer action validation failed",
@@ -1835,7 +2064,14 @@ var _EventConsumerAction = class _EventConsumerAction {
           });
           return response_default.error(400 /* BAD_REQUEST */, errorMessage);
         }
-        const result = await action(params, { logger, headers: params.__ow_headers || {} });
+        const result = await _EventConsumerAction.executeActionWithInstrumentation(
+          name,
+          params.__ow_headers || {},
+          params,
+          action,
+          telemetry,
+          logger
+        );
         logger.debug({
           message: "Event consumer action execution completed",
           result
@@ -1844,16 +2080,109 @@ var _EventConsumerAction = class _EventConsumerAction {
       } catch (error) {
         if (error instanceof Error) {
           logger.error({
+            message: "Event consumer action execution failed",
             error: error.message,
             stack: error.stack
           });
         } else {
-          logger.error({ error });
+          logger.error({
+            message: "Event consumer action execution failed",
+            error
+          });
         }
         return response_default.error(500 /* INTERNAL_ERROR */, "server error");
       }
     }, "eventConsumerAction");
-    return telemetry_default.initialize(eventConsumerAction);
+    return telemetry.initialize(eventConsumerAction);
+  }
+  /**
+   * Validates event consumer request with OpenTelemetry instrumentation
+   *
+   * This method wraps the validation logic with distributed tracing instrumentation,
+   * creating a span that tracks validation metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param params - Request parameters
+   * @param requiredParams - List of required parameter names to validate
+   * @param requiredHeaders - List of required header names to validate
+   * @returns Error message if validation fails, empty string if successful
+   *
+   * @private
+   */
+  static validateWithInstrumentation(name, params, requiredParams, requiredHeaders, telemetry) {
+    const instrumentedValidate = telemetry.instrument(
+      `event.consumer.action.${name}.validate`,
+      (actionName, actionParams, actionRequiredParams, actionRequiredHeaders, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute(
+            "event.consumer.validation.required_params",
+            actionRequiredParams.join(",")
+          );
+          span.setAttribute(
+            "event.consumer.validation.required_headers",
+            actionRequiredHeaders.join(",")
+          );
+        }
+        const errorMessage = validator_default.checkMissingRequestInputs(
+          actionParams,
+          actionRequiredParams,
+          actionRequiredHeaders
+        ) || "";
+        if (span) {
+          span.setAttribute("event.consumer.validation.passed", errorMessage === "");
+          if (errorMessage) {
+            span.setAttribute("event.consumer.validation.error", errorMessage);
+          }
+        }
+        return errorMessage;
+      }
+    );
+    return instrumentedValidate(name, params, requiredParams, requiredHeaders, telemetry);
+  }
+  /**
+   * Executes event consumer action with OpenTelemetry instrumentation
+   *
+   * This method wraps the action execution with distributed tracing instrumentation,
+   * creating a span that tracks execution metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param headers - Request headers
+   * @param params - Request parameters
+   * @param action - The user's action function to execute
+   * @param telemetry - Telemetry instance for instrumentation
+   * @param logger - Logger instance
+   * @returns Promise resolving to the action result
+   *
+   * @private
+   */
+  static async executeActionWithInstrumentation(name, headers, params, action, telemetry, logger) {
+    const instrumentedAction = telemetry.instrument(
+      `event.consumer.action.${name}.execute`,
+      async (actionName, actionHeaders, actionParams, actionFn, actionTelemetry, actionLogger) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("event.consumer.action.name", actionName);
+          span.setAttribute("event.consumer.action.has_headers", !!actionHeaders);
+          span.addEvent("event-consumer-execution-started");
+        }
+        const result = await actionFn(actionParams, {
+          logger: actionLogger,
+          headers: actionHeaders,
+          telemetry: actionTelemetry
+        });
+        if (span) {
+          const statusCode = "statusCode" in result ? result.statusCode : result.error.statusCode;
+          span.setAttribute("event.consumer.action.response_status", statusCode);
+          span.setAttribute("event.consumer.action.has_error", "error" in result);
+          span.addEvent("event-consumer-execution-completed", {
+            statusCode
+          });
+        }
+        return result;
+      }
+    );
+    return instrumentedAction(name, headers, params, action, telemetry, logger);
   }
 };
 __name(_EventConsumerAction, "EventConsumerAction");
@@ -1863,6 +2192,116 @@ var event_consumer_action_default = EventConsumerAction;
 // src/framework/graphql-action/index.ts
 var import_graphql = require("graphql");
 var _GraphQlAction = class _GraphQlAction {
+  /**
+   * Creates a GraphQL action handler with schema validation and telemetry
+   *
+   * This method wraps a GraphQL API with standardized runtime functionality:
+   * 1. Builds and validates the GraphQL schema
+   * 2. Parses incoming GraphQL queries
+   * 3. Validates queries against the schema
+   * 4. Optionally blocks introspection queries for security
+   * 5. Executes queries with provided resolvers
+   * 6. Integrates with OpenTelemetry for distributed tracing
+   * 7. Provides structured logging with request ID correlation
+   *
+   * All operations are instrumented with OpenTelemetry spans for observability in New Relic.
+   *
+   * @param schema - GraphQL schema definition string (SDL format)
+   * @param resolvers - Function that returns resolver map with access to logger, headers, and params
+   * @param name - Action name for logging and telemetry spans (default: 'main')
+   * @param disableIntrospection - If true, blocks introspection queries (__schema, __type) for security (default: false)
+   * @returns Wrapped action function ready to be exported as Adobe I/O Runtime entrypoint
+   *
+   * @example Complete GraphQL API with authentication
+   * ```typescript
+   * const schema = `
+   *   type Query {
+   *     me: User
+   *     orders: [Order]
+   *   }
+   *
+   *   type User {
+   *     id: ID!
+   *     email: String!
+   *     name: String!
+   *   }
+   *
+   *   type Order {
+   *     id: ID!
+   *     total: Float!
+   *     items: [OrderItem]
+   *   }
+   *
+   *   type OrderItem {
+   *     productId: ID!
+   *     quantity: Int!
+   *     price: Float!
+   *   }
+   * `;
+   *
+   * const resolvers = async ({ logger, headers, params, telemetry }) => {
+   *   // Access authentication from headers
+   *   const userId = headers['x-user-id'];
+   *
+   *   return {
+   *     me: async () => {
+   *       logger.info({ message: 'Fetching current user', userId });
+   *       const span = telemetry.getCurrentSpan();
+   *       if (span) {
+   *         span.setAttribute('user.id', userId);
+   *       }
+   *       return getUserById(userId);
+   *     },
+   *     orders: async () => {
+   *       logger.info({ message: 'Fetching user orders', userId });
+   *       return getOrdersByUserId(userId);
+   *     }
+   *   };
+   * };
+   *
+   * // Disable introspection in production for security
+   * const handler = GraphQlAction.execute(
+   *   schema,
+   *   resolvers,
+   *   'customer-api',
+   *   process.env.NODE_ENV === 'production'
+   * );
+   *
+   * export const main = handler;
+   * ```
+   *
+   * @example GraphQL action with variables and operation names
+   * ```typescript
+   * // Client sends:
+   * // POST /api/graphql
+   * // {
+   * //   "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
+   * //   "variables": { "id": "123" },
+   * //   "operationName": "GetUser"
+   * // }
+   *
+   * const schema = `
+   *   type Query {
+   *     user(id: ID!): User
+   *   }
+   *   type User {
+   *     id: ID!
+   *     name: String!
+   *     email: String!
+   *   }
+   * `;
+   *
+   * const resolvers = async ({ logger, headers, params, telemetry }) => ({
+   *   user: async ({ id }) => {
+   *     logger.info({ message: 'Query executed', operationName: 'GetUser', userId: id });
+   *     return { id, name: 'John Doe', email: 'john@example.com' };
+   *   }
+   * });
+   *
+   * const handler = GraphQlAction.execute(schema, resolvers, 'graphql-api');
+   * export const main = handler;
+   * ```
+   */
   static execute(schema = `
       type Query {
         hello: String
@@ -1872,15 +2311,11 @@ var _GraphQlAction = class _GraphQlAction {
       hello: /* @__PURE__ */ __name(() => "Hello World!", "hello")
     };
   }, name = "main", disableIntrospection = false) {
-    runtime_action_default.setActionType("graphql-action");
-    runtime_action_default.setActionTypeName("GraphQL action");
     const callback = /* @__PURE__ */ __name(async (params, ctx) => {
-      const { logger } = ctx;
-      let graphqlSchema;
-      try {
-        graphqlSchema = (0, import_graphql.buildSchema)(schema);
-      } catch (error) {
-        return response_default.error(400 /* BAD_REQUEST */, error.message);
+      const { logger, telemetry } = ctx;
+      const { schema: graphqlSchema, error: schemaError } = _GraphQlAction.buildSchemaWithInstrumentation(name, schema, telemetry);
+      if (schemaError) {
+        return response_default.error(400 /* BAD_REQUEST */, schemaError);
       }
       const graphqlResolvers = await resolvers({
         ...ctx,
@@ -1890,11 +2325,9 @@ var _GraphQlAction = class _GraphQlAction {
       });
       const context2 = {};
       const query = params.query;
-      let parsedQuery;
-      try {
-        parsedQuery = (0, import_graphql.parse)(query);
-      } catch (error) {
-        return response_default.error(400 /* BAD_REQUEST */, error.message);
+      const { parsed: parsedQuery, error: parseError } = _GraphQlAction.parseQueryWithInstrumentation(name, query, telemetry);
+      if (parseError) {
+        return response_default.error(400 /* BAD_REQUEST */, parseError);
       }
       logger.debug(
         JSON.stringify({
@@ -1902,7 +2335,12 @@ var _GraphQlAction = class _GraphQlAction {
           query: parsedQuery
         })
       );
-      const validationErrors = (0, import_graphql.validate)(graphqlSchema, parsedQuery);
+      const validationErrors = _GraphQlAction.validateQueryWithInstrumentation(
+        name,
+        graphqlSchema,
+        parsedQuery,
+        telemetry
+      );
       if (validationErrors.length) {
         logger.error({
           message: "GraphQL action query validation failed",
@@ -1917,10 +2355,10 @@ var _GraphQlAction = class _GraphQlAction {
         logger.debug({
           message: "GraphQL action introspection check disabled"
         });
-        const isIntrospectionQuery = parsedQuery.definitions.some(
-          (definition) => definition.selectionSet.selections.some(
-            (selection) => selection.name.value.startsWith("__")
-          )
+        const isIntrospectionQuery = _GraphQlAction.checkIntrospectionWithInstrumentation(
+          name,
+          parsedQuery,
+          telemetry
         );
         if (isIntrospectionQuery) {
           logger.error({
@@ -1939,24 +2377,240 @@ var _GraphQlAction = class _GraphQlAction {
         variables
       });
       return response_default.success(
-        await (0, import_graphql.graphql)({
-          schema: graphqlSchema,
-          source: query,
-          rootValue: graphqlResolvers,
-          contextValue: context2,
-          variableValues: variables,
-          operationName: params.operationName
-        })
+        await _GraphQlAction.executeGraphQLWithInstrumentation(
+          name,
+          {
+            schema: graphqlSchema,
+            source: query,
+            rootValue: graphqlResolvers,
+            contextValue: context2,
+            variableValues: variables,
+            operationName: params.operationName
+          },
+          telemetry
+        )
       );
     }, "callback");
-    const graphqlAction = runtime_action_default.execute(
+    runtime_action_default.setActionType("graphql-action");
+    runtime_action_default.setActionTypeName("GraphQL action");
+    return runtime_action_default.execute(
       `graphql-${name}`,
       ["GET" /* GET */, "POST" /* POST */],
       ["query"],
       [],
       callback
     );
-    return telemetry_default.initialize(graphqlAction);
+  }
+  /**
+   * Builds GraphQL schema with OpenTelemetry instrumentation
+   *
+   * This method wraps the schema building logic with distributed tracing instrumentation,
+   * creating a span that tracks schema metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param schemaString - GraphQL schema definition string
+   * @param params - Request parameters for telemetry context
+   * @returns Object with built schema or error message
+   *
+   * @private
+   */
+  static buildSchemaWithInstrumentation(name, schemaString, telemetry) {
+    const instrumentedBuildSchema = telemetry.instrument(
+      `graphql.action.${name}.build-schema`,
+      (actionName, actionSchemaString, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("graphql.schema.length", actionSchemaString.length);
+          span.addEvent("schema-building-started");
+        }
+        try {
+          const builtSchema = (0, import_graphql.buildSchema)(actionSchemaString);
+          if (span) {
+            span.setAttribute("graphql.schema.built", true);
+            span.addEvent("schema-building-completed");
+          }
+          return { schema: builtSchema, error: null };
+        } catch (error) {
+          if (span) {
+            span.setAttribute("graphql.schema.built", false);
+            span.setAttribute("graphql.schema.error", error.message);
+          }
+          return { schema: null, error: error.message };
+        }
+      }
+    );
+    return instrumentedBuildSchema(name, schemaString, telemetry);
+  }
+  /**
+   * Parses GraphQL query with OpenTelemetry instrumentation
+   *
+   * This method wraps the query parsing logic with distributed tracing instrumentation,
+   * creating a span that tracks parsing metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param queryString - GraphQL query string to parse
+   * @param params - Request parameters for telemetry context
+   * @returns Object with parsed query document or error message
+   *
+   * @private
+   */
+  static parseQueryWithInstrumentation(name, queryString, telemetry) {
+    const instrumentedParseQuery = telemetry.instrument(
+      `graphql.action.${name}.parse-query`,
+      (actionName, actionQueryString, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("graphql.query.length", actionQueryString.length);
+          span.addEvent("query-parsing-started");
+        }
+        try {
+          const parsed = (0, import_graphql.parse)(actionQueryString);
+          if (span) {
+            span.setAttribute("graphql.query.parsed", true);
+            span.setAttribute("graphql.query.definitions_count", parsed.definitions.length);
+            span.addEvent("query-parsing-completed");
+          }
+          return { parsed, error: null };
+        } catch (error) {
+          if (span) {
+            span.setAttribute("graphql.query.parsed", false);
+            span.setAttribute("graphql.query.error", error.message);
+          }
+          return { parsed: null, error: error.message };
+        }
+      }
+    );
+    return instrumentedParseQuery(name, queryString, telemetry);
+  }
+  /**
+   * Validates GraphQL query with OpenTelemetry instrumentation
+   *
+   * This method wraps the query validation logic with distributed tracing instrumentation,
+   * creating a span that tracks validation metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param schema - GraphQL schema to validate against
+   * @param parsedQuery - Parsed GraphQL query document
+   * @param params - Request parameters for telemetry context
+   * @returns Array of validation errors (empty if valid)
+   *
+   * @private
+   */
+  static validateQueryWithInstrumentation(name, schema, parsedQuery, telemetry) {
+    const instrumentedValidateQuery = telemetry.instrument(
+      `graphql.action.${name}.validate-query`,
+      (actionName, actionSchema, actionParsedQuery, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.addEvent("query-validation-started");
+        }
+        const errors = (0, import_graphql.validate)(actionSchema, actionParsedQuery);
+        if (span) {
+          span.setAttribute("graphql.query.valid", errors.length === 0);
+          span.setAttribute("graphql.query.validation_errors_count", errors.length);
+          if (errors.length > 0) {
+            span.setAttribute(
+              "graphql.query.validation_errors",
+              errors.map((e) => e.message).join("; ")
+            );
+          }
+          span.addEvent("query-validation-completed", {
+            valid: errors.length === 0,
+            errorCount: errors.length
+          });
+        }
+        return errors;
+      }
+    );
+    return instrumentedValidateQuery(name, schema, parsedQuery, telemetry);
+  }
+  /**
+   * Checks for introspection query with OpenTelemetry instrumentation
+   *
+   * This method wraps the introspection detection logic with distributed tracing instrumentation,
+   * creating a span that tracks whether an introspection query was detected in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param parsedQuery - Parsed GraphQL query document
+   * @param params - Request parameters for telemetry context
+   * @returns True if introspection query detected, false otherwise
+   *
+   * @private
+   */
+  static checkIntrospectionWithInstrumentation(name, parsedQuery, telemetry) {
+    const instrumentedIntrospectionCheck = telemetry.instrument(
+      `graphql.action.${name}.introspection-check`,
+      (actionName, actionParsedQuery, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("graphql.introspection.disabled", true);
+          span.addEvent("introspection-check-started");
+        }
+        const isIntrospection = actionParsedQuery.definitions.some(
+          (definition) => definition.selectionSet.selections.some(
+            (selection) => selection.name.value.startsWith("__")
+          )
+        );
+        if (span) {
+          span.setAttribute("graphql.introspection.detected", isIntrospection);
+          span.addEvent("introspection-check-completed", {
+            detected: isIntrospection
+          });
+        }
+        return isIntrospection;
+      }
+    );
+    return instrumentedIntrospectionCheck(name, parsedQuery, telemetry);
+  }
+  /**
+   * Executes GraphQL query with OpenTelemetry instrumentation
+   *
+   * This method wraps the GraphQL execution with distributed tracing instrumentation,
+   * creating a span that tracks execution metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param executionParams - GraphQL execution parameters (schema, source, rootValue, etc.)
+   * @param params - Request parameters for telemetry context
+   * @returns Promise resolving to the GraphQL execution result
+   *
+   * @private
+   */
+  static async executeGraphQLWithInstrumentation(name, executionParams, telemetry) {
+    const instrumentedGraphQLExecution = telemetry.instrument(
+      `graphql.action.${name}.execute`,
+      async (actionName, actionExecutionParams, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute(
+            "graphql.execution.operation_name",
+            actionExecutionParams.operationName || "default"
+          );
+          span.setAttribute(
+            "graphql.execution.has_variables",
+            !!actionExecutionParams.variableValues
+          );
+          span.addEvent("graphql-execution-started");
+        }
+        const result = await (0, import_graphql.graphql)(actionExecutionParams);
+        if (span) {
+          span.setAttribute("graphql.execution.has_errors", !!result.errors);
+          if (result.errors) {
+            span.setAttribute("graphql.execution.errors_count", result.errors.length);
+            span.setAttribute(
+              "graphql.execution.errors",
+              result.errors.map((e) => e.message).join("; ")
+            );
+          }
+          span.setAttribute("graphql.execution.has_data", !!result.data);
+          span.addEvent("graphql-execution-completed", {
+            hasErrors: !!result.errors,
+            hasData: !!result.data
+          });
+        }
+        return result;
+      }
+    );
+    return instrumentedGraphQLExecution(name, executionParams, telemetry);
   }
 };
 __name(_GraphQlAction, "GraphQlAction");
@@ -2021,9 +2675,15 @@ var _OpenwhiskAction = class _OpenwhiskAction {
    * ```typescript
    * const handler = OpenwhiskAction.execute(
    *   'processWebhook',
-   *   async (params, { logger, headers }) => {
+   *   async (params, { logger, headers, telemetry }) => {
    *     logger.info({ message: 'Webhook received', event: params.event });
    *
+   *     // Access current span for custom instrumentation
+   *     const span = telemetry.getCurrentSpan();
+   *     if (span) {
+   *       span.setAttribute('webhook.event', params.event);
+   *     }
+   *
    *     // Your webhook processing logic here
    *     const result = await processWebhookData(params);
    *
@@ -2038,9 +2698,10 @@ var _OpenwhiskAction = class _OpenwhiskAction {
   static execute(name = "main", action = async (_params) => {
     return { statusCode: 200 /* OK */, body: {} };
   }) {
+    const telemetry = new telemetry_default();
     const openwhiskAction = /* @__PURE__ */ __name(async (params) => {
       params.action_type = "openwhisk-action";
-      const logger = telemetry_default.createLogger(name, params);
+      const logger = telemetry.createLogger(name);
       try {
         logger.debug({
           message: "OpenWhisk action execution started"
@@ -2049,7 +2710,14 @@ var _OpenwhiskAction = class _OpenwhiskAction {
           message: "OpenWhisk action parameters received",
           params
         });
-        const result = await action(params, { logger, headers: params.__ow_headers || {} });
+        const result = await _OpenwhiskAction.executeActionWithInstrumentation(
+          name,
+          params.__ow_headers || {},
+          params,
+          action,
+          telemetry,
+          logger
+        );
         logger.debug({
           message: "OpenWhisk action execution completed",
           result
@@ -2071,7 +2739,51 @@ var _OpenwhiskAction = class _OpenwhiskAction {
         return response_default.error(500 /* INTERNAL_ERROR */, "server error");
       }
     }, "openwhiskAction");
-    return telemetry_default.initialize(openwhiskAction);
+    return telemetry.initialize(openwhiskAction);
+  }
+  /**
+   * Executes OpenWhisk action with OpenTelemetry instrumentation
+   *
+   * This method wraps the action execution with distributed tracing instrumentation,
+   * creating a span that tracks execution metrics and results in New Relic.
+   *
+   * @param name - Action name used for span naming
+   * @param headers - Request headers
+   * @param params - Request parameters
+   * @param action - The user's action function to execute
+   * @param telemetry - Telemetry instance for instrumentation
+   * @param logger - Logger instance
+   * @returns Promise resolving to the action result
+   *
+   * @private
+   */
+  static async executeActionWithInstrumentation(name, headers, params, action, telemetry, logger) {
+    const instrumentedAction = telemetry.instrument(
+      `openwhisk.action.${name}.execute`,
+      async (actionName, actionHeaders, actionParams, actionFn, actionTelemetry, actionLogger) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("openwhisk.action.name", actionName);
+          span.setAttribute("openwhisk.action.has_headers", !!actionHeaders);
+          span.addEvent("openwhisk-execution-started");
+        }
+        const result = await actionFn(actionParams, {
+          logger: actionLogger,
+          headers: actionHeaders,
+          telemetry: actionTelemetry
+        });
+        if (span) {
+          const statusCode = "statusCode" in result ? result.statusCode : result.error.statusCode;
+          span.setAttribute("openwhisk.action.response_status", statusCode);
+          span.setAttribute("openwhisk.action.has_error", "error" in result);
+          span.addEvent("openwhisk-execution-completed", {
+            statusCode
+          });
+        }
+        return result;
+      }
+    );
+    return instrumentedAction(name, headers, params, action, telemetry, logger);
   }
 };
 __name(_OpenwhiskAction, "OpenwhiskAction");
@@ -2595,41 +3307,17 @@ var _WebhookAction = class _WebhookAction {
    */
   static execute(name = "webhook", requiredParams = [], requiredHeaders = [], signatureVerification = "disabled" /* DISABLED */, action = async () => response_default2.success()) {
     const httpMethods = ["POST" /* POST */];
-    const verifySignature = /* @__PURE__ */ __name(async (params) => {
-      const signature = params.__ow_headers["x-adobe-commerce-webhook-signature"] || "";
-      if (!signature) {
-        return "Header `x-adobe-commerce-webhook-signature` not found. Make sure Webhooks signature is enabled in the Commerce instance.";
-      }
-      const body = params.__ow_body;
-      if (!body) {
-        return "Request body not found. Make sure the action is configured with `raw-http: true`.";
-      }
-      let publicKey = params.PUBLIC_KEY;
-      if (!publicKey && params.PUBLIC_KEY_BASE64) {
-        publicKey = atob(params.PUBLIC_KEY_BASE64);
-      }
-      if (!publicKey) {
-        return "Public key not found. Make sure the action is configured with the input `PUBLIC_KEY` or `PUBLIC_KEY_BASE64` and it is defined in .env file.";
-      }
-      try {
-        const verifier = import_crypto.default.createVerify("SHA256");
-        verifier.update(body);
-        const isSignatureValid = verifier.verify(publicKey, signature, "base64");
-        if (!isSignatureValid) {
-          return "The signature is invalid.";
-        }
-      } catch (error) {
-        return "The signature is invalid.";
-      }
-      return null;
-    }, "verifySignature");
     const callback = /* @__PURE__ */ __name(async (params, ctx) => {
-      const { logger } = ctx;
+      const { logger, telemetry } = ctx;
       if (signatureVerification === "enabled" /* ENABLED */) {
-        const verificationErrorMessage = await verifySignature(params);
+        const verificationErrorMessage = await _WebhookAction.verifySignatureWithInstrumentation(
+          name,
+          params,
+          telemetry
+        );
         if (verificationErrorMessage) {
           logger.error({
-            message: "Webhook actionsignature verification failed",
+            message: "Webhook action signature verification failed",
             error: verificationErrorMessage
           });
           const verificationErrorResponse = response_default2.exception(verificationErrorMessage);
@@ -2640,7 +3328,13 @@ var _WebhookAction = class _WebhookAction {
           ...JSON.parse(atob(params.__ow_body))
         };
       }
-      const errorMessage = validator_default.checkMissingRequestInputs(params, requiredParams, requiredHeaders) ?? "";
+      const errorMessage = _WebhookAction.validateWithInstrumentation(
+        name,
+        params,
+        requiredParams,
+        requiredHeaders,
+        telemetry
+      );
       if (errorMessage) {
         logger.error({
           message: "Webhook action validation failed",
@@ -2649,13 +3343,183 @@ var _WebhookAction = class _WebhookAction {
         const errorMessageResponse = response_default2.exception(errorMessage);
         return response_default.success(JSON.stringify(errorMessageResponse));
       }
-      const response = await action(params, ctx);
+      const response = await _WebhookAction.executeActionWithInstrumentation(
+        name,
+        action,
+        params,
+        ctx
+      );
       return response_default.success(JSON.stringify(response));
     }, "callback");
     runtime_action_default.setActionType("webhook-action");
     runtime_action_default.setActionTypeName("Webhook action");
     return runtime_action_default.execute(name, httpMethods, [], [], callback);
   }
+  /**
+   * Executes webhook action with OpenTelemetry instrumentation
+   *
+   * This method wraps the webhook action execution with distributed tracing instrumentation,
+   * creating a span that tracks execution metrics and results in New Relic.
+   *
+   * @param name - Webhook action name used for span naming
+   * @param action - The webhook action function to execute
+   * @param params - Request parameters
+   * @param ctx - Context object with logger, headers, and telemetry
+   * @returns Promise resolving to the webhook action response(s)
+   *
+   * @private
+   */
+  static async executeActionWithInstrumentation(name, action, params, ctx) {
+    const instrumentedWebhookAction = ctx.telemetry.instrument(
+      `webhook.action.${name}.execute`,
+      async (actionName, actionFn, actionParams, context2) => {
+        const span = context2.telemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("webhook.action.name", actionName);
+          span.setAttribute("webhook.action.has_headers", !!context2.headers);
+          span.addEvent("webhook-execution-started");
+        }
+        const response = await actionFn(actionParams, context2);
+        if (span) {
+          span.setAttribute("webhook.action.response_is_array", Array.isArray(response));
+          if (Array.isArray(response)) {
+            span.setAttribute("webhook.action.response_count", response.length);
+          }
+          span.addEvent("webhook-execution-completed", {
+            isArray: Array.isArray(response),
+            count: Array.isArray(response) ? response.length : 1
+          });
+        }
+        return response;
+      }
+    );
+    return instrumentedWebhookAction(name, action, params, ctx);
+  }
+  /**
+   * Verifies webhook signature with OpenTelemetry instrumentation
+   *
+   * This method wraps the signature verification logic with distributed tracing instrumentation,
+   * creating a span that tracks verification metrics and results in New Relic.
+   *
+   * @param name - Webhook action name used for span naming
+   * @param params - Request parameters including headers, body, and public key
+   * @param telemetry - Telemetry instance for instrumentation
+   * @returns Error message if verification fails, null if successful
+   *
+   * @private
+   */
+  static async verifySignatureWithInstrumentation(name, params, telemetry) {
+    const instrumentedVerifySignature = telemetry.instrument(
+      `webhook.action.${name}.verify-signature`,
+      async (actionName, actionParams, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("webhook.signature.enabled", true);
+          span.setAttribute(
+            "webhook.signature.header_present",
+            !!actionParams.__ow_headers?.["x-adobe-commerce-webhook-signature"]
+          );
+          span.setAttribute("webhook.signature.has_body", !!actionParams.__ow_body);
+          span.setAttribute(
+            "webhook.signature.has_public_key",
+            !!(actionParams.PUBLIC_KEY || actionParams.PUBLIC_KEY_BASE64)
+          );
+          span.addEvent("signature-verification-started");
+        }
+        const verificationError = await _WebhookAction.verifySignature(actionParams);
+        if (span) {
+          span.setAttribute("webhook.signature.valid", verificationError === null);
+          if (verificationError) {
+            span.setAttribute("webhook.signature.error", verificationError);
+          }
+          span.addEvent("signature-verification-completed", {
+            valid: verificationError === null
+          });
+        }
+        return verificationError;
+      }
+    );
+    return instrumentedVerifySignature(name, params, telemetry);
+  }
+  /**
+   * Validates webhook parameters and headers with OpenTelemetry instrumentation
+   *
+   * This method wraps the validation logic with distributed tracing instrumentation,
+   * creating a span that tracks validation metrics and results in New Relic.
+   *
+   * @param name - Webhook action name used for span naming
+   * @param params - Request parameters
+   * @param requiredParams - List of required parameter names to validate
+   * @param requiredHeaders - List of required header names to validate
+   * @param telemetry - Telemetry instance for instrumentation
+   * @returns Error message if validation fails, empty string if successful
+   *
+   * @private
+   */
+  static validateWithInstrumentation(name, params, requiredParams, requiredHeaders, telemetry) {
+    const instrumentedValidate = telemetry.instrument(
+      `webhook.action.${name}.validate`,
+      (actionName, actionParams, actionRequiredParams, actionRequiredHeaders, actionTelemetry) => {
+        const span = actionTelemetry.getCurrentSpan();
+        if (span) {
+          span.setAttribute("webhook.validation.required_params", actionRequiredParams.join(","));
+          span.setAttribute("webhook.validation.required_headers", actionRequiredHeaders.join(","));
+        }
+        const errorMessage = validator_default.checkMissingRequestInputs(
+          actionParams,
+          actionRequiredParams,
+          actionRequiredHeaders
+        ) ?? "";
+        if (span) {
+          span.setAttribute("webhook.validation.passed", errorMessage === "");
+          if (errorMessage) {
+            span.setAttribute("webhook.validation.error", errorMessage);
+          }
+        }
+        return errorMessage;
+      }
+    );
+    return instrumentedValidate(name, params, requiredParams, requiredHeaders, telemetry);
+  }
+  /**
+   * Verify webhook signature using a public key and SHA256
+   *
+   * This method validates the authenticity of webhook requests by verifying
+   * the signature against the request body using the provided public key.
+   *
+   * @param params - Request parameters including headers, body, and public key
+   * @returns Error message if verification fails, null if successful
+   *
+   * @private
+   */
+  static async verifySignature(params) {
+    const signature = params.__ow_headers["x-adobe-commerce-webhook-signature"] || "";
+    if (!signature) {
+      return "Header `x-adobe-commerce-webhook-signature` not found. Make sure Webhooks signature is enabled in the Commerce instance.";
+    }
+    const body = params.__ow_body;
+    if (!body) {
+      return "Request body not found. Make sure the action is configured with `raw-http: true`.";
+    }
+    let publicKey = params.PUBLIC_KEY;
+    if (!publicKey && params.PUBLIC_KEY_BASE64) {
+      publicKey = atob(params.PUBLIC_KEY_BASE64);
+    }
+    if (!publicKey) {
+      return "Public key not found. Make sure the action is configured with the input `PUBLIC_KEY` or `PUBLIC_KEY_BASE64` and it is defined in .env file.";
+    }
+    try {
+      const verifier = import_crypto.default.createVerify("SHA256");
+      verifier.update(body);
+      const isSignatureValid = verifier.verify(publicKey, signature, "base64");
+      if (!isSignatureValid) {
+        return "The signature is invalid.";
+      }
+    } catch (error) {
+      return "The signature is invalid.";
+    }
+    return null;
+  }
 };
 __name(_WebhookAction, "WebhookAction");
 var WebhookAction = _WebhookAction;