@pagopa/azure-tracing 0.1.0 → 0.3.0

package/README.md

@@ -1,18 +1,109 @@
 # @pagopa/azure-tracing
 
-This package provides a set of tools to integrate Azure Application Insights with OpenTelemetry for tracing and telemetry in Node.js applications.
+This package provides utilities to seamlessly integrate [Azure Monitor's Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview)
+with OpenTelemetry for distributed tracing and telemetry in Node.js applications, especially in Azure Functions environments.
 
-## Usage
-1. Install the package:
+## Installation
 
-   ```bash
-   yarn add @pagopa/azure-tracing
-   ```
+Install the package using:
 
-If you need to enable tracing on Azure Functions, you can simply add the following environment variable:
+```bash
+yarn add @pagopa/azure-tracing
 ```
-"NODE_OPTIONS": "--import @pagopa/azure-tracing",
+
+## Getting Started
+
+### Instrumenting Azure Functions
+
+Currently, [ECMAScript Modules (ESM) support in OpenTelemetry is still experimental](https://github.com/open-telemetry/opentelemetry-js/blob/966ac176af249d86de6cb10feac2306062846768/doc/esm-support.md),
+which makes direct instrumentation of Azure Functions a bit tricky.
+So, if you have a Node.js project ESM based (`"type": "module"` in the `package.json`), to work around this, you have to preload the instrumentation logic at runtime using the `NODE_OPTIONS` environment variable.
+
+> [!NOTE]
+> In case you have a CJS project (`"type": "commonjs"` in the `package.json`), you could use the [`opentelemetry-js` library](https://github.com/open-telemetry/opentelemetry-js?tab=readme-ov-file#quick-start)
+> to instrument the application, making sure the OpenTelemetry SDK is initialized before the Azure Functions runtime starts.  
+> This package is useful for ESM projects only, where the instrumentation logic needs to be preloaded.
+
+This package provides a wrapper that simplifies this setup.
+
+#### Step 1: Enable Tracing via NODE_OPTIONS
+
+Set the following environment variable to preload the instrumentation:
+
+```bash
+NODE_OPTIONS=--import @pagopa/azure-tracing
+```
+
+This will automatically enable OpenTelemetry tracing and route telemetry to Azure Monitor.
+
+For more background on this workaround, see:
+
+- [Issue #4845 - OpenTelemetry JS](https://github.com/open-telemetry/opentelemetry-js/issues/4845#issuecomment-2253556217)
+- [Issue #4933 - OpenTelemetry JS](https://github.com/open-telemetry/opentelemetry-js/issues/4933)
+
+In order to enable tracing, you also need to set the following environment variables:
+
+| **Name**                            | **Required** | **Default** |
+| ----------------------------------- | ------------ | ----------- |
+| **APPINSIGHTS_SAMPLING_PERCENTAGE** | false        | 5           |
+| **APPINSIGHTS_CONNECTION_STRING**   | true         | -           |
+
+#### Step 2: Register Azure Function Lifecycle Hooks
+
+Due to known limitations with the `azure-functions-nodejs-opentelemetry` library,
+it's necessary to manually register lifecycle hooks to ensure proper dependency correlation in telemetry.
+
+For more background on this workaround, see:
+
+- [Issue #8 - azure-functions-nodejs-opentelemetry](https://github.com/Azure/azure-functions-nodejs-opentelemetry/issues/8)
+- [Issue #33242 - azure-sdk-for-js](https://github.com/Azure/azure-sdk-for-js/issues/33242)
+
+Add the following snippet to your main entry point (e.g., `main.ts`):
+
+```ts
+import { app } from "@azure/functions"; // Replace with your actual app import
+import { registerAzureFunctionHooks } from "@pagopa/azure-tracing/azure-functions";
+...
+registerAzureFunctionHooks(app);
+...
+```
+
+### Enabling Azure Monitor Telemetry
+
+If you want to enable Azure Monitor telemetry in your application, and you don't have those issues previously described, you can do so in the following ways:
+
+```ts
+import { initAzureMonitor } from "@pagopa/azure-tracing/azure-monitor";
+import { AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+...
+const config: AzureMonitorOpenTelemetryOptions = {} // A valid AzureMonitorOpenTelemetryOptions object
+const instrumentations = [new ExpressInstrumentation()] // A list of custom OpenTelemetry instrumentations
+initAzureMonitor(instrumentations, config);
+...
+```
+
+> [!NOTE]
+> the use of `ExpressInstrumentation` is just for example, you can use any other OpenTelemetry instrumentation you want.
+
+or, if you want to use the default configuration:
+
+```ts
+import { initAzureMonitor } from "@pagopa/azure-tracing/azure-monitor";
+...
+initAzureMonitor();
+```
+
+### Logging Custom Events
+
+You can log custom events for additional observability using the `emitCustomEvent` function.
+This utility accepts an event name and an optional payload, returning a logger function that also accepts a component or handler name.
+
+```ts
+import { emitCustomEvent } from "@pagopa/azure-tracing/logger";
+...
+emitCustomEvent("taskCreated", { id: task.id })("CreateTaskHandler");
+...
 ```
-This will instrument you Azure Function with OpenTelemetry and Application Insights.
 
-With this approach, you don't need to add any code to your Azure Function. The instrumentation will be automatically applied when the function is executed.
+This is especially useful for tracing domain-specific actions (e.g., resource creation, user actions, error tracking).

package/dist/{azure-functions-hooks.d.ts → functions/hooks.d.ts}

@@ -1,4 +1,5 @@
-import { app } from "@azure/functions";
+import { app } from '@azure/functions';
+
 /**
  * Registers Azure Function hooks to enable OpenTelemetry tracing.
  * These hooks extract trace context from the Azure Function context
@@ -9,7 +10,13 @@ import { app } from "@azure/functions";
  * to add the [azure-functions-nodejs-opentelemetry](https://github.com/Azure/azure-functions-nodejs-opentelemetry/tree/main)
  * to the instrumentation package and remove this workaround.
  *
- * @param {Object} options - An object containing the Azure Functions `hook` object.
- * @param {Function} options.hook - The Azure Functions `hook` object from the `app` module.
+ * @example
+ * In your application, where you add the Azure Functions hooks (like `app.http() and so on), you
+ * can add the following code:
+ *
+ * registerAzureFunctionHooks(app);
+ *
  */
-export declare const registerAzureFunctionHooks: ({ hook }: typeof app) => void;
+declare const registerAzureFunctionHooks: ({ hook }: typeof app) => void;
+
+export { registerAzureFunctionHooks };

package/dist/functions/hooks.js

@@ -0,0 +1,20 @@
+// src/azure/functions/hooks.ts
+import { context as otelContext, propagation } from "@opentelemetry/api";
+var registerAzureFunctionHooks = ({ hook }) => {
+  hook.preInvocation((context) => {
+    const traceContext = context.invocationContext.traceContext;
+    if (traceContext) {
+      context.functionHandler = otelContext.bind(
+        propagation.extract(otelContext.active(), {
+          traceparent: traceContext.traceParent,
+          tracestate: traceContext.traceState
+        }),
+        context.functionHandler
+      );
+    }
+  });
+};
+export {
+  registerAzureFunctionHooks
+};
+//# sourceMappingURL=hooks.js.map

package/dist/functions/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/azure/functions/hooks.ts"],"sourcesContent":["import { app } from \"@azure/functions\";\nimport { context as otelContext, propagation } from \"@opentelemetry/api\";\n\n/**\n * Registers Azure Function hooks to enable OpenTelemetry tracing.\n * These hooks extract trace context from the Azure Function context\n * and bind it to the function handler, ensuring that traces are\n * properly propagated across function invocations.\n *\n * Once the issues that causes this workaround are resolved, it will be possible\n * to add the [azure-functions-nodejs-opentelemetry](https://github.com/Azure/azure-functions-nodejs-opentelemetry/tree/main)\n * to the instrumentation package and remove this workaround.\n *\n * @example\n * In your application, where you add the Azure Functions hooks (like `app.http() and so on), you\n * can add the following code:\n *\n * registerAzureFunctionHooks(app);\n *\n */\nexport const registerAzureFunctionHooks = ({ hook }: typeof app) => {\n  hook.preInvocation((context) => {\n    const traceContext = context.invocationContext.traceContext;\n    if (traceContext) {\n      context.functionHandler = otelContext.bind(\n        propagation.extract(otelContext.active(), {\n          traceparent: traceContext.traceParent,\n          tracestate: traceContext.traceState,\n        }),\n        context.functionHandler,\n      );\n    }\n  });\n};\n"],"mappings":";AACA,SAAS,WAAW,aAAa,mBAAmB;AAmB7C,IAAM,6BAA6B,CAAC,EAAE,KAAK,MAAkB;AAClE,OAAK,cAAc,CAAC,YAAY;AAC9B,UAAM,eAAe,QAAQ,kBAAkB;AAC/C,QAAI,cAAc;AAChB,cAAQ,kBAAkB,YAAY;AAAA,QACpC,YAAY,QAAQ,YAAY,OAAO,GAAG;AAAA,UACxC,aAAa,aAAa;AAAA,UAC1B,YAAY,aAAa;AAAA,QAC3B,CAAC;AAAA,QACD,QAAQ;AAAA,MACV;AAAA,IACF;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/functions/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/functions/index.js

@@ -0,0 +1,75 @@
+// src/azure/functions/index.mts
+import { createAddHookMessageChannel } from "import-in-the-middle";
+import { register } from "module";
+import { metrics, trace } from "@opentelemetry/api";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+
+// src/azure/monitor/start-from-env.ts
+import { useAzureMonitor } from "@azure/monitor-opentelemetry";
+
+// src/azure/monitor/env.ts
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+var loadEnv = () => createEnv({
+  emptyStringAsUndefined: true,
+  onValidationError: (errors) => {
+    throw new Error(
+      errors.map(
+        (error) => `Environment variable ${error.path} - ${error.message}`
+      ).join(", ")
+    );
+  },
+  runtimeEnv: process.env,
+  server: {
+    APPINSIGHTS_CONNECTION_STRING: z.string().describe("The connection string for Application Insights."),
+    APPINSIGHTS_SAMPLING_PERCENTAGE: z.optional(
+      z.coerce.number().min(0).max(100).default(5).describe(
+        "Application Insights sampling percentage between 0 and 100. If not set, defaults to 5."
+      )
+    ).transform((value) => {
+      const percentage = Number(value);
+      return isNaN(percentage) ? 5 : percentage;
+    }).transform((value) => value / 100)
+  }
+});
+
+// src/azure/monitor/start-from-env.ts
+var initFromEnv = () => {
+  const env = loadEnv();
+  return useAzureMonitor({
+    azureMonitorExporterOptions: {
+      connectionString: env.APPINSIGHTS_CONNECTION_STRING
+    },
+    enableLiveMetrics: true,
+    samplingRatio: env.APPINSIGHTS_SAMPLING_PERCENTAGE
+  });
+};
+
+// src/azure/opentelemetry/azure-undici-instrumentation.ts
+import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
+var registerUndiciInstrumentation = () => new UndiciInstrumentation({
+  requestHook: (span, requestInfo) => {
+    const { method, origin, path } = requestInfo;
+    span.setAttributes({
+      "http.host": origin,
+      "http.method": method,
+      "http.target": path,
+      "http.url": `${origin}${path}`
+    });
+  },
+  responseHook: (span, { response }) => {
+    span.setAttribute("http.status_code", response.statusCode);
+  }
+});
+
+// src/azure/functions/index.mts
+var { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel();
+register("import-in-the-middle/hook.mjs", import.meta.url, registerOptions);
+initFromEnv();
+registerInstrumentations({
+  instrumentations: [registerUndiciInstrumentation()],
+  meterProvider: metrics.getMeterProvider(),
+  tracerProvider: trace.getTracerProvider()
+});
+await waitForAllMessagesAcknowledged();
+//# sourceMappingURL=index.js.map

package/dist/functions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/azure/functions/index.mts","../../src/azure/monitor/start-from-env.ts","../../src/azure/monitor/env.ts","../../src/azure/opentelemetry/azure-undici-instrumentation.ts"],"sourcesContent":["/*\nThis file is required to instrument ESM application to use OpenTelemetry.\nThis file must be pre-loaded through the `NODE_OPTIONS` environment variable to\nhave a fully instrumented application.\n */\n\nimport { createAddHookMessageChannel } from \"import-in-the-middle\";\nimport { register } from \"module\";\n\nconst { registerOptions, waitForAllMessagesAcknowledged } =\n  createAddHookMessageChannel();\n\nregister(\"import-in-the-middle/hook.mjs\", import.meta.url, registerOptions);\n\nimport { metrics, trace } from \"@opentelemetry/api\";\nimport { registerInstrumentations } from \"@opentelemetry/instrumentation\";\n\nimport { initFromEnv } from \"../monitor/start-from-env\";\nimport { registerUndiciInstrumentation } from \"../opentelemetry/azure-undici-instrumentation\";\n\ninitFromEnv();\n\nregisterInstrumentations({\n  instrumentations: [registerUndiciInstrumentation()],\n  meterProvider: metrics.getMeterProvider(),\n  tracerProvider: trace.getTracerProvider(),\n});\n\nawait waitForAllMessagesAcknowledged();\n","import { useAzureMonitor } from \"@azure/monitor-opentelemetry\";\n\nimport { loadEnv } from \"./env\";\n\nexport const initFromEnv = () => {\n  const env = loadEnv();\n\n  return useAzureMonitor({\n    azureMonitorExporterOptions: {\n      connectionString: env.APPINSIGHTS_CONNECTION_STRING,\n    },\n    enableLiveMetrics: true,\n    samplingRatio: env.APPINSIGHTS_SAMPLING_PERCENTAGE,\n  });\n};\n","// Load and type check environment variables on runtime\nimport { createEnv } from \"@t3-oss/env-core\";\nimport { z } from \"zod\";\n\nexport const loadEnv = () =>\n  createEnv({\n    emptyStringAsUndefined: true,\n    onValidationError: (errors) => {\n      throw new Error(\n        errors\n          .map(\n            (error) => `Environment variable ${error.path} - ${error.message}`,\n          )\n          .join(\", \"),\n      );\n    },\n    runtimeEnv: process.env,\n    server: {\n      APPINSIGHTS_CONNECTION_STRING: z\n        .string()\n        .describe(\"The connection string for Application Insights.\"),\n      APPINSIGHTS_SAMPLING_PERCENTAGE: z\n        .optional(\n          z.coerce\n            .number()\n            .min(0)\n            .max(100)\n            .default(5)\n            .describe(\n              \"Application Insights sampling percentage between 0 and 100. If not set, defaults to 5.\",\n            ),\n        )\n        .transform((value) => {\n          const percentage = Number(value);\n          return isNaN(percentage) ? 5 : percentage;\n        })\n        .transform((value) => value / 100),\n    },\n  });\n","import { UndiciInstrumentation } from \"@opentelemetry/instrumentation-undici\";\n\n// instrument native node fetch\nexport const registerUndiciInstrumentation = () =>\n  new UndiciInstrumentation({\n    requestHook: (span, requestInfo) => {\n      const { method, origin, path } = requestInfo;\n      // Default instrumented attributes don't feed well into AppInsights,\n      // so we set them manually.\n      span.setAttributes({\n        \"http.host\": origin,\n        \"http.method\": method,\n        \"http.target\": path,\n        \"http.url\": `${origin}${path}`,\n      });\n    },\n    responseHook: (span, { response }) => {\n      // Same as above, set the status code manually.\n      span.setAttribute(\"http.status_code\", response.statusCode);\n    },\n  });\n"],"mappings":";AAMA,SAAS,mCAAmC;AAC5C,SAAS,gBAAgB;AAOzB,SAAS,SAAS,aAAa;AAC/B,SAAS,gCAAgC;;;ACfzC,SAAS,uBAAuB;;;ACChC,SAAS,iBAAiB;AAC1B,SAAS,SAAS;AAEX,IAAM,UAAU,MACrB,UAAU;AAAA,EACR,wBAAwB;AAAA,EACxB,mBAAmB,CAAC,WAAW;AAC7B,UAAM,IAAI;AAAA,MACR,OACG;AAAA,QACC,CAAC,UAAU,wBAAwB,MAAM,IAAI,MAAM,MAAM,OAAO;AAAA,MAClE,EACC,KAAK,IAAI;AAAA,IACd;AAAA,EACF;AAAA,EACA,YAAY,QAAQ;AAAA,EACpB,QAAQ;AAAA,IACN,+BAA+B,EAC5B,OAAO,EACP,SAAS,iDAAiD;AAAA,IAC7D,iCAAiC,EAC9B;AAAA,MACC,EAAE,OACC,OAAO,EACP,IAAI,CAAC,EACL,IAAI,GAAG,EACP,QAAQ,CAAC,EACT;AAAA,QACC;AAAA,MACF;AAAA,IACJ,EACC,UAAU,CAAC,UAAU;AACpB,YAAM,aAAa,OAAO,KAAK;AAC/B,aAAO,MAAM,UAAU,IAAI,IAAI;AAAA,IACjC,CAAC,EACA,UAAU,CAAC,UAAU,QAAQ,GAAG;AAAA,EACrC;AACF,CAAC;;;ADlCI,IAAM,cAAc,MAAM;AAC/B,QAAM,MAAM,QAAQ;AAEpB,SAAO,gBAAgB;AAAA,IACrB,6BAA6B;AAAA,MAC3B,kBAAkB,IAAI;AAAA,IACxB;AAAA,IACA,mBAAmB;AAAA,IACnB,eAAe,IAAI;AAAA,EACrB,CAAC;AACH;;;AEdA,SAAS,6BAA6B;AAG/B,IAAM,gCAAgC,MAC3C,IAAI,sBAAsB;AAAA,EACxB,aAAa,CAAC,MAAM,gBAAgB;AAClC,UAAM,EAAE,QAAQ,QAAQ,KAAK,IAAI;AAGjC,SAAK,cAAc;AAAA,MACjB,aAAa;AAAA,MACb,eAAe;AAAA,MACf,eAAe;AAAA,MACf,YAAY,GAAG,MAAM,GAAG,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAAA,EACA,cAAc,CAAC,MAAM,EAAE,SAAS,MAAM;AAEpC,SAAK,aAAa,oBAAoB,SAAS,UAAU;AAAA,EAC3D;AACF,CAAC;;;AHXH,IAAM,EAAE,iBAAiB,+BAA+B,IACtD,4BAA4B;AAE9B,SAAS,iCAAiC,YAAY,KAAK,eAAe;AAQ1E,YAAY;AAEZ,yBAAyB;AAAA,EACvB,kBAAkB,CAAC,8BAA8B,CAAC;AAAA,EAClD,eAAe,QAAQ,iBAAiB;AAAA,EACxC,gBAAgB,MAAM,kBAAkB;AAC1C,CAAC;AAED,MAAM,+BAA+B;","names":[]}

package/dist/{azure-monitor.d.ts → monitor/index.d.ts}

@@ -1,4 +1,6 @@
-import { Instrumentation } from "@opentelemetry/instrumentation";
+import { AzureMonitorOpenTelemetryOptions } from '@azure/monitor-opentelemetry';
+import { Instrumentation } from '@opentelemetry/instrumentation';
+
 /**
  * Initialize the Azure Monitor with the given instrumentations.
  * Call this function to register the instrumentations with the Azure Monitor.
@@ -14,5 +16,8 @@ import { Instrumentation } from "@opentelemetry/instrumentation";
  *
  * initAzureMonitor();
  * @param instrumentations the list of instrumentations to register with the Azure Monitor.
+ * @param azureMonitorOptions custom configuration for Azure Monitor. If not provided, then it will be initialized using the environment variables.
  */
-export declare const initAzureMonitor: (instrumentations?: readonly Instrumentation[]) => void;
+declare const initAzureMonitor: (instrumentations?: readonly Instrumentation[], azureMonitorOptions?: AzureMonitorOpenTelemetryOptions) => void;
+
+export { initAzureMonitor };

package/dist/monitor/index.js

@@ -0,0 +1,84 @@
+// src/azure/monitor/index.ts
+import {
+  useAzureMonitor as useAzureMonitor2
+} from "@azure/monitor-opentelemetry";
+import { metrics, trace } from "@opentelemetry/api";
+import {
+  registerInstrumentations
+} from "@opentelemetry/instrumentation";
+
+// src/azure/opentelemetry/azure-undici-instrumentation.ts
+import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
+var registerUndiciInstrumentation = () => new UndiciInstrumentation({
+  requestHook: (span, requestInfo) => {
+    const { method, origin, path } = requestInfo;
+    span.setAttributes({
+      "http.host": origin,
+      "http.method": method,
+      "http.target": path,
+      "http.url": `${origin}${path}`
+    });
+  },
+  responseHook: (span, { response }) => {
+    span.setAttribute("http.status_code", response.statusCode);
+  }
+});
+
+// src/azure/monitor/start-from-env.ts
+import { useAzureMonitor } from "@azure/monitor-opentelemetry";
+
+// src/azure/monitor/env.ts
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+var loadEnv = () => createEnv({
+  emptyStringAsUndefined: true,
+  onValidationError: (errors) => {
+    throw new Error(
+      errors.map(
+        (error) => `Environment variable ${error.path} - ${error.message}`
+      ).join(", ")
+    );
+  },
+  runtimeEnv: process.env,
+  server: {
+    APPINSIGHTS_CONNECTION_STRING: z.string().describe("The connection string for Application Insights."),
+    APPINSIGHTS_SAMPLING_PERCENTAGE: z.optional(
+      z.coerce.number().min(0).max(100).default(5).describe(
+        "Application Insights sampling percentage between 0 and 100. If not set, defaults to 5."
+      )
+    ).transform((value) => {
+      const percentage = Number(value);
+      return isNaN(percentage) ? 5 : percentage;
+    }).transform((value) => value / 100)
+  }
+});
+
+// src/azure/monitor/start-from-env.ts
+var initFromEnv = () => {
+  const env = loadEnv();
+  return useAzureMonitor({
+    azureMonitorExporterOptions: {
+      connectionString: env.APPINSIGHTS_CONNECTION_STRING
+    },
+    enableLiveMetrics: true,
+    samplingRatio: env.APPINSIGHTS_SAMPLING_PERCENTAGE
+  });
+};
+
+// src/azure/monitor/index.ts
+var initAzureMonitor = (instrumentations = [], azureMonitorOptions) => {
+  if (azureMonitorOptions) {
+    useAzureMonitor2(azureMonitorOptions);
+  } else {
+    initFromEnv();
+  }
+  registerInstrumentations({
+    instrumentations: [registerUndiciInstrumentation(), ...instrumentations],
+    meterProvider: metrics.getMeterProvider(),
+    tracerProvider: trace.getTracerProvider()
+  });
+};
+export {
+  initAzureMonitor
+};
+//# sourceMappingURL=index.js.map

package/dist/monitor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/azure/monitor/index.ts","../../src/azure/opentelemetry/azure-undici-instrumentation.ts","../../src/azure/monitor/start-from-env.ts","../../src/azure/monitor/env.ts"],"sourcesContent":["import {\n  AzureMonitorOpenTelemetryOptions,\n  useAzureMonitor,\n} from \"@azure/monitor-opentelemetry\";\nimport { metrics, trace } from \"@opentelemetry/api\";\nimport {\n  Instrumentation,\n  registerInstrumentations,\n} from \"@opentelemetry/instrumentation\";\n\nimport { registerUndiciInstrumentation } from \"../opentelemetry/azure-undici-instrumentation\";\nimport { initFromEnv } from \"./start-from-env\";\n\n/**\n * Initialize the Azure Monitor with the given instrumentations.\n * Call this function to register the instrumentations with the Azure Monitor.\n * By default, the Undici instrumentation is included; if you need to add more,\n * you can pass them as an array of instrumentations.\n *\n * @remarks\n * This function will register the given instrumentations with the Azure Monitor.\n * It is recommended to call this function at the beginning of your application.\n *\n * @example\n * import { initAzureMonitor } from \"@pagopa/azure-tracing/azure-monitor\";\n *\n * initAzureMonitor();\n * @param instrumentations the list of instrumentations to register with the Azure Monitor.\n * @param azureMonitorOptions custom configuration for Azure Monitor. If not provided, then it will be initialized using the environment variables.\n */\nexport const initAzureMonitor = (\n  instrumentations: readonly Instrumentation[] = [],\n  azureMonitorOptions?: AzureMonitorOpenTelemetryOptions,\n) => {\n  if (azureMonitorOptions) {\n    useAzureMonitor(azureMonitorOptions);\n  } else {\n    initFromEnv();\n  }\n\n  registerInstrumentations({\n    instrumentations: [registerUndiciInstrumentation(), ...instrumentations],\n    meterProvider: metrics.getMeterProvider(),\n    tracerProvider: trace.getTracerProvider(),\n  });\n};\n","import { UndiciInstrumentation } from \"@opentelemetry/instrumentation-undici\";\n\n// instrument native node fetch\nexport const registerUndiciInstrumentation = () =>\n  new UndiciInstrumentation({\n    requestHook: (span, requestInfo) => {\n      const { method, origin, path } = requestInfo;\n      // Default instrumented attributes don't feed well into AppInsights,\n      // so we set them manually.\n      span.setAttributes({\n        \"http.host\": origin,\n        \"http.method\": method,\n        \"http.target\": path,\n        \"http.url\": `${origin}${path}`,\n      });\n    },\n    responseHook: (span, { response }) => {\n      // Same as above, set the status code manually.\n      span.setAttribute(\"http.status_code\", response.statusCode);\n    },\n  });\n","import { useAzureMonitor } from \"@azure/monitor-opentelemetry\";\n\nimport { loadEnv } from \"./env\";\n\nexport const initFromEnv = () => {\n  const env = loadEnv();\n\n  return useAzureMonitor({\n    azureMonitorExporterOptions: {\n      connectionString: env.APPINSIGHTS_CONNECTION_STRING,\n    },\n    enableLiveMetrics: true,\n    samplingRatio: env.APPINSIGHTS_SAMPLING_PERCENTAGE,\n  });\n};\n","// Load and type check environment variables on runtime\nimport { createEnv } from \"@t3-oss/env-core\";\nimport { z } from \"zod\";\n\nexport const loadEnv = () =>\n  createEnv({\n    emptyStringAsUndefined: true,\n    onValidationError: (errors) => {\n      throw new Error(\n        errors\n          .map(\n            (error) => `Environment variable ${error.path} - ${error.message}`,\n          )\n          .join(\", \"),\n      );\n    },\n    runtimeEnv: process.env,\n    server: {\n      APPINSIGHTS_CONNECTION_STRING: z\n        .string()\n        .describe(\"The connection string for Application Insights.\"),\n      APPINSIGHTS_SAMPLING_PERCENTAGE: z\n        .optional(\n          z.coerce\n            .number()\n            .min(0)\n            .max(100)\n            .default(5)\n            .describe(\n              \"Application Insights sampling percentage between 0 and 100. If not set, defaults to 5.\",\n            ),\n        )\n        .transform((value) => {\n          const percentage = Number(value);\n          return isNaN(percentage) ? 5 : percentage;\n        })\n        .transform((value) => value / 100),\n    },\n  });\n"],"mappings":";AAAA;AAAA,EAEE,mBAAAA;AAAA,OACK;AACP,SAAS,SAAS,aAAa;AAC/B;AAAA,EAEE;AAAA,OACK;;;ACRP,SAAS,6BAA6B;AAG/B,IAAM,gCAAgC,MAC3C,IAAI,sBAAsB;AAAA,EACxB,aAAa,CAAC,MAAM,gBAAgB;AAClC,UAAM,EAAE,QAAQ,QAAQ,KAAK,IAAI;AAGjC,SAAK,cAAc;AAAA,MACjB,aAAa;AAAA,MACb,eAAe;AAAA,MACf,eAAe;AAAA,MACf,YAAY,GAAG,MAAM,GAAG,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAAA,EACA,cAAc,CAAC,MAAM,EAAE,SAAS,MAAM;AAEpC,SAAK,aAAa,oBAAoB,SAAS,UAAU;AAAA,EAC3D;AACF,CAAC;;;ACpBH,SAAS,uBAAuB;;;ACChC,SAAS,iBAAiB;AAC1B,SAAS,SAAS;AAEX,IAAM,UAAU,MACrB,UAAU;AAAA,EACR,wBAAwB;AAAA,EACxB,mBAAmB,CAAC,WAAW;AAC7B,UAAM,IAAI;AAAA,MACR,OACG;AAAA,QACC,CAAC,UAAU,wBAAwB,MAAM,IAAI,MAAM,MAAM,OAAO;AAAA,MAClE,EACC,KAAK,IAAI;AAAA,IACd;AAAA,EACF;AAAA,EACA,YAAY,QAAQ;AAAA,EACpB,QAAQ;AAAA,IACN,+BAA+B,EAC5B,OAAO,EACP,SAAS,iDAAiD;AAAA,IAC7D,iCAAiC,EAC9B;AAAA,MACC,EAAE,OACC,OAAO,EACP,IAAI,CAAC,EACL,IAAI,GAAG,EACP,QAAQ,CAAC,EACT;AAAA,QACC;AAAA,MACF;AAAA,IACJ,EACC,UAAU,CAAC,UAAU;AACpB,YAAM,aAAa,OAAO,KAAK;AAC/B,aAAO,MAAM,UAAU,IAAI,IAAI;AAAA,IACjC,CAAC,EACA,UAAU,CAAC,UAAU,QAAQ,GAAG;AAAA,EACrC;AACF,CAAC;;;ADlCI,IAAM,cAAc,MAAM;AAC/B,QAAM,MAAM,QAAQ;AAEpB,SAAO,gBAAgB;AAAA,IACrB,6BAA6B;AAAA,MAC3B,kBAAkB,IAAI;AAAA,IACxB;AAAA,IACA,mBAAmB;AAAA,IACnB,eAAe,IAAI;AAAA,EACrB,CAAC;AACH;;;AFgBO,IAAM,mBAAmB,CAC9B,mBAA+C,CAAC,GAChD,wBACG;AACH,MAAI,qBAAqB;AACvB,IAAAC,iBAAgB,mBAAmB;AAAA,EACrC,OAAO;AACL,gBAAY;AAAA,EACd;AAEA,2BAAyB;AAAA,IACvB,kBAAkB,CAAC,8BAA8B,GAAG,GAAG,gBAAgB;AAAA,IACvE,eAAe,QAAQ,iBAAiB;AAAA,IACxC,gBAAgB,MAAM,kBAAkB;AAAA,EAC1C,CAAC;AACH;","names":["useAzureMonitor","useAzureMonitor"]}

package/dist/{logger.d.ts → opentelemetry/logger.d.ts}

@@ -5,4 +5,6 @@
  * @param eventName the name of the event to emit
  * @param attributes the attributes to include with the event
  */
-export declare const emitCustomEvent: (eventName: string, attributes: Record<string, string>) => (loggerName?: string) => void;
+declare const emitCustomEvent: (eventName: string, attributes?: Record<string, string>) => (loggerName?: string) => void;
+
+export { emitCustomEvent };

package/dist/opentelemetry/logger.js

@@ -0,0 +1,14 @@
+// src/azure/opentelemetry/logger.ts
+import { logs } from "@opentelemetry/api-logs";
+var emitCustomEvent = (eventName, attributes = {}) => (loggerName = "ApplicationInsightsLogger") => {
+  logs.getLogger(loggerName).emit({
+    attributes: {
+      "microsoft.custom_event.name": eventName,
+      ...attributes
+    }
+  });
+};
+export {
+  emitCustomEvent
+};
+//# sourceMappingURL=logger.js.map

package/dist/opentelemetry/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/azure/opentelemetry/logger.ts"],"sourcesContent":["import { logs } from \"@opentelemetry/api-logs\";\n\n/**\n * Emit a custom event to the Azure Monitor.\n * This function is used to emit custom events to the Azure Monitor.\n *\n * @param eventName the name of the event to emit\n * @param attributes the attributes to include with the event\n */\nexport const emitCustomEvent =\n  (eventName: string, attributes: Record<string, string> = {}) =>\n  (loggerName = \"ApplicationInsightsLogger\") => {\n    logs.getLogger(loggerName).emit({\n      attributes: {\n        \"microsoft.custom_event.name\": eventName,\n        ...attributes,\n      },\n    });\n  };\n"],"mappings":";AAAA,SAAS,YAAY;AASd,IAAM,kBACX,CAAC,WAAmB,aAAqC,CAAC,MAC1D,CAAC,aAAa,gCAAgC;AAC5C,OAAK,UAAU,UAAU,EAAE,KAAK;AAAA,IAC9B,YAAY;AAAA,MACV,+BAA+B;AAAA,MAC/B,GAAG;AAAA,IACL;AAAA,EACF,CAAC;AACH;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagopa/azure-tracing",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A package that contains some utilities to enable Azure tracing on Node.js applications.",
   "keywords": [
@@ -11,42 +11,43 @@
   "files": [
     "dist"
   ],
-  "main": "./dist/azure-functions.mjs",
+  "main": "./dist/functions/index.js",
   "exports": {
     ".": {
-      "import": "./dist/azure-functions.mjs"
+      "import": "./dist/functions/index.js"
     },
     "./logger": {
-      "import": "./dist/logger.js"
+      "import": "./dist/opentelemetry/logger.js"
     },
     "./azure-monitor": {
-      "import": "./dist/azure-monitor.js"
+      "import": "./dist/monitor/index.js"
     },
     "./azure-functions": {
-      "import": "./dist/azure-functions-hooks.js"
+      "import": "./dist/functions/hooks.js"
     }
   },
   "dependencies": {
     "@azure/functions": "^4.7.0",
-    "@azure/monitor-opentelemetry": "^1.9.0",
-    "@azure/monitor-opentelemetry-exporter": "^1.0.0-beta.29",
+    "@azure/monitor-opentelemetry": "^1.10.0",
+    "@azure/monitor-opentelemetry-exporter": "^1.0.0-beta.30",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.200.0",
     "@opentelemetry/instrumentation": "^0.200.0",
     "@opentelemetry/instrumentation-undici": "^0.11.0",
-    "import-in-the-middle": "^1.13.1"
+    "@t3-oss/env-core": "^0.12.0",
+    "import-in-the-middle": "^1.13.1",
+    "zod": "^3.24.2"
   },
   "devDependencies": {
     "@pagopa/eslint-config": "workspace:^",
     "@tsconfig/node20": "^20.1.5",
     "@types/node": "^20.12.2",
     "eslint": "8.57.0",
-    "shx": "^0.4.0",
+    "tsup": "^8.4.0",
     "typescript": "~5.2.2"
   },
   "scripts": {
-    "clean": "shx rm -rf dist",
-    "build": "tsc",
+    "build": "tsup",
     "lint": "eslint --fix src",
     "lint:check": "eslint src",
     "typecheck": "tsc --noEmit"

package/dist/azure-functions-hooks.js

@@ -1,26 +0,0 @@
-import { context as otelContext, propagation } from "@opentelemetry/api";
-/**
- * Registers Azure Function hooks to enable OpenTelemetry tracing.
- * These hooks extract trace context from the Azure Function context
- * and bind it to the function handler, ensuring that traces are
- * properly propagated across function invocations.
- *
- * Once the issues that causes this workaround are resolved, it will be possible
- * to add the [azure-functions-nodejs-opentelemetry](https://github.com/Azure/azure-functions-nodejs-opentelemetry/tree/main)
- * to the instrumentation package and remove this workaround.
- *
- * @param {Object} options - An object containing the Azure Functions `hook` object.
- * @param {Function} options.hook - The Azure Functions `hook` object from the `app` module.
- */
-export const registerAzureFunctionHooks = ({ hook }) => {
-    hook.preInvocation((context) => {
-        const traceContext = context.invocationContext.traceContext;
-        if (traceContext) {
-            context.functionHandler = otelContext.bind(propagation.extract(otelContext.active(), {
-                traceparent: traceContext.traceParent,
-                tracestate: traceContext.traceState,
-            }), context.functionHandler);
-        }
-    });
-};
-//# sourceMappingURL=azure-functions-hooks.js.map

package/dist/azure-functions-hooks.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"azure-functions-hooks.js","sourceRoot":"","sources":["../src/azure-functions-hooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,EAAE,IAAI,EAAc,EAAE,EAAE;IACjE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,YAAY,GAAG,OAAO,CAAC,iBAAiB,CAAC,YAAY,CAAC;QAC5D,IAAI,YAAY,EAAE;YAChB,OAAO,CAAC,eAAe,GAAG,WAAW,CAAC,IAAI,CACxC,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,EAAE;gBACxC,WAAW,EAAE,YAAY,CAAC,WAAW;gBACrC,UAAU,EAAE,YAAY,CAAC,UAAU;aACpC,CAAC,EACF,OAAO,CAAC,eAAe,CACxB,CAAC;SACH;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/azure-functions.d.mts

@@ -1 +0,0 @@
-export {};

package/dist/azure-functions.mjs

@@ -1,16 +0,0 @@
-import { createAddHookMessageChannel } from "import-in-the-middle";
-import { register } from "module";
-const { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel();
-register("import-in-the-middle/hook.mjs", import.meta.url, registerOptions);
-import { useAzureMonitor } from "@azure/monitor-opentelemetry";
-import { metrics, trace } from "@opentelemetry/api";
-import { registerInstrumentations } from "@opentelemetry/instrumentation";
-import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
-useAzureMonitor();
-registerInstrumentations({
-    instrumentations: [new UndiciInstrumentation()],
-    meterProvider: metrics.getMeterProvider(),
-    tracerProvider: trace.getTracerProvider(),
-});
-await waitForAllMessagesAcknowledged();
-//# sourceMappingURL=azure-functions.mjs.map

package/dist/azure-functions.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"azure-functions.mjs","sourceRoot":"","sources":["../src/azure-functions.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAElC,MAAM,EAAE,eAAe,EAAE,8BAA8B,EAAE,GACvD,2BAA2B,EAAE,CAAC;AAEhC,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,eAAe,EAAE,CAAC;AAElB,wBAAwB,CAAC;IACvB,gBAAgB,EAAE,CAAC,IAAI,qBAAqB,EAAE,CAAC;IAC/C,aAAa,EAAE,OAAO,CAAC,gBAAgB,EAAE;IACzC,cAAc,EAAE,KAAK,CAAC,iBAAiB,EAAE;CAC1C,CAAC,CAAC;AAEH,MAAM,8BAA8B,EAAE,CAAC"}

package/dist/azure-monitor.js

@@ -1,49 +0,0 @@
-import { useAzureMonitor } from "@azure/monitor-opentelemetry";
-import { metrics, trace } from "@opentelemetry/api";
-import { registerInstrumentations, } from "@opentelemetry/instrumentation";
-import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
-/**
- * Initialize the Azure Monitor with the given instrumentations.
- * Call this function to register the instrumentations with the Azure Monitor.
- * By default, the Undici instrumentation is included; if you need to add more,
- * you can pass them as an array of instrumentations.
- *
- * @remarks
- * This function will register the given instrumentations with the Azure Monitor.
- * It is recommended to call this function at the beginning of your application.
- *
- * @example
- * import { initAzureMonitor } from "@pagopa/azure-tracing/azure-monitor";
- *
- * initAzureMonitor();
- * @param instrumentations the list of instrumentations to register with the Azure Monitor.
- */
-export const initAzureMonitor = (instrumentations = []) => {
-    useAzureMonitor();
-    registerInstrumentations({
-        instrumentations: [
-            // instrument native node fetch
-            new UndiciInstrumentation({
-                requestHook: (span, requestInfo) => {
-                    const { method, origin, path } = requestInfo;
-                    // Default instrumented attributes don't feed well into AppInsights,
-                    // so we set them manually.
-                    span.setAttributes({
-                        "http.host": origin,
-                        "http.method": method,
-                        "http.target": path,
-                        "http.url": `${origin}${path}`,
-                    });
-                },
-                responseHook: (span, { response }) => {
-                    // Same as above, set the status code manually.
-                    span.setAttribute("http.status_code", response.statusCode);
-                },
-            }),
-            ...instrumentations,
-        ],
-        meterProvider: metrics.getMeterProvider(),
-        tracerProvider: trace.getTracerProvider(),
-    });
-};
-//# sourceMappingURL=azure-monitor.js.map

package/dist/azure-monitor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"azure-monitor.js","sourceRoot":"","sources":["../src/azure-monitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAEL,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,mBAA+C,EAAE,EACjD,EAAE;IACF,eAAe,EAAE,CAAC;IAElB,wBAAwB,CAAC;QACvB,gBAAgB,EAAE;YAChB,+BAA+B;YAC/B,IAAI,qBAAqB,CAAC;gBACxB,WAAW,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;oBACjC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC;oBAC7C,oEAAoE;oBACpE,2BAA2B;oBAC3B,IAAI,CAAC,aAAa,CAAC;wBACjB,WAAW,EAAE,MAAM;wBACnB,aAAa,EAAE,MAAM;wBACrB,aAAa,EAAE,IAAI;wBACnB,UAAU,EAAE,GAAG,MAAM,GAAG,IAAI,EAAE;qBAC/B,CAAC,CAAC;gBACL,CAAC;gBACD,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;oBACnC,+CAA+C;oBAC/C,IAAI,CAAC,YAAY,CAAC,kBAAkB,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;gBAC7D,CAAC;aACF,CAAC;YACF,GAAG,gBAAgB;SACpB;QACD,aAAa,EAAE,OAAO,CAAC,gBAAgB,EAAE;QACzC,cAAc,EAAE,KAAK,CAAC,iBAAiB,EAAE;KAC1C,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/logger.js

@@ -1,17 +0,0 @@
-import { logs } from "@opentelemetry/api-logs";
-/**
- * Emit a custom event to the Azure Monitor.
- * This function is used to emit custom events to the Azure Monitor.
- *
- * @param eventName the name of the event to emit
- * @param attributes the attributes to include with the event
- */
-export const emitCustomEvent = (eventName, attributes) => (loggerName = "ApplicationInsightsLogger") => {
-    logs.getLogger(loggerName).emit({
-        attributes: {
-            "microsoft.custom_event.name": eventName,
-            ...attributes,
-        },
-    });
-};
-//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,CAAC,SAAiB,EAAE,UAAkC,EAAE,EAAE,CAC1D,CAAC,UAAU,GAAG,2BAA2B,EAAE,EAAE;IAC3C,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;QAC9B,UAAU,EAAE;YACV,6BAA6B,EAAE,SAAS;YACxC,GAAG,UAAU;SACd;KACF,CAAC,CAAC;AACL,CAAC,CAAC"}