@adonisjs/otel 1.0.0 → 1.1.1

package/README.md

@@ -10,7 +10,7 @@ OpenTelemetry integration for AdonisJS with sensible defaults and zero-config se
 
 ## Official Documentation
 
-The documentation is available on the [AdonisJS website](https://docs.adonisjs.com/guides/digging-deeper/otel)
+The documentation is available on the [AdonisJS website](https://docs.adonisjs.com/guides/digging-deeper/open-telemetry)
 
 ## Contributing
 

package/build/src/debug.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("util").DebugLogger;
+export default _default;

package/build/src/debug.js

@@ -0,0 +1,2 @@
+import { debuglog } from 'node:util';
+export default debuglog('adonisjs:otel');

package/build/src/helpers.d.ts

@@ -70,17 +70,25 @@ export declare function handleError(span: Span, error: Error): void;
  * Set user information on the currently active span.
  *
  * Uses OpenTelemetry semantic conventions for user attributes.
+ * Custom attributes are prefixed with `user.` automatically.
  *
  * @example
  * ```ts
  * import { setUser } from '@adonisjs/otel'
  *
- * // In a controller or middleware
+ * // Basic usage
  * setUser({
  *   id: auth.user.id,
  *   email: auth.user.email,
  *   role: auth.user.role,
  * })
+ *
+ * // With custom attributes
+ * setUser({
+ *   id: auth.user.id,
+ *   tenantId: auth.user.tenantId,
+ *   plan: 'enterprise',
+ * })
  * ```
  */
 export declare function setUser(user: UserContextResult): void;

package/build/src/helpers.js

@@ -107,17 +107,25 @@ const ATTR_USER_ROLES = 'user.roles';
  * Set user information on the currently active span.
  *
  * Uses OpenTelemetry semantic conventions for user attributes.
+ * Custom attributes are prefixed with `user.` automatically.
  *
  * @example
  * ```ts
  * import { setUser } from '@adonisjs/otel'
  *
- * // In a controller or middleware
+ * // Basic usage
  * setUser({
  *   id: auth.user.id,
  *   email: auth.user.email,
  *   role: auth.user.role,
  * })
+ *
+ * // With custom attributes
+ * setUser({
+ *   id: auth.user.id,
+ *   tenantId: auth.user.tenantId,
+ *   plan: 'enterprise',
+ * })
  * ```
  */
 export function setUser(user) {
@@ -131,6 +139,14 @@ export function setUser(user) {
         attributes[ATTR_USER_EMAIL] = user.email;
     if (user.role)
         attributes[ATTR_USER_ROLES] = [user.role];
+    // Add custom attributes with user. prefix
+    for (const [key, value] of Object.entries(user)) {
+        if (key === 'id' || key === 'email' || key === 'role')
+            continue;
+        if (value === undefined)
+            continue;
+        attributes[`user.${key}`] = value;
+    }
     span.setAttributes(attributes);
 }
 /**

package/build/src/http_url_filter.d.ts

@@ -1,5 +1,5 @@
 import type { InstrumentationConfigMap } from '@opentelemetry/auto-instrumentations-node';
-import type { HttpInstrumentationConfig } from './types/instrumentations.js';
+import type { HttpInstrumentationConfig, IgnoreRequestInfo } from './types/instrumentations.js';
 /**
  * Handles URL filtering for OpenTelemetry HTTP instrumentation.
  * Determines which requests should be ignored (not traced).
@@ -8,15 +8,17 @@ export declare class HttpUrlFilter {
     #private;
     static readonly DEFAULT_IGNORED_URLS: string[];
     static readonly STATIC_FILE_EXTENSIONS: Set<string>;
+    static readonly VITE_DEV_PATTERNS: string[];
     constructor(config?: HttpInstrumentationConfig);
     /**
-     * Check if a URL should be ignored (not traced).
-     * A URL is ignored if:
+     * Check if a request should be ignored (not traced).
+     * A request is ignored if:
+     * - It's an OPTIONS request and ignoreOptionsRequests is true (default)
      * - It's a static file and ignoreStaticFiles is true (default)
      * - It matches the ignored URLs list (exact or prefix pattern)
      * - The user's custom hook returns true
      */
-    shouldIgnore(url: string | undefined): boolean;
+    shouldIgnore(request: IgnoreRequestInfo): boolean;
     /**
      * Apply HTTP instrumentation config to the merged config map
      */

package/build/src/http_url_filter.js

@@ -1,3 +1,4 @@
+import debug from './debug.js';
 /**
  * Handles URL filtering for OpenTelemetry HTTP instrumentation.
  * Determines which requests should be ignored (not traced).
@@ -40,13 +41,18 @@ export class HttpUrlFilter {
         'ogg',
         'wav',
         'pdf',
+        'vue',
+        'svelte',
     ]);
+    static VITE_DEV_PATTERNS = ['/@vite/', '/@id/', '/@fs/', '/__vite'];
     #ignoredUrls;
     #ignoreStaticFiles;
+    #ignoreOptionsRequests;
     #userIgnoreHook;
     constructor(config) {
         this.#ignoredUrls = this.#buildIgnoredUrls(config);
         this.#ignoreStaticFiles = config?.ignoreStaticFiles !== false;
+        this.#ignoreOptionsRequests = config?.ignoreOptionsRequests !== false;
         this.#userIgnoreHook = config?.ignoreIncomingRequestHook;
     }
     #buildIgnoredUrls(config) {
@@ -64,6 +70,9 @@ export class HttpUrlFilter {
         const extension = lastSegment.slice(dotIndex + 1).toLowerCase();
         return HttpUrlFilter.STATIC_FILE_EXTENSIONS.has(extension);
     }
+    #isViteDevRequest(url) {
+        return HttpUrlFilter.VITE_DEV_PATTERNS.some((pattern) => url.startsWith(pattern));
+    }
     #matchesPattern(urlPath, pattern) {
         if (pattern.endsWith('/*')) {
             const prefix = pattern.slice(0, -2);
@@ -72,22 +81,38 @@ export class HttpUrlFilter {
         return urlPath === pattern || urlPath.startsWith(pattern + '/');
     }
     /**
-     * Check if a URL should be ignored (not traced).
-     * A URL is ignored if:
+     * Check if a request should be ignored (not traced).
+     * A request is ignored if:
+     * - It's an OPTIONS request and ignoreOptionsRequests is true (default)
      * - It's a static file and ignoreStaticFiles is true (default)
      * - It matches the ignored URLs list (exact or prefix pattern)
      * - The user's custom hook returns true
      */
-    shouldIgnore(url) {
+    shouldIgnore(request) {
+        const { url, method } = request;
+        if (this.#ignoreOptionsRequests && method === 'OPTIONS') {
+            debug('ignoring request "%s %s" (reason: OPTIONS method)', method, url);
+            return true;
+        }
         if (!url)
             return false;
         const urlPath = url.split('?')[0];
-        if (this.#ignoreStaticFiles && this.#isStaticFile(urlPath))
+        if (this.#ignoreStaticFiles && this.#isStaticFile(urlPath)) {
+            debug('ignoring request "%s %s" (reason: static file)', method, urlPath);
             return true;
-        if (this.#ignoredUrls.some((pattern) => this.#matchesPattern(urlPath, pattern)))
+        }
+        if (this.#ignoreStaticFiles && this.#isViteDevRequest(urlPath)) {
+            debug('ignoring request "%s %s" (reason: vite dev pattern)', method, urlPath);
             return true;
-        if (this.#userIgnoreHook)
-            return this.#userIgnoreHook({ url });
+        }
+        if (this.#ignoredUrls.some((pattern) => this.#matchesPattern(urlPath, pattern))) {
+            debug('ignoring request "%s %s" (reason: ignored url pattern)', method, urlPath);
+            return true;
+        }
+        if (this.#userIgnoreHook && this.#userIgnoreHook(request)) {
+            debug('ignoring request "%s %s" (reason: user hook)', method, urlPath);
+            return true;
+        }
         return false;
     }
     /**
@@ -102,7 +127,7 @@ export class HttpUrlFilter {
         mergedConfig[httpKey] = {
             ...currentConfig,
             ...userHttpConfig,
-            ignoreIncomingRequestHook: (req) => this.shouldIgnore(req.url),
+            ignoreIncomingRequestHook: (req) => this.shouldIgnore({ url: req.url, method: req.method }),
         };
     }
 }

package/build/src/middleware/otel_middleware.d.ts

@@ -2,19 +2,18 @@ import type { HttpContext } from '@adonisjs/core/http';
 import type { NextFn } from '@adonisjs/core/types/http';
 import type { UserContextConfig } from '../types/index.js';
 /**
- * Middleware that enriches the active OpenTelemetry span with AdonisJS
- * specific attributes like the route pattern, user info, etc.
+ * Enriches the active OpenTelemetry span with AdonisJS-specific attributes.
  *
- * This should be registered as a router middleware to run after the
- * route has been resolved.
- *
- * When Auth module is installed, it will automatically set user
- * attributes on the span if a user is authenticated.
+ * Should be registered as a router middleware so it runs after route resolution.
+ * Automatically extracts user context from Auth module when available.
  */
 export default class OtelMiddleware {
     #private;
     constructor(options: {
         userContext?: UserContextConfig | false;
     });
+    /**
+     * Enriches active span with route info, user context, and response status.
+     */
     handle(ctx: HttpContext, next: NextFn): Promise<any>;
 }

package/build/src/middleware/otel_middleware.js

@@ -1,15 +1,12 @@
-import { trace } from '@opentelemetry/api';
+import { context, trace } from '@opentelemetry/api';
+import { getRPCMetadata, RPCType } from '@opentelemetry/core';
 import { ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_HTTP_ROUTE, } from '@opentelemetry/semantic-conventions';
 import { setUser } from '../helpers.js';
 /**
- * Middleware that enriches the active OpenTelemetry span with AdonisJS
- * specific attributes like the route pattern, user info, etc.
+ * Enriches the active OpenTelemetry span with AdonisJS-specific attributes.
  *
- * This should be registered as a router middleware to run after the
- * route has been resolved.
- *
- * When Auth module is installed, it will automatically set user
- * attributes on the span if a user is authenticated.
+ * Should be registered as a router middleware so it runs after route resolution.
+ * Automatically extracts user context from Auth module when available.
  */
 export default class OtelMiddleware {
     #userContextConfig;
@@ -17,45 +14,55 @@ export default class OtelMiddleware {
         this.#userContextConfig = options.userContext ?? {};
     }
     /**
-     * Try to extract user from auth and set on span
-     *
-     * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/user/
+     * Extracts user from auth context and sets OTEL user attributes.
+     * Supports custom resolvers or defaults to ctx.auth.user fields.
      */
     async #setUserFromAuth(ctx) {
         if (this.#userContextConfig === false)
             return;
         if (this.#userContextConfig.enabled === false)
             return;
-        // Custom resolver takes precedence
         if (this.#userContextConfig.resolver) {
             const resolved = await this.#userContextConfig.resolver(ctx);
             if (resolved)
                 setUser(resolved);
             return;
         }
-        // Default: extract from ctx.auth.user
         const user = ctx.auth?.user;
         if (!user)
             return;
         setUser({ id: user.id, email: user.email, role: user.role });
     }
+    /**
+     * Sets route metadata via RPCMetadata for OTEL HTTP instrumentation.
+     * This is the standard mechanism OTEL uses to populate http.route attribute.
+     */
+    #setRouteViaRpcMetadata(routePattern) {
+        const rpcMetadata = getRPCMetadata(context.active());
+        if (rpcMetadata?.type === RPCType.HTTP)
+            rpcMetadata.route = routePattern;
+    }
+    /**
+     * Updates span name and sets http.route attribute directly.
+     * Produces better trace names like "GET /users/:id" instead of just "GET".
+     */
+    #updateSpanWithRoute(options) {
+        options.span?.updateName(`${options.method} ${options.routePattern}`);
+        options.span?.setAttribute(ATTR_HTTP_ROUTE, options.routePattern);
+    }
+    /**
+     * Enriches active span with route info, user context, and response status.
+     */
     async handle(ctx, next) {
         const span = trace.getActiveSpan();
         if (!span)
             return next();
         const { request, route } = ctx;
-        /**
-         * Update span name with HTTP method and route pattern
-         * This gives much better trace names like "GET /users/:id" instead of "GET"
-         */
         if (route?.pattern) {
-            span.updateName(`${request.method()} ${route.pattern}`);
-            span.setAttribute(ATTR_HTTP_ROUTE, route.pattern);
+            this.#setRouteViaRpcMetadata(route.pattern);
+            this.#updateSpanWithRoute({ span, method: request.method(), routePattern: route.pattern });
         }
         span.setAttributes({ 'adonis.route.name': route?.name ?? 'unknown' });
-        /**
-         * Automatically set user context from Auth module
-         */
         await this.#setUserFromAuth(ctx);
         const output = await next();
         span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, ctx.response.getStatus());

package/build/src/otel.js

@@ -2,10 +2,11 @@ import { getNodeAutoInstrumentations, } from '@opentelemetry/auto-instrumentatio
 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_HTTP_ROUTE, 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';
 import { HttpUrlFilter } from './http_url_filter.js';
+import debug from './debug.js';
 /**
  * OpenTelemetry SDK manager for AdonisJS.
  *
@@ -140,6 +141,10 @@ export class OtelManager {
      */
     #buildInstrumentations() {
         const { customInstances, disabledSet, configOverrides, httpConfig, pinoConfig } = this.#processUserInstrumentations(this.#config.instrumentations);
+        if (disabledSet.size > 0)
+            debug('disabled instrumentations: %O', [...disabledSet]);
+        if (customInstances.length > 0)
+            debug('custom instrumentations: %O', customInstances.map((i) => i.instrumentationName));
         const mergedConfig = this.#buildBaseInstrumentationConfig();
         for (const [name, config] of Object.entries(configOverrides)) {
             mergedConfig[name] = {
@@ -166,15 +171,14 @@ export class OtelManager {
             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);
+                const httpContext = HttpContext.get();
+                const routePattern = httpContext?.route?.pattern;
+                if (routePattern)
+                    span.setAttribute(ATTR_HTTP_ROUTE, routePattern);
                 if (userLogHook)
                     userLogHook(span, record);
             },
@@ -222,12 +226,14 @@ export class OtelManager {
      * Start the OpenTelemetry SDK
      */
     start() {
+        debug('starting otel sdk for service "%s" v%s (%s)', this.serviceName, this.serviceVersion, this.environment);
         this.sdk.start();
     }
     /**
      * Gracefully shutdown the OpenTelemetry SDK
      */
     async shutdown() {
+        debug('shutting down otel sdk');
         await this.sdk.shutdown();
     }
     /**

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

@@ -102,12 +102,14 @@ export interface OtelConfig extends Partial<Omit<NodeSDKConfiguration, 'resource
     userContext?: false | UserContextConfig;
 }
 /**
- * Result returned by the user context resolver
+ * Result returned by the user context resolver.
+ * Supports custom attributes via index signature.
  */
 export interface UserContextResult {
     id: string | number;
     email?: string;
     role?: string;
+    [key: string]: string | number | boolean | string[] | undefined;
 }
 /**
  * Configuration for automatic user context extraction

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

@@ -13,6 +13,13 @@ export type InstrumentationValue<K extends keyof InstrumentationConfigMap> = Ins
 export type CustomInstrumentationValue = Instrumentation | {
     enabled: false;
 };
+/**
+ * Request info passed to the ignoreIncomingRequestHook
+ */
+export interface IgnoreRequestInfo {
+    url?: string;
+    method?: string;
+}
 /**
  * Extended config for @opentelemetry/instrumentation-http.
  * Adds AdonisJS-specific helpers for URL filtering.
@@ -36,13 +43,16 @@ export interface HttpInstrumentationConfig extends Omit<NonNullable<Instrumentat
      * @default true
      */
     ignoreStaticFiles?: boolean;
+    /**
+     * Whether to automatically ignore OPTIONS requests (CORS preflight).
+     * @default true
+     */
+    ignoreOptionsRequests?: boolean;
     /**
      * Custom hook to ignore specific incoming requests.
-     * Called AFTER the ignoredUrls and static files checks.
+     * Called AFTER the ignoredUrls, static files, and OPTIONS checks.
      */
-    ignoreIncomingRequestHook?: (request: {
-        url?: string;
-    }) => boolean;
+    ignoreIncomingRequestHook?: (request: IgnoreRequestInfo) => boolean;
 }
 /**
  * Extended config for @opentelemetry/instrumentation-pino.
@@ -66,10 +76,16 @@ export interface PinoInstrumentationConfig extends Omit<NonNullable<Instrumentat
  * Keys of instrumentations with custom extended configs
  */
 type ExtendedInstrumentationKeys = '@opentelemetry/instrumentation-http' | '@opentelemetry/instrumentation-pino';
+/**
+ * All possible values for any instrumentation key
+ */
+type AnyInstrumentationValue = HttpInstrumentationConfig | PinoInstrumentationConfig | InstrumentationConfigMap[keyof InstrumentationConfigMap] | CustomInstrumentationValue;
 /**
  * Instrumentations configuration map.
  *
  * - HTTP and Pino instrumentations have extended configs
+ * - Known OpenTelemetry instrumentations have typed configs with autocomplete
+ * - Custom instrumentations can be added with any string key
  */
 export type InstrumentationsConfig = {
     '@opentelemetry/instrumentation-http'?: HttpInstrumentationConfig | Instrumentation | {
@@ -80,5 +96,7 @@ export type InstrumentationsConfig = {
     };
 } & {
     [K in Exclude<keyof InstrumentationConfigMap, ExtendedInstrumentationKeys>]?: InstrumentationValue<K>;
+} & {
+    [key: string & {}]: AnyInstrumentationValue | undefined;
 };
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adonisjs/otel",
   "description": "OpenTelemetry integration for AdonisJS with sensible defaults and zero-config setup",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "engines": {
     "node": ">=20.6.0"
   },
@@ -68,6 +68,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.67.2",
+    "@opentelemetry/core": "^2.2.0",
     "@opentelemetry/exporter-metrics-otlp-grpc": "^0.208.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.208.0",
     "@opentelemetry/instrumentation": "^0.208.0",
@@ -88,8 +89,8 @@
     "@adonisjs/tsconfig": "^1.4.1",
     "@japa/assert": "^4.1.1",
     "@japa/runner": "^4.4.0",
+    "@julr/otel-instrumentation-clickhouse": "^1.0.2",
     "@opentelemetry/context-async-hooks": "^2.2.0",
-    "@opentelemetry/core": "^2.2.0",
     "@release-it/conventional-changelog": "^10.0.0",
     "@sentry/node": "^10.30.0",
     "@swc/core": "^1.15.3",