@adonisjs/otel 1.0.0-next.0

package/build/src/otel.js

@@ -0,0 +1,329 @@
+import { getNodeAutoInstrumentations, } from '@opentelemetry/auto-instrumentations-node';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ConsoleSpanExporter, ParentBasedSampler, SimpleSpanProcessor, TraceIdRatioBasedSampler, } from '@opentelemetry/sdk-trace-base';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { ATTR_DEPLOYMENT_ENVIRONMENT_NAME, ATTR_SERVICE_INSTANCE_ID, } from '@opentelemetry/semantic-conventions/incubating';
+import { HttpContext } from '@adonisjs/core/http';
+/**
+ * OpenTelemetry SDK manager for AdonisJS.
+ *
+ * Provides sensible defaults and easy configuration for OpenTelemetry
+ * while allowing full customization when needed.
+ *
+ * @example
+ * ```ts
+ * import { OtelManager } from '@adonisjs/otel'
+ * import config from '#config/otel'
+ *
+ * const manager = OtelManager.create(config)
+ * manager?.start()
+ *
+ * // Later, on shutdown
+ * await manager?.shutdown()
+ * ```
+ */
+export class OtelManager {
+    static DEFAULT_IGNORED_URLS = [
+        '/health',
+        '/healthz',
+        '/internal/healthz',
+        '/ready',
+        '/readiness',
+        '/metrics',
+        '/internal/metrics',
+        '/favicon.ico',
+    ];
+    static #instance = null;
+    sdk;
+    serviceName;
+    serviceVersion;
+    environment;
+    #config;
+    constructor(config) {
+        this.#config = config;
+        this.serviceName = this.#resolveServiceName();
+        this.serviceVersion = this.#resolveServiceVersion();
+        this.environment = this.#resolveEnvironment();
+        this.sdk = this.#createSdk();
+    }
+    /**
+     * Resolve the service name from config or environment
+     */
+    #resolveServiceName() {
+        return (this.#config.serviceName ||
+            process.env.OTEL_SERVICE_NAME ||
+            process.env.APP_NAME ||
+            'unknown_service');
+    }
+    /**
+     * Resolve the service version from config or environment
+     */
+    #resolveServiceVersion() {
+        return this.#config.serviceVersion || process.env.APP_VERSION || '0.0.0';
+    }
+    /**
+     * Resolve the environment from config or environment
+     */
+    #resolveEnvironment() {
+        return this.#config.environment || process.env.APP_ENV || 'development';
+    }
+    /**
+     * Build the OpenTelemetry Resource with service metadata
+     */
+    #buildResource() {
+        return resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: this.serviceName,
+            [ATTR_SERVICE_VERSION]: this.serviceVersion,
+            [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: this.environment,
+            [ATTR_SERVICE_INSTANCE_ID]: process.env.HOSTNAME || crypto.randomUUID(),
+            ...this.#config.resourceAttributes,
+        });
+    }
+    /**
+     * Get the resolved list of ignored URLs from HTTP instrumentation config
+     */
+    #getIgnoredUrls(httpConfig) {
+        const userUrls = httpConfig?.ignoredUrls || [];
+        const mergeWithDefaults = httpConfig?.mergeIgnoredUrls !== false;
+        if (!mergeWithDefaults) {
+            return userUrls;
+        }
+        return [...OtelManager.DEFAULT_IGNORED_URLS, ...userUrls];
+    }
+    /**
+     * Check if a URL should be ignored based on the ignored URLs list.
+     * Supports exact matches and wildcard patterns (e.g., '/internal/*')
+     */
+    #shouldIgnoreUrl(url, ignoredUrls) {
+        if (!url)
+            return false;
+        return ignoredUrls.some((pattern) => {
+            if (pattern.endsWith('/*')) {
+                const prefix = pattern.slice(0, -1);
+                return url.startsWith(prefix);
+            }
+            return url.startsWith(pattern);
+        });
+    }
+    /**
+     * Check if a value is an Instrumentation instance
+     */
+    #isInstrumentationInstance(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'instrumentationName' in value &&
+            typeof value.instrumentationName === 'string');
+    }
+    /**
+     * Check if a value is a "disabled" config
+     */
+    #isDisabledConfig(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'enabled' in value &&
+            value.enabled === false);
+    }
+    /**
+     * Process user instrumentation configuration
+     */
+    #processUserInstrumentations(userConfig) {
+        const customInstances = [];
+        const disabledSet = new Set();
+        const configOverrides = {};
+        let httpConfig;
+        let pinoConfig;
+        if (!userConfig)
+            return { customInstances, disabledSet, configOverrides, httpConfig, pinoConfig };
+        for (const [name, value] of Object.entries(userConfig)) {
+            if (this.#isDisabledConfig(value)) {
+                disabledSet.add(name);
+                continue;
+            }
+            if (this.#isInstrumentationInstance(value)) {
+                customInstances.push(value);
+                disabledSet.add(name);
+                continue;
+            }
+            if (name === '@opentelemetry/instrumentation-http') {
+                httpConfig = value;
+                continue;
+            }
+            if (name === '@opentelemetry/instrumentation-pino') {
+                pinoConfig = value;
+                continue;
+            }
+            configOverrides[name] = value;
+        }
+        return { customInstances, disabledSet, configOverrides, httpConfig, pinoConfig };
+    }
+    /**
+     * Build the base instrumentation configuration
+     */
+    #buildBaseInstrumentationConfig() {
+        return {
+            '@opentelemetry/instrumentation-net': { enabled: false },
+            '@opentelemetry/instrumentation-dns': { enabled: false },
+            '@opentelemetry/instrumentation-socket.io': { enabled: false },
+            '@opentelemetry/instrumentation-pg': { enabled: false },
+            '@opentelemetry/instrumentation-mysql': { enabled: false },
+            '@opentelemetry/instrumentation-mysql2': { enabled: false },
+        };
+    }
+    /**
+     * Build instrumentations from user config merged with defaults
+     */
+    #buildInstrumentations() {
+        const { customInstances, disabledSet, configOverrides, httpConfig, pinoConfig } = this.#processUserInstrumentations(this.#config.instrumentations);
+        const mergedConfig = this.#buildBaseInstrumentationConfig();
+        for (const [name, config] of Object.entries(configOverrides)) {
+            mergedConfig[name] = {
+                ...mergedConfig[name],
+                ...config,
+            };
+        }
+        for (const name of disabledSet) {
+            mergedConfig[name] = { enabled: false };
+        }
+        this.#applyHttpInstrumentationConfig(mergedConfig, httpConfig);
+        this.#applyPinoInstrumentationConfig(mergedConfig, pinoConfig);
+        const autoInstrumentations = getNodeAutoInstrumentations(mergedConfig);
+        return [...autoInstrumentations, ...customInstances];
+    }
+    /**
+     * Apply HTTP instrumentation configuration with smart merging of ignoreIncomingRequestHook
+     */
+    #applyHttpInstrumentationConfig(mergedConfig, userHttpConfig) {
+        const httpKey = '@opentelemetry/instrumentation-http';
+        const currentConfig = mergedConfig[httpKey];
+        if (currentConfig && 'enabled' in currentConfig && currentConfig.enabled === false) {
+            return;
+        }
+        const ignoredUrls = this.#getIgnoredUrls(userHttpConfig);
+        const userIgnoreHook = userHttpConfig?.ignoreIncomingRequestHook;
+        mergedConfig[httpKey] = {
+            ...currentConfig,
+            ...userHttpConfig,
+            ignoreIncomingRequestHook: (req) => {
+                if (this.#shouldIgnoreUrl(req.url, ignoredUrls))
+                    return true;
+                if (userIgnoreHook)
+                    return userIgnoreHook(req);
+                return false;
+            },
+        };
+    }
+    /**
+     * Apply Pino instrumentation configuration with smart merging of logHook
+     */
+    #applyPinoInstrumentationConfig(mergedConfig, userPinoConfig) {
+        const pinoKey = '@opentelemetry/instrumentation-pino';
+        const currentConfig = mergedConfig[pinoKey];
+        if (currentConfig && 'enabled' in currentConfig && currentConfig.enabled === false) {
+            return;
+        }
+        const userLogHook = userPinoConfig?.logHook;
+        const internalLogHook = (span) => {
+            const httpContext = HttpContext.get();
+            span.setAttribute('http.route', httpContext?.route?.pattern || '');
+        };
+        mergedConfig[pinoKey] = {
+            ...currentConfig,
+            ...userPinoConfig,
+            logHook: (span, record) => {
+                internalLogHook(span);
+                if (userLogHook)
+                    userLogHook(span, record);
+            },
+        };
+    }
+    /**
+     * Build sampler from samplingRatio if no explicit sampler is provided
+     */
+    #buildSampler() {
+        if (this.#config.sampler)
+            return this.#config.sampler;
+        if (this.#config.samplingRatio !== undefined) {
+            const ratio = Math.max(0, Math.min(1, this.#config.samplingRatio));
+            return new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(ratio) });
+        }
+        return undefined;
+    }
+    /**
+     * Build span processors, including debug console exporter if enabled
+     */
+    #buildSpanProcessors() {
+        const processors = this.#config.spanProcessors ? [...this.#config.spanProcessors] : [];
+        if (this.#config.debug)
+            processors.push(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+        return processors.length > 0 ? processors : undefined;
+    }
+    /**
+     * Create the NodeSDK instance with all configuration
+     */
+    #createSdk() {
+        const resource = this.#buildResource();
+        const instrumentations = this.#buildInstrumentations();
+        const sampler = this.#buildSampler();
+        const spanProcessors = this.#buildSpanProcessors();
+        return new NodeSDK({
+            ...this.#config,
+            resource,
+            serviceName: this.serviceName,
+            instrumentations,
+            ...(sampler && { sampler }),
+            ...(spanProcessors && { spanProcessors }),
+        });
+    }
+    /**
+     * Start the OpenTelemetry SDK
+     */
+    start() {
+        this.sdk.start();
+    }
+    /**
+     * Gracefully shutdown the OpenTelemetry SDK
+     */
+    async shutdown() {
+        await this.sdk.shutdown();
+    }
+    /**
+     * Check if OpenTelemetry should be enabled based on config.
+     * Defaults to false when NODE_ENV === 'test'.
+     */
+    static isEnabled(config) {
+        if (config.enabled !== undefined)
+            return config.enabled;
+        return process.env.NODE_ENV !== 'test';
+    }
+    /**
+     * Create and configure the OpenTelemetry SDK manager.
+     *
+     * Returns null if OpenTelemetry is disabled.
+     *
+     * @example
+     * ```ts
+     * import { OtelManager } from '@adonisjs/otel'
+     * import config from '#config/otel'
+     *
+     * const manager = OtelManager.create(config)
+     * manager?.start()
+     *
+     * // Later, on shutdown
+     * await manager?.shutdown()
+     * ```
+     */
+    static create(config) {
+        if (!OtelManager.isEnabled(config))
+            return null;
+        OtelManager.#instance = new OtelManager(config);
+        return OtelManager.#instance;
+    }
+    /**
+     * Get the global OtelManager instance.
+     * Returns null if OpenTelemetry is disabled or not yet initialized.
+     */
+    static getInstance() {
+        return OtelManager.#instance;
+    }
+}

package/build/src/start.d.ts

@@ -0,0 +1,18 @@
+/**
+ * OpenTelemetry initialization file.
+ *
+ * This file should be loaded BEFORE your application starts
+ * to enable auto-instrumentation:
+ *
+ * ```ts
+ * // bin/otel.ts
+ * import { init } from '@adonisjs/otel/init'
+ * await init(import.meta.dirname)
+ * ```
+ *
+ * Then import it first in bin/server.ts:
+ * ```ts
+ * import './otel.js'
+ * ```
+ */
+export declare function init(dirname: string): Promise<void>;

package/build/src/start.js

@@ -0,0 +1,37 @@
+/**
+ * OpenTelemetry initialization file.
+ *
+ * This file should be loaded BEFORE your application starts
+ * to enable auto-instrumentation:
+ *
+ * ```ts
+ * // bin/otel.ts
+ * import { init } from '@adonisjs/otel/init'
+ * await init(import.meta.dirname)
+ * ```
+ *
+ * Then import it first in bin/server.ts:
+ * ```ts
+ * import './otel.js'
+ * ```
+ */
+import { createAddHookMessageChannel } from 'import-in-the-middle';
+import { register } from 'node:module';
+import { join } from 'node:path';
+export async function init(dirname) {
+    // Setup import-in-the-middle hooks for auto-instrumentation
+    const { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel();
+    register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions);
+    // Import SDK functions after hooks are registered
+    const { OtelManager } = await import('./otel.js');
+    const configPath = join(dirname, '../config/otel.ts');
+    const config = await import(configPath).then((mod) => mod.default || mod);
+    if (!config)
+        throw new Error(`Otel configuration not found at ${configPath}`);
+    // Check if OTEL is enabled
+    if (!OtelManager.isEnabled(config))
+        return;
+    const manager = OtelManager.create(config);
+    manager?.start();
+    await waitForAllMessagesAcknowledged();
+}

package/build/src/types/decorators.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for span decorators
+ */
+export interface SpanOptions {
+    /**
+     * Custom span name. Defaults to `ClassName.methodName`
+     */
+    name?: string;
+    /**
+     * Additional attributes to add to the span
+     */
+    attributes?: Record<string, string | number | boolean>;
+}

package/build/src/types/decorators.js

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

package/build/src/types/index.d.ts

@@ -0,0 +1,155 @@
+import type { NodeSDKConfiguration } from '@opentelemetry/sdk-node';
+import type { HttpContext } from '@adonisjs/core/http';
+export type { InstrumentationValue, CustomInstrumentationValue, HttpInstrumentationConfig, PinoInstrumentationConfig, InstrumentationsConfig, } from './instrumentations.js';
+export type { SpanOptions } from './decorators.js';
+export { hiddenFields, type HiddenField, type OtelLoggingPresetOptions } from './logging.js';
+import type { InstrumentationsConfig } from './instrumentations.js';
+/**
+ * Configuration for @adonisjs/otel
+ *
+ * Extends NodeSDKConfiguration with simplified options and good defaults.
+ * All options are optional - the package works out of the box.
+ */
+export interface OtelConfig extends Partial<Omit<NodeSDKConfiguration, 'resource' | 'instrumentations'>> {
+    /**
+     * Enable or disable OpenTelemetry entirely.
+     *
+     * When disabled, no SDK is initialized and no traces are collected.
+     * Useful for tests or local development without a collector.
+     *
+     * @default true (false in 'test' environment)
+     */
+    enabled?: boolean;
+    /**
+     * Sampling ratio for traces (0.0 to 1.0).
+     *
+     * - `1.0` = 100% of traces are sampled (default)
+     * - `0.1` = 10% of traces are sampled
+     * - `0.0` = No traces are sampled
+     *
+     * This option is ignored if `sampler` is explicitly provided.
+     *
+     * @default 1.0
+     *
+     * @example
+     * ```ts
+     * defineConfig({
+     *   samplingRatio: 0.1, // Sample 10% of traces in production
+     * })
+     * ```
+     */
+    samplingRatio?: number;
+    /**
+     * Enable debug mode to print spans to the console.
+     *
+     * When enabled, a `ConsoleSpanExporter` is automatically added
+     * to help with local development and debugging.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * defineConfig({
+     *   debug: true, // Print spans to console
+     * })
+     * ```
+     */
+    debug?: boolean;
+    /**
+     * Service name for telemetry identification
+     * @default process.env.OTEL_SERVICE_NAME || process.env.APP_NAME || 'unknown_service'
+     */
+    serviceName?: string;
+    /**
+     * Service version
+     * @default process.env.APP_VERSION || '0.0.0'
+     */
+    serviceVersion?: string;
+    /**
+     * Deployment environment (production, staging, development, etc.)
+     * @default process.env.APP_ENV || 'development'
+     */
+    environment?: string;
+    /**
+     * Additional resource attributes to include in telemetry
+     */
+    resourceAttributes?: Record<string, string>;
+    /**
+     * Instrumentations configuration.
+     *
+     * - Pass a config object to merge with defaults
+     * - Pass an Instrumentation instance for custom instrumentations
+     * - Pass `{ enabled: false }` to disable
+     *
+     * @example
+     * ```ts
+     * instrumentations: {
+     *   '@opentelemetry/instrumentation-http': {
+     *     ignoredUrls: ['/internal/*', '/custom-health'],
+     *   },
+     *   '@opentelemetry/instrumentation-pino': {
+     *     logHook: (span, record) => {
+     *       record.tenant_id = getTenantId()
+     *     },
+     *   },
+     *   '@opentelemetry/instrumentation-pg': { enabled: false },
+     * }
+     * ```
+     */
+    instrumentations?: InstrumentationsConfig;
+    /**
+     * Configure automatic user context extraction in the middleware.
+     *
+     * By default, extracts `id`, `email`, `role` from `ctx.auth.user`.
+     * Set to `false` to disable entirely.
+     *
+     * @example
+     * ```ts
+     * userContext: {
+     *   resolver: async (ctx) => ({
+     *     id: ctx.auth.user.id,
+     *     tenantId: ctx.auth.user.tenantId,
+     *   }),
+     * }
+     * ```
+     */
+    userContext?: false | UserContextConfig;
+}
+/**
+ * Result returned by the user context resolver
+ */
+export interface UserContextResult {
+    id: string | number;
+    email?: string;
+    role?: string;
+    [key: string]: unknown;
+}
+/**
+ * Configuration for automatic user context extraction
+ */
+export interface UserContextConfig {
+    /**
+     * Enable/disable automatic user extraction from @adonisjs/auth
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Custom function to extract user context from the HttpContext.
+     * When provided, replaces the default extraction logic.
+     * Return `null` to skip setting user context for this request.
+     */
+    resolver?: (ctx: HttpContext) => UserContextResult | null | Promise<UserContextResult | null>;
+}
+/**
+ * User information for tracing
+ */
+export interface UserContext {
+    id: string | number;
+    email?: string;
+    role?: string;
+    [key: string]: unknown;
+}
+/**
+ * Headers carrier type for context propagation
+ */
+export type HeadersCarrier = Record<string, string | string[] | undefined>;

package/build/src/types/index.js

@@ -0,0 +1 @@
+export { hiddenFields } from './logging.js';

package/build/src/types/instrumentations.d.ts

@@ -0,0 +1,79 @@
+import type { Span } from '@opentelemetry/api';
+import type { InstrumentationConfigMap } from '@opentelemetry/auto-instrumentations-node';
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+/**
+ * Value for a known instrumentation: config object, instance, or disabled
+ */
+export type InstrumentationValue<K extends keyof InstrumentationConfigMap> = InstrumentationConfigMap[K] | Instrumentation | {
+    enabled: false;
+};
+/**
+ * Value for a custom instrumentation: instance or disabled
+ */
+export type CustomInstrumentationValue = Instrumentation | {
+    enabled: false;
+};
+/**
+ * Extended config for @opentelemetry/instrumentation-http.
+ * Adds AdonisJS-specific helpers for URL filtering.
+ */
+export interface HttpInstrumentationConfig extends Omit<NonNullable<InstrumentationConfigMap['@opentelemetry/instrumentation-http']>, 'ignoreIncomingRequestHook'> {
+    /**
+     * URLs to ignore in HTTP instrumentation.
+     * Merged with defaults unless `mergeIgnoredUrls` is false.
+     * Supports wildcards: '/internal/*'
+     *
+     * @default ['/health', '/healthz', '/ready', '/metrics', '/favicon.ico', ...]
+     */
+    ignoredUrls?: string[];
+    /**
+     * Whether to merge ignoredUrls with default ignored URLs or replace them entirely.
+     * @default true
+     */
+    mergeIgnoredUrls?: boolean;
+    /**
+     * Custom hook to ignore specific incoming requests.
+     * Called AFTER the ignoredUrls check.
+     */
+    ignoreIncomingRequestHook?: (request: {
+        url?: string;
+    }) => boolean;
+}
+/**
+ * Extended config for @opentelemetry/instrumentation-pino.
+ * Allows custom logHook while preserving the internal one.
+ */
+export interface PinoInstrumentationConfig extends Omit<NonNullable<InstrumentationConfigMap['@opentelemetry/instrumentation-pino']>, 'logHook'> {
+    /**
+     * Custom log hook executed AFTER the internal hook that adds route info.
+     * Use this to add your own properties to log records.
+     *
+     * @example
+     * ```ts
+     * logHook: (span, record) => {
+     *   record.tenant_id = getCurrentTenantId()
+     * }
+     * ```
+     */
+    logHook?: (span: Span, record: Record<string, unknown>) => void;
+}
+/**
+ * Keys of instrumentations with custom extended configs
+ */
+type ExtendedInstrumentationKeys = '@opentelemetry/instrumentation-http' | '@opentelemetry/instrumentation-pino';
+/**
+ * Instrumentations configuration map.
+ *
+ * - HTTP and Pino instrumentations have extended configs
+ */
+export type InstrumentationsConfig = {
+    '@opentelemetry/instrumentation-http'?: HttpInstrumentationConfig | Instrumentation | {
+        enabled: false;
+    };
+    '@opentelemetry/instrumentation-pino'?: PinoInstrumentationConfig | Instrumentation | {
+        enabled: false;
+    };
+} & {
+    [K in Exclude<keyof InstrumentationConfigMap, ExtendedInstrumentationKeys>]?: InstrumentationValue<K>;
+};
+export {};

package/build/src/types/instrumentations.js

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

package/build/src/types/logging.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Fields hidden by default in pino-pretty output
+ */
+export declare const hiddenFields: readonly ["pid", "hostname", "trace_id", "span_id", "trace_flags", "route", "request_id", "x-request-id"];
+export type HiddenField = (typeof hiddenFields)[number];
+export interface OtelLoggingPresetOptions {
+    /**
+     * Fields to keep visible in logs (not hidden).
+     * Useful if you want to see trace context in development.
+     */
+    keep?: HiddenField[];
+}

package/build/src/types/logging.js

@@ -0,0 +1,13 @@
+/**
+ * Fields hidden by default in pino-pretty output
+ */
+export const hiddenFields = [
+    'pid',
+    'hostname',
+    'trace_id',
+    'span_id',
+    'trace_flags',
+    'route',
+    'request_id',
+    'x-request-id',
+];

package/build/stubs/config.stub

@@ -0,0 +1,12 @@
+{{{
+  exports({ to: app.configPath('otel.ts') })
+}}}
+import { defineConfig } from '@adonisjs/otel'
+import env from '#start/env'
+
+export default defineConfig({
+  serviceName: env.get('APP_NAME'),
+  serviceVersion: env.get('APP_VERSION'),
+  environment: env.get('APP_ENV'),
+})
+

package/build/stubs/main.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Path to the root directory where the stubs are stored. We use
+ * this path within commands and the configure hook
+ */
+export declare const stubsRoot: string;