@ogcio/o11y-sdk-node 0.7.1 → 0.9.0

package/README.md

@@ -129,6 +129,109 @@ instrumentNode({
 });
 ```
 
+## Extension Points
+
+The SDK provides extension points for integrating with third-party observability vendors (e.g. Sentry) or adding custom processing logic.
+
+### Span Processors
+
+Add custom span processors that run before the default OTLP exporters:
+
+```typescript
+import { instrumentNode } from "@ogcio/o11y-sdk-node";
+import { MyCustomSpanProcessor } from "./my-processor";
+
+await instrumentNode({
+  collectorUrl: "http://localhost:4317",
+  serviceName: "my-service",
+
+  // Processors that run before OTLP export (e.g., vendor processors)
+  prependSpanProcessors: [new MyCustomSpanProcessor()],
+});
+```
+
+### Log Processors
+
+Similarly, add custom log record processors:
+
+```typescript
+await instrumentNode({
+  collectorUrl: "http://localhost:4317",
+  serviceName: "my-service",
+
+  prependLogProcessors: [new MyLogProcessor()],
+});
+```
+
+### Custom Sampler
+
+Wrap or replace the default sampler using `samplerWrapper`:
+
+```typescript
+import { TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+
+await instrumentNode({
+  collectorUrl: "http://localhost:4317",
+  serviceName: "my-service",
+
+  // Wrap the default sampler with custom logic
+  samplerWrapper: (_defaultSampler) => {
+    // Discard the default sampler and return your custom sampler, or wrap it and leverage it as default
+    return new MyCustomSampler();
+  },
+});
+```
+
+### Custom Context Manager
+
+Override the default context manager:
+
+```typescript
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+
+await instrumentNode({
+  collectorUrl: "http://localhost:4317",
+  serviceName: "my-service",
+
+  contextManager: new AsyncLocalStorageContextManager(), //(the current default)
+});
+```
+
+### Additional Propagators
+
+Add propagators to the composite propagator (W3CTraceContextPropagator is always included):
+
+```typescript
+import { B3Propagator } from "@opentelemetry/propagator-b3";
+
+await instrumentNode({
+  collectorUrl: "http://localhost:4317",
+  serviceName: "my-service",
+
+  additionalPropagators: [new B3Propagator()],
+});
+```
+
+### Post-Start Callback
+
+Execute code after the SDK has started:
+
+```typescript
+await instrumentNode({
+  collectorUrl: "http://localhost:4317",
+  serviceName: "my-service",
+
+  onSdkStarted: (sdk) => {
+    console.log("SDK started successfully");
+    // Perform vendor-specific validation, register additional hooks, etc.
+  },
+});
+```
+
+## Vendor Presets
+
+For common integrations, the SDK provides preset functions that configure all extension points automatically. See [Presets Documentation](./lib/presets/README.md) for details.
+
 ## Utils:
 
 - ## `withSpan`:
@@ -357,13 +460,19 @@ export type SDKLogLevel =
 
 ### Config
 
-| Parameter                    | Type                       | Description                                                                                                       |
-| :--------------------------- | :------------------------- | :---------------------------------------------------------------------------------------------------------------- |
-| `collectorUrl`               | `string`                   | **Required**. The opentelemetry collector entrypoint url, if null, instrumentation will not be activated          |
-| `serviceName`                | `string`                   | Name of your application used for the collector to group logs                                                     |
-| `diagLogLevel`               | `SDKLogLevel`              | Diagnostic log level for the internal runtime instrumentation                                                     |
-| `collectorMode`              | `single \| batch`          | Signals sending mode, default is batch for performance                                                            |
-| `enableFS`                   | `boolean`                  | **Deprecated**. Use `autoInstrumentationConfig` instead. Flag to enable or disable the tracing for node:fs module |
-| `autoInstrumentationConfig`  | `InstrumentationConfigMap` | Configuration object for auto instrumentations. Default: `{"@opentelemetry/instrumentation-fs":{enabled:false}}`  |
-| `additionalInstrumentations` | `Instrumentation[]`        | Additional custom instrumentations to be added to the NodeSDK. Default: `[]`                                      |
-| `protocol`                   | `string`                   | Type of the protocol used to send signals                                                                         |
+| Parameter                    | Type                                   | Description                                                                                                       |
+| :--------------------------- | :------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
+| `collectorUrl`               | `string`                               | **Required**. The opentelemetry collector entrypoint url, if null, instrumentation will not be activated          |
+| `serviceName`                | `string`                               | Name of your application used for the collector to group logs                                                     |
+| `diagLogLevel`               | `SDKLogLevel`                          | Diagnostic log level for the internal runtime instrumentation                                                     |
+| `collectorMode`              | `single \| batch`                      | Signals sending mode, default is batch for performance                                                            |
+| `enableFS`                   | `boolean`                              | **Deprecated**. Use `autoInstrumentationConfig` instead. Flag to enable or disable the tracing for node:fs module |
+| `autoInstrumentationConfig`  | `InstrumentationConfigMap`             | Configuration object for auto instrumentations. Default: `{"@opentelemetry/instrumentation-fs":{enabled:false}}`  |
+| `additionalInstrumentations` | `Instrumentation[]`                    | Additional custom instrumentations to be added to the NodeSDK. Default: `[]`                                      |
+| `protocol`                   | `string`                               | Type of the protocol used to send signals                                                                         |
+| `prependSpanProcessors`      | `SpanProcessor[]`                      | Span processors to run before OTLP export. Default: `[]`                                                          |
+| `prependLogProcessors`       | `LogRecordProcessor[]`                 | Log processors to run before OTLP export. Default: `[]`                                                           |
+| `samplerWrapper`             | `(defaultSampler: Sampler) => Sampler` | Function to wrap or replace the default sampler                                                                   |
+| `contextManager`             | `ContextManager`                       | Custom context manager to use                                                                                     |
+| `additionalPropagators`      | `TextMapPropagator[]`                  | Additional propagators to add to the composite propagator. Default: `[]`                                          |
+| `onSdkStarted`               | `(sdk: NodeSDK) => void`               | Callback invoked after the SDK has started                                                                        |

package/dist/sdk-core/lib/redaction/ip-redactor.js

@@ -1,17 +1,44 @@
 import { BasicRedactor } from "./basic-redactor.js";
 export class IpRedactor extends BasicRedactor {
-    static IPV4_REGEX = /(?<!\d)(?:%[0-9A-Fa-f]{2})?(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}(?:%[0-9A-Fa-f]{2})?(?!\d)/gi;
-    static IPV6_REGEX = /(?<![0-9a-f:])(?:%[0-9A-Fa-f]{2})?((?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,7}:|:(?::[0-9A-Fa-f]{1,4}){1,7}|(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,5}(?::[0-9A-Fa-f]{1,4}){1,2}|(?:[0-9A-Fa-f]{1,4}:){1,4}(?::[0-9A-Fa-f]{1,4}){1,3}|(?:[0-9A-Fa-f]{1,4}:){1,3}(?::[0-9A-Fa-f]{1,4}){1,4}|(?:[0-9A-Fa-f]{1,4}:){1,2}(?::[0-9A-Fa-f]{1,4}){1,5}|[0-9A-Fa-f]{1,4}:(?::[0-9A-Fa-f]{1,4}){1,6}|:(?::[0-9A-Fa-f]{1,4}){1,7}:?|(?:[0-9A-Fa-f]{1,4}:){1,4}:(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})){3})(?:%[0-9A-Fa-f]{2})?(?![0-9a-f:])/gi;
+    // iOS < 16.6 compatible: no lookbehind/lookahead
+    static IPV4_REGEX = /(?:%[0-9A-Fa-f]{2})?(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}(?:%[0-9A-Fa-f]{2})?/gi;
+    // Comprehensive IPv6 regex without lookbehind - matches all standard formats including :: compression
+    static IPV6_REGEX = /(?:%[0-9A-Fa-f]{2})?((?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,5}(?::[0-9A-Fa-f]{1,4}){1,2}|(?:[0-9A-Fa-f]{1,4}:){1,4}(?::[0-9A-Fa-f]{1,4}){1,3}|(?:[0-9A-Fa-f]{1,4}:){1,3}(?::[0-9A-Fa-f]{1,4}){1,4}|(?:[0-9A-Fa-f]{1,4}:){1,2}(?::[0-9A-Fa-f]{1,4}){1,5}|[0-9A-Fa-f]{1,4}:(?:(?::[0-9A-Fa-f]{1,4}){1,6})|::(?:[0-9A-Fa-f]{1,4}:){0,5}[0-9A-Fa-f]{1,4}|[0-9A-Fa-f]{1,4}::(?:[0-9A-Fa-f]{1,4}:){0,5}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){2}::(?:[0-9A-Fa-f]{1,4}:){0,4}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){3}::(?:[0-9A-Fa-f]{1,4}:){0,3}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){4}::(?:[0-9A-Fa-f]{1,4}:){0,2}[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){5}::(?:[0-9A-Fa-f]{1,4}:)?[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){6}::[0-9A-Fa-f]{1,4}|(?:[0-9A-Fa-f]{1,4}:){1,7}:|(?:[0-9A-Fa-f]{1,4}:){1,4}:(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})(?:\\.(?:25[0-5]|2[0-4]\d|1\d\d|\d{1,2})){3})(?:%[0-9A-Fa-f]{2})?/gi;
     redact(value) {
         const counters = {};
-        const redactedValue = value
-            .replace(IpRedactor.IPV4_REGEX, () => {
-            counters["IPv4"] = (counters["IPv4"] || 0) + 1;
-            return "[REDACTED IPV4]";
-        })
-            .replace(IpRedactor.IPV6_REGEX, () => {
-            counters["IPv6"] = (counters["IPv6"] || 0) + 1;
-            return "[REDACTED IPV6]";
+        // First pass: redact IPv4 with boundary checking
+        const tempValue = value.replace(IpRedactor.IPV4_REGEX, (match, ...args) => {
+            const offset = args[args.length - 2];
+            const before = offset > 0 ? value[offset - 1] : "";
+            const after = offset + match.length < value.length
+                ? value[offset + match.length]
+                : "";
+            // Check if surrounded by non-digit characters
+            const isValidBefore = !before || !/\d/.test(before);
+            const isValidAfter = !after || !/\d/.test(after);
+            if (isValidBefore && isValidAfter) {
+                counters["IPv4"] = (counters["IPv4"] || 0) + 1;
+                return "[REDACTED IPV4]";
+            }
+            return match;
+        });
+        // Second pass: redact IPv6 with boundary checking
+        const redactedValue = tempValue.replace(IpRedactor.IPV6_REGEX, (match, ...args) => {
+            const offset = args[args.length - 2];
+            const before = offset > 0 ? tempValue[offset - 1] : "";
+            const after = offset + match.length < tempValue.length
+                ? tempValue[offset + match.length]
+                : "";
+            // For IPv6:
+            // Reject if there's a colon before (indicating :::)
+            // Reject if there's a hex digit or colon after
+            const isValidBefore = !before || !/[0-9a-f:]/i.test(before);
+            const isValidAfter = !after || !/[0-9a-f:]/i.test(after);
+            if (isValidBefore && isValidAfter) {
+                counters["IPv6"] = (counters["IPv6"] || 0) + 1;
+                return "[REDACTED IPV6]";
+            }
+            return match;
         });
         return {
             redactedValue: redactedValue,

package/dist/sdk-core/lib/redaction/ppsn-redactor.js

@@ -1,11 +1,23 @@
 import { BasicRedactor } from "./basic-redactor.js";
 export class PpsnRedactor extends BasicRedactor {
-    static PPSN_REGEX = /(?<!([0-9]|[a-z]))[0-9]{7}[a-z]{1,2}(?!([0-9]|[a-z]))/gi;
+    // iOS < 16.6 compatible: no lookbehind/lookahead
+    static PPSN_REGEX = /[0-9]{7}[a-z]{1,2}/gi;
     redact(value) {
         let redactedCounter = 0;
-        const redactedValue = value.replace(PpsnRedactor.PPSN_REGEX, (_) => {
-            redactedCounter++;
-            return "[REDACTED PPSN]";
+        // Boundary checking to replace lookbehind/lookahead
+        const redactedValue = value.replace(PpsnRedactor.PPSN_REGEX, (match, offset) => {
+            const before = offset > 0 ? value[offset - 1] : "";
+            const after = offset + match.length < value.length
+                ? value[offset + match.length]
+                : "";
+            // Check if surrounded by non-alphanumeric characters
+            const isValidBefore = !before || !/[0-9a-z]/i.test(before);
+            const isValidAfter = !after || !/[0-9a-z]/i.test(after);
+            if (isValidBefore && isValidAfter) {
+                redactedCounter++;
+                return "[REDACTED PPSN]";
+            }
+            return match;
         });
         return {
             redactedValue: redactedValue,

package/dist/sdk-node/index.d.ts

@@ -1,5 +1,6 @@
 import type { NodeSDK } from "@opentelemetry/sdk-node";
 import buildNodeInstrumentation from "./lib/instrumentation.node.js";
+export type { SpanKind, SpanStatus, SpanStatusCode, TraceFlags, } from "@opentelemetry/api";
 export type * from "./lib/index.js";
 export type { NodeSDK };
 export { buildNodeInstrumentation as instrumentNode };

package/dist/sdk-node/lib/index.d.ts

@@ -1,7 +1,11 @@
 import type { Metadata } from "@grpc/grpc-js";
-import { BasicRedactor } from "../../sdk-core/lib/redaction/basic-redactor.js";
+import { BasicRedactor } from "../../sdk-core/lib/index.js";
 import { InstrumentationConfigMap } from "@opentelemetry/auto-instrumentations-node";
 import { Instrumentation } from "@opentelemetry/instrumentation";
+import { Sampler, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { ContextManager, TextMapPropagator } from "@opentelemetry/api";
+import { NodeSDK } from "@opentelemetry/sdk-node";
 export interface NodeSDKConfig {
     /**
      * The opentelemetry collector entrypoint GRPC url.
@@ -127,6 +131,43 @@ export interface NodeSDKConfig {
          */
         enabled: boolean;
     };
+    /**
+     * Additional span processors to prepend to the processing pipeline.
+     * These run before the default OTLP exporters.
+     * You may use this for vendor-specific processors (e.g. sentry).
+     * @default []
+     */
+    prependSpanProcessors?: SpanProcessor[];
+    /**
+     * Additional log record processors to prepend to the pipeline.
+     * @default []
+     */
+    prependLogProcessors?: LogRecordProcessor[];
+    /**
+     * Custom sampler factory function.
+     * Receives the default o11y sampler and should return the sampler to use.
+     * You may use this to wrap the default sampler with vendor-specific samplers.
+     *
+     * @default undefined (uses default sampler)
+     */
+    samplerWrapper?: (defaultSampler: Sampler) => Sampler;
+    /**
+     * Custom context manager to use, required by some vendors (e.g. sentry requires its own SentryContextManager).
+     * @default undefined (uses AsyncLocalStorageContextManager from otel)
+     */
+    contextManager?: ContextManager;
+    /**
+     * Additional propagators to include in the composite propagator.
+     * W3CTraceContextPropagator is always included by default.
+     * @default []
+     */
+    additionalPropagators?: TextMapPropagator[];
+    /**
+     * Callback function that is invoked once the SDK has been started.
+     *
+     * @param sdk The started NodeSDK instance.
+     */
+    onSdkStarted?: (sdk: NodeSDK) => void;
 }
 export interface SamplerCondition {
     type: "endsWith" | "includes" | "equals";

package/dist/sdk-node/lib/instrumentation.node.js

@@ -1,6 +1,6 @@
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { CompositePropagator, W3CTraceContextPropagator, } from "@opentelemetry/core";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { AlwaysOffSampler, ParentBasedSampler, TraceIdRatioBasedSampler, } from "@opentelemetry/sdk-trace-base";
 import { setNodeSdkConfig } from "./config-manager.js";
@@ -25,14 +25,19 @@ export default async function buildNodeInstrumentation(config) {
     }
     // Init configManager to make it available to all o11y utils.
     setNodeSdkConfig(config);
+    // Build base sampler
     const urlSampler = new UrlSampler(config.ignoreUrls, new TraceIdRatioBasedSampler(config.traceRatio ?? 1));
-    const mainSampler = new ParentBasedSampler({
+    const defaultSampler = new ParentBasedSampler({
         root: urlSampler,
         remoteParentSampled: urlSampler,
         remoteParentNotSampled: new AlwaysOffSampler(),
         localParentSampled: urlSampler,
         localParentNotSampled: new AlwaysOffSampler(),
     });
+    // Allow sampler customization via config
+    const finalSampler = config.samplerWrapper
+        ? config.samplerWrapper(defaultSampler)
+        : defaultSampler;
     diag.setLogger(new DiagConsoleLogger(), config.diagLogLevel ? DiagLogLevel[config.diagLogLevel] : DiagLogLevel.INFO);
     try {
         let exporter;
@@ -45,16 +50,32 @@ export default async function buildNodeInstrumentation(config) {
         else {
             exporter = await buildGrpcExporters(config);
         }
+        // Build span processors with custom processors from config
+        const spanProcessors = [
+            ...(config.prependSpanProcessors ?? []),
+            ...exporter.spans,
+        ];
+        // Build log processors with custom processors from config
+        const logProcessors = [
+            ...(config.prependLogProcessors ?? []),
+            ...exporter.logs,
+        ];
         const sdk = new NodeSDK({
             resourceDetectors: [
                 new ObservabilityResourceDetector(config.resourceAttributes),
             ],
-            spanProcessors: exporter.spans,
+            spanProcessors,
             serviceName: config.serviceName,
             metricReaders: [exporter.metrics],
-            logRecordProcessors: exporter.logs,
-            sampler: mainSampler,
-            textMapPropagator: new W3CTraceContextPropagator(),
+            logRecordProcessors: logProcessors,
+            sampler: finalSampler,
+            textMapPropagator: new CompositePropagator({
+                propagators: [
+                    new W3CTraceContextPropagator(),
+                    ...(config.additionalPropagators ?? []),
+                ],
+            }),
+            contextManager: config.contextManager,
             instrumentations: [
                 getNodeAutoInstrumentations(config.autoInstrumentationConfig ?? {
                     "@opentelemetry/instrumentation-fs": {
@@ -67,6 +88,7 @@ export default async function buildNodeInstrumentation(config) {
         sdk.start();
         console.log("NodeJS OpenTelemetry instrumentation started successfully.");
         _shutdownHook(sdk);
+        config.onSdkStarted?.(sdk);
         return sdk;
     }
     catch (error) {

package/dist/sdk-node/lib/presets/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./sentry-next.js";
+export * from "./sentry-node.js";

package/dist/sdk-node/lib/presets/index.js

@@ -0,0 +1,2 @@
+export * from "./sentry-next.js";
+export * from "./sentry-node.js";

package/dist/sdk-node/lib/presets/sentry-next.d.ts

@@ -0,0 +1,29 @@
+import type { NodeSDKConfig } from "../index.js";
+import type { NodeOptions as SentryNextjsOptions } from "@sentry/nextjs";
+/**
+ * Options for the withSentryNextjs preset function.
+ */
+export interface WithSentryNextjsOptions {
+    /**
+     * Sentry-specific configuration options for Next.js.
+     * Passed to Sentry.init() with skipOpenTelemetrySetup: true.
+     *
+     * Uses NodeOptions from @sentry/nextjs (server-side configuration).
+     */
+    sentryOptions?: SentryNextjsOptions;
+    /**
+     * If true, Sentry's sampling logic (tracesSampleRate/tracesSampler) takes precedence.
+     * If false, o11y's sampler handles all decisions and Sentry receives all sampled traces.
+     *
+     * @default false
+     */
+    useSentrySampling?: boolean;
+}
+/**
+ * Enhances a NodeSDKConfig with Sentry integration for Next.js server-side.
+ *
+ * includes Next.js-specific integrations
+ * filters Next.js internal spans (static assets, _next routes, etc...)
+ * nextjs proper source map resolution
+ */
+export declare function withSentryNextjs(config: NodeSDKConfig, options?: WithSentryNextjsOptions): Promise<NodeSDKConfig>;

package/dist/sdk-node/lib/presets/sentry-next.js

@@ -0,0 +1,76 @@
+/**
+ * Enhances a NodeSDKConfig with Sentry integration for Next.js server-side.
+ *
+ * includes Next.js-specific integrations
+ * filters Next.js internal spans (static assets, _next routes, etc...)
+ * nextjs proper source map resolution
+ */
+export async function withSentryNextjs(config, options = {}) {
+    const { sentryOptions = {}, useSentrySampling = false } = options;
+    const components = await buildSentryNextjsComponents(sentryOptions, useSentrySampling);
+    return {
+        ...config,
+        // Prepend SentrySpanProcessor so it processes spans before OTLP export
+        prependSpanProcessors: [
+            components.spanProcessor,
+            ...(config.prependSpanProcessors ?? []),
+        ],
+        // Wrap sampler with SentrySampler, using o11y's sampler as fallback
+        samplerWrapper: (defaultSampler) => {
+            // Chain with any existing wrapper
+            const baseSampler = config.samplerWrapper
+                ? config.samplerWrapper(defaultSampler)
+                : defaultSampler;
+            return components.sampler(baseSampler);
+        },
+        // Add SentryPropagator for distributed tracing
+        additionalPropagators: [
+            components.propagator,
+            ...(config.additionalPropagators ?? []),
+        ],
+        // Use SentryContextManager for proper async context tracking
+        contextManager: config.contextManager ?? components.contextManager,
+        // Validate Sentry setup after SDK starts
+        onSdkStarted: (sdk) => {
+            components.validate();
+            config.onSdkStarted?.(sdk);
+        },
+    };
+}
+/**
+ * Builds Sentry OTEL components for Next.js by dynamically importing @sentry packages.
+ * This keeps @sentry/* as optional peer dependencies.
+ */
+async function buildSentryNextjsComponents(sentryOptions, useSentrySampling = false) {
+    // Dynamic imports to keep @sentry/* as optional peer dependencies
+    const Sentry = await import("@sentry/nextjs");
+    const SentryOtel = await import("@sentry/opentelemetry");
+    // Destructure common options to be defaulted, pass rest to Sentry.init
+    const { dsn, environment, tracesSampleRate, tracesSampler, integrations, sendDefaultPii, enableLogs, ...restOptions } = sentryOptions;
+    Sentry.init({
+        dsn: dsn ?? process.env.SENTRY_DSN,
+        environment: environment ?? process.env.SENTRY_ENV ?? process.env.NODE_ENV,
+        skipOpenTelemetrySetup: true,
+        // Sentry Next.js defaults (which include distDirRewriteFramesIntegration, httpIntegration, etc...)
+        integrations: integrations ?? [],
+        tracesSampleRate: useSentrySampling ? (tracesSampleRate ?? 1.0) : 1.0,
+        tracesSampler: useSentrySampling ? tracesSampler : undefined,
+        sendDefaultPii: sendDefaultPii ?? false,
+        enableLogs: enableLogs ?? true,
+        // Pass through any additional options
+        ...restOptions,
+    });
+    const sentryClient = Sentry.getClient();
+    if (!sentryClient) {
+        console.warn("[@ogcio/o11y-sdk-node] Unable to initialize Sentry client for Next.js. Telemetry may not work as expected.");
+    }
+    return {
+        spanProcessor: new SentryOtel.SentrySpanProcessor(),
+        sampler: (fallbackSampler) => sentryClient
+            ? new SentryOtel.SentrySampler(sentryClient)
+            : fallbackSampler,
+        propagator: new SentryOtel.SentryPropagator(),
+        contextManager: new Sentry.SentryContextManager(),
+        validate: Sentry.validateOpenTelemetrySetup,
+    };
+}

package/dist/sdk-node/lib/presets/sentry-node.d.ts

@@ -0,0 +1,25 @@
+import { NodeSDKConfig } from "../index.js";
+import type { NodeOptions as SentryNodeOptions } from "@sentry/node";
+/**
+ * Options for the withSentry preset function.
+ */
+export interface WithSentryOptions {
+    /**
+     * Sentry-specific configuration options.
+     * Passed to Sentry.init() with skipOpenTelemetrySetup: true.
+     */
+    sentryOptions?: SentryNodeOptions;
+    /**
+     * If true, Sentry's sampling logic (tracesSampleRate/tracesSampler) takes precedence.
+     * If false, o11y's sampler handles all decisions and Sentry receives all sampled traces.
+     *
+     * @default false
+     */
+    useSentrySampling?: boolean;
+}
+/**
+ * Enhances a NodeSDKConfig with Sentry for Node integration.
+ *
+ * Includes sentry own processors and context management.
+ */
+export declare function withSentry(config: NodeSDKConfig, options?: WithSentryOptions): Promise<NodeSDKConfig>;

package/dist/sdk-node/lib/presets/sentry-node.js

@@ -0,0 +1,72 @@
+/**
+ * Enhances a NodeSDKConfig with Sentry for Node integration.
+ *
+ * Includes sentry own processors and context management.
+ */
+export async function withSentry(config, options = {}) {
+    const { sentryOptions = {}, useSentrySampling = true } = options;
+    const components = await buildSentryComponents(sentryOptions, useSentrySampling);
+    return {
+        ...config,
+        prependSpanProcessors: [
+            components.spanProcessor,
+            ...(config.prependSpanProcessors ?? []),
+        ],
+        // Wrap sampler with SentrySampler, using o11y's sampler as fallback
+        samplerWrapper: (defaultSampler) => {
+            // Chain with any existing wrapper
+            const baseSampler = config.samplerWrapper
+                ? config.samplerWrapper(defaultSampler)
+                : defaultSampler;
+            return components.sampler(baseSampler);
+        },
+        additionalPropagators: [
+            components.propagator,
+            ...(config.additionalPropagators ?? []),
+        ],
+        // Sentry own async context tracking
+        contextManager: config.contextManager ?? components.contextManager,
+        onSdkStarted: components.validate,
+    };
+}
+/**
+ * Builds Sentry OTEL components by dynamically importing @sentry packages.
+ * This keeps @sentry/* as optional peer dependencies.
+ */
+async function buildSentryComponents(sentryOptions, useSentrySampling = false) {
+    // Dynamic imports to keep @sentry/* as optional peer dependencies
+    const Sentry = await import("@sentry/node");
+    const SentryOtel = await import("@sentry/opentelemetry");
+    // Destructure common options to be defaulted, pass rest to Sentry.init
+    const { dsn, environment, tracesSampleRate, tracesSampler, integrations, sendDefaultPii, enableLogs, ...restOptions } = sentryOptions;
+    // Initialize Sentry with skipOpenTelemetrySetup
+    Sentry.init({
+        dsn: dsn ?? process.env.SENTRY_DSN,
+        environment: environment ?? process.env.SENTRY_ENV ?? process.env.NODE_ENV,
+        skipOpenTelemetrySetup: true,
+        integrations: integrations ?? [
+            Sentry.redisIntegration(),
+            Sentry.extraErrorDataIntegration(),
+            Sentry.postgresIntegration(),
+            Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
+        ],
+        tracesSampleRate: useSentrySampling ? (tracesSampleRate ?? 1.0) : 1.0,
+        tracesSampler: useSentrySampling ? tracesSampler : undefined,
+        sendDefaultPii: sendDefaultPii ?? false,
+        enableLogs: enableLogs ?? true,
+        ...restOptions,
+    });
+    const sentryClient = Sentry.getClient();
+    if (!sentryClient) {
+        console.warn("Unable to initialize Sentry client. Telemetry may not work as expected.");
+    }
+    return {
+        spanProcessor: new SentryOtel.SentrySpanProcessor(),
+        sampler: (fallbackSampler) => sentryClient
+            ? new SentryOtel.SentrySampler(sentryClient)
+            : fallbackSampler,
+        propagator: new SentryOtel.SentryPropagator(),
+        contextManager: new Sentry.SentryContextManager(),
+        validate: Sentry.validateOpenTelemetrySetup,
+    };
+}

package/dist/sdk-node/lib/processor/nextjs-span-processor.d.ts

@@ -1,6 +1,5 @@
-import { Context } from "@opentelemetry/api";
 import { Span } from "@opentelemetry/sdk-trace-base";
 import { OnEndingHookSpanProcessor } from "./on-ending-hook-span-processor.js";
 export declare class NextJsSpanProcessor extends OnEndingHookSpanProcessor {
-    onEnding(span: Span, _context: Context): void;
+    onEnding(span: Span): void;
 }

package/dist/sdk-node/lib/processor/nextjs-span-processor.js

@@ -1,7 +1,7 @@
 import { SpanStatusCode } from "@opentelemetry/api";
 import { OnEndingHookSpanProcessor } from "./on-ending-hook-span-processor.js";
 export class NextJsSpanProcessor extends OnEndingHookSpanProcessor {
-    onEnding(span, _context) {
+    onEnding(span) {
         // ref. https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/quickstart/nextjs/#instrument-the-nextjs-backend
         if (span.name.startsWith("GET /_next/static")) {
             span.updateName("GET /_next/static");

package/dist/sdk-node/lib/processor/on-ending-hook-span-processor.d.ts

@@ -27,9 +27,8 @@ export declare abstract class OnEndingHookSpanProcessor implements SpanProcessor
     /**
      * Hook method called just before a span is ended.
      * @param span The span that is about to end.
-     * @param context The context in which the span is ending.
      */
-    abstract onEnding(span: Span, context: Context): void;
+    abstract onEnding(span: Span): void;
     onStart(span: Span, _context: Context): void;
     onEnd(_span: ReadableSpan): void;
     forceFlush(): Promise<void>;

package/dist/sdk-node/lib/processor/on-ending-hook-span-processor.js

@@ -27,7 +27,7 @@ export class OnEndingHookSpanProcessor {
         const originalEnd = span.end.bind(span);
         // Wrap the end method to inject custom logic before ending the span
         span.end = (endTime) => {
-            this.onEnding(span, _context);
+            this.onEnding(span);
             originalEnd(endTime);
         };
     }

package/dist/sdk-node/lib/processor/pseudo-profiling-span-processor.d.ts

@@ -11,7 +11,7 @@ import { OnEndingHookSpanProcessor } from "./on-ending-hook-span-processor.js";
 export declare class PseudoProfilingSpanProcessor extends OnEndingHookSpanProcessor {
     private _spanProfilingData;
     onStart(span: Span, _context: Context): void;
-    onEnding(span: Span, _context: Context): void;
+    onEnding(span: Span): void;
     /**
      * Captures profiling data and sets attributes on the span.
      * Called just before the span is ended, while it's still writable.

package/dist/sdk-node/lib/processor/pseudo-profiling-span-processor.js

@@ -19,7 +19,7 @@ export class PseudoProfilingSpanProcessor extends OnEndingHookSpanProcessor {
             memoryUsageStart,
         });
     }
-    onEnding(span, _context) {
+    onEnding(span) {
         this._captureProfilingData(span);
     }
     /**

package/dist/sdk-node/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ogcio/o11y-sdk-node",
-    "version": "0.7.1",
+    "version": "0.9.0",
     "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
     "main": "dist/index.js",
     "type": "module",
@@ -17,7 +17,8 @@
     },
     "exports": {
         ".": "./dist/sdk-node/index.js",
-        "./*": "./dist/*.js"
+        "./*": "./dist/*.js",
+        "./presets/*": "./dist/sdk-node/lib/presets/*.js"
     },
     "files": [
         "dist"
@@ -35,31 +36,48 @@
     "dependencies": {
         "@grpc/grpc-js": "1.14.3",
         "@opentelemetry/api": "1.9.0",
-        "@opentelemetry/api-logs": "0.208.0",
-        "@opentelemetry/auto-instrumentations-node": "0.67.2",
-        "@opentelemetry/core": "2.2.0",
-        "@opentelemetry/exporter-logs-otlp-grpc": "0.208.0",
-        "@opentelemetry/exporter-logs-otlp-http": "0.208.0",
-        "@opentelemetry/exporter-metrics-otlp-grpc": "0.208.0",
-        "@opentelemetry/exporter-metrics-otlp-http": "0.208.0",
-        "@opentelemetry/exporter-trace-otlp-grpc": "0.208.0",
-        "@opentelemetry/exporter-trace-otlp-http": "0.208.0",
-        "@opentelemetry/instrumentation": "0.208.0",
-        "@opentelemetry/otlp-exporter-base": "0.208.0",
-        "@opentelemetry/resources": "2.2.0",
-        "@opentelemetry/sdk-logs": "0.208.0",
-        "@opentelemetry/sdk-metrics": "2.2.0",
-        "@opentelemetry/sdk-node": "0.208.0",
-        "@opentelemetry/sdk-trace-base": "2.2.0"
+        "@opentelemetry/api-logs": "0.211.0",
+        "@opentelemetry/auto-instrumentations-node": "0.69.0",
+        "@opentelemetry/context-async-hooks": "2.5.0",
+        "@opentelemetry/core": "2.5.0",
+        "@opentelemetry/exporter-logs-otlp-grpc": "0.211.0",
+        "@opentelemetry/exporter-logs-otlp-http": "0.211.0",
+        "@opentelemetry/exporter-metrics-otlp-grpc": "0.211.0",
+        "@opentelemetry/exporter-metrics-otlp-http": "0.211.0",
+        "@opentelemetry/exporter-trace-otlp-grpc": "0.211.0",
+        "@opentelemetry/exporter-trace-otlp-http": "0.211.0",
+        "@opentelemetry/instrumentation": "0.211.0",
+        "@opentelemetry/otlp-exporter-base": "0.211.0",
+        "@opentelemetry/resources": "2.5.0",
+        "@opentelemetry/sdk-logs": "0.211.0",
+        "@opentelemetry/sdk-metrics": "2.5.0",
+        "@opentelemetry/sdk-node": "0.211.0",
+        "@opentelemetry/sdk-trace-base": "2.5.0"
     },
     "devDependencies": {
-        "@types/node": "25.0.2",
-        "@vitest/coverage-v8": "4.0.15",
+        "@types/node": "25.0.10",
+        "@vitest/coverage-v8": "4.0.18",
         "tsx": "4.21.0",
         "typescript": "5.9.3",
-        "vitest": "4.0.15"
+        "vitest": "4.0.18"
     },
     "engines": {
         "node": ">=20.6.0"
+    },
+    "peerDependencies": {
+        "@sentry/nextjs": "^10.36.0",
+        "@sentry/node": "^10.36.0",
+        "@sentry/opentelemetry": "^10.36.0"
+    },
+    "peerDependenciesMeta": {
+        "@sentry/opentelemetry": {
+            "optional": true
+        },
+        "@sentry/node": {
+            "optional": true
+        },
+        "@sentry/nextjs": {
+            "optional": true
+        }
     }
 }

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@ogcio/o11y-sdk-node",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Opentelemetry standard instrumentation SDK for NodeJS based project",
   "main": "dist/index.js",
   "type": "module",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest",
+    "prepublishOnly": "pnpm i && rm -rf dist && tsc -p tsconfig.json",
+    "test:unit": "vitest --project unit",
+    "test:integration": "pnpm test:integration:setup && pnpm test:integration:run && pnpm test:integration:assert && pnpm test:integration:teardown",
+    "test:integration:setup": "sh ./test/integration/setup.sh integration",
+    "test:integration:run": "pnpm --filter @ogcio/o11y run prepare:integration",
+    "test:integration:assert": "vitest --project integration",
+    "test:integration:teardown": "sh ./test/integration/teardown.sh integration"
+  },
   "exports": {
     ".": "./dist/sdk-node/index.js",
-    "./*": "./dist/*.js"
+    "./*": "./dist/*.js",
+    "./presets/*": "./dist/sdk-node/lib/presets/*.js"
   },
   "files": [
     "dist"
@@ -24,41 +36,48 @@
   "dependencies": {
     "@grpc/grpc-js": "1.14.3",
     "@opentelemetry/api": "1.9.0",
-    "@opentelemetry/api-logs": "0.208.0",
-    "@opentelemetry/auto-instrumentations-node": "0.67.2",
-    "@opentelemetry/core": "2.2.0",
-    "@opentelemetry/exporter-logs-otlp-grpc": "0.208.0",
-    "@opentelemetry/exporter-logs-otlp-http": "0.208.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "0.208.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "0.208.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "0.208.0",
-    "@opentelemetry/exporter-trace-otlp-http": "0.208.0",
-    "@opentelemetry/instrumentation": "0.208.0",
-    "@opentelemetry/otlp-exporter-base": "0.208.0",
-    "@opentelemetry/resources": "2.2.0",
-    "@opentelemetry/sdk-logs": "0.208.0",
-    "@opentelemetry/sdk-metrics": "2.2.0",
-    "@opentelemetry/sdk-node": "0.208.0",
-    "@opentelemetry/sdk-trace-base": "2.2.0"
+    "@opentelemetry/api-logs": "0.211.0",
+    "@opentelemetry/auto-instrumentations-node": "0.69.0",
+    "@opentelemetry/context-async-hooks": "2.5.0",
+    "@opentelemetry/core": "2.5.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "0.211.0",
+    "@opentelemetry/exporter-logs-otlp-http": "0.211.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "0.211.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "0.211.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "0.211.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.211.0",
+    "@opentelemetry/instrumentation": "0.211.0",
+    "@opentelemetry/otlp-exporter-base": "0.211.0",
+    "@opentelemetry/resources": "2.5.0",
+    "@opentelemetry/sdk-logs": "0.211.0",
+    "@opentelemetry/sdk-metrics": "2.5.0",
+    "@opentelemetry/sdk-node": "0.211.0",
+    "@opentelemetry/sdk-trace-base": "2.5.0"
   },
   "devDependencies": {
-    "@types/node": "25.0.2",
-    "@vitest/coverage-v8": "4.0.15",
+    "@types/node": "25.0.10",
+    "@vitest/coverage-v8": "4.0.18",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.15"
+    "vitest": "4.0.18"
   },
   "engines": {
     "node": ">=20.6.0"
   },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
-    "test": "vitest",
-    "test:unit": "vitest --project unit",
-    "test:integration": "pnpm test:integration:setup && pnpm test:integration:run && pnpm test:integration:assert && pnpm test:integration:teardown",
-    "test:integration:setup": "sh ./test/integration/setup.sh integration",
-    "test:integration:run": "pnpm --filter @ogcio/o11y run prepare:integration",
-    "test:integration:assert": "vitest --project integration",
-    "test:integration:teardown": "sh ./test/integration/teardown.sh integration"
+  "peerDependencies": {
+    "@sentry/nextjs": "^10.36.0",
+    "@sentry/node": "^10.36.0",
+    "@sentry/opentelemetry": "^10.36.0"
+  },
+  "peerDependenciesMeta": {
+    "@sentry/opentelemetry": {
+      "optional": true
+    },
+    "@sentry/node": {
+      "optional": true
+    },
+    "@sentry/nextjs": {
+      "optional": true
+    }
   }
-}
+}