@adonisjs/otel 1.0.0-next.0

package/build/src/helpers.js

@@ -0,0 +1,236 @@
+import { context, propagation, trace, SpanStatusCode } from '@opentelemetry/api';
+import { hiddenFields, } from './types/index.js';
+/**
+ * Get the currently active span from the current context.
+ *
+ * Returns `undefined` if there is no active span.
+ *
+ * @example
+ * ```ts
+ * import { getCurrentSpan } from '@adonisjs/otel'
+ *
+ * function myUtility() {
+ *   const span = getCurrentSpan()
+ *   span?.setAttributes({ 'custom.attribute': 'value' })
+ * }
+ * ```
+ */
+export function getCurrentSpan() {
+    return trace.getActiveSpan();
+}
+/**
+ * Set attributes on the currently active span.
+ *
+ * This is a convenience wrapper around `getCurrentSpan()?.setAttributes()`.
+ * Does nothing if there is no active span.
+ *
+ * @example
+ * ```ts
+ * import { setAttributes } from '@adonisjs/otel'
+ *
+ * function processOrder(orderId: string) {
+ *   setAttributes({
+ *     'order.id': orderId,
+ *     'order.type': 'subscription',
+ *   })
+ * }
+ * ```
+ */
+export function setAttributes(attributes) {
+    getCurrentSpan()?.setAttributes(attributes);
+}
+/**
+ * Record a code section as a span in your traces.
+ *
+ * Automatically handles:
+ * - Creating and closing the span
+ * - Capturing exceptions and setting error status
+ * - Async/await support
+ *
+ * @example
+ * ```ts
+ * import { record } from '@adonisjs/otel'
+ *
+ * // Sync
+ * const result = record('database.query', () => {
+ *   return db.query('SELECT * FROM users')
+ * })
+ *
+ * // Async
+ * const user = await record('user.fetch', async () => {
+ *   return await userService.findById(id)
+ * })
+ *
+ * // With attributes
+ * const order = await record('order.process', async (span) => {
+ *   span.setAttributes({ 'order.id': orderId })
+ *   return await processOrder(orderId)
+ * })
+ * ```
+ */
+export function record(name, callback) {
+    const tracer = trace.getTracer('@adonisjs/otel');
+    return tracer.startActiveSpan(name, (span) => {
+        try {
+            const result = callback(span);
+            if (result instanceof Promise) {
+                return result
+                    .then((value) => {
+                    span.end();
+                    return value;
+                })
+                    .catch((error) => handleError(span, error));
+            }
+            span.end();
+            return result;
+        }
+        catch (error) {
+            handleError(span, error);
+            return undefined;
+        }
+    });
+}
+export function handleError(span, error) {
+    span.recordException(error);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message });
+    span.end();
+    throw error;
+}
+/**
+ * User semantic convention attributes
+ * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/user/
+ */
+const ATTR_USER_ID = 'user.id';
+const ATTR_USER_EMAIL = 'user.email';
+const ATTR_USER_ROLES = 'user.roles';
+/**
+ * Set user information on the currently active span.
+ *
+ * Uses OpenTelemetry semantic conventions for user attributes.
+ *
+ * @example
+ * ```ts
+ * import { setUser } from '@adonisjs/otel'
+ *
+ * // In a controller or middleware
+ * setUser({
+ *   id: auth.user.id,
+ *   email: auth.user.email,
+ *   role: auth.user.role,
+ * })
+ * ```
+ */
+export function setUser(user) {
+    const span = getCurrentSpan();
+    if (!span)
+        return;
+    const attributes = {
+        [ATTR_USER_ID]: String(user.id),
+    };
+    if (user.email)
+        attributes[ATTR_USER_EMAIL] = user.email;
+    if (user.role)
+        attributes[ATTR_USER_ROLES] = [user.role];
+    // Add any extra custom attributes
+    for (const [key, value] of Object.entries(user)) {
+        if (!['id', 'email', 'role'].includes(key) && value !== undefined) {
+            attributes[`user.${key}`] = String(value);
+        }
+    }
+    span.setAttributes(attributes);
+}
+/**
+ * Inject the current trace context into headers for propagation.
+ *
+ * Use this when making outgoing HTTP requests, dispatching queue jobs,
+ * or any cross-service communication where you want to maintain trace continuity.
+ *
+ * @example
+ * ```ts
+ * import { injectTraceContext } from '@adonisjs/otel'
+ *
+ * // HTTP request to another service
+ * const headers = {}
+ * injectTraceContext(headers)
+ * await fetch('https://api.example.com', { headers })
+ *
+ * // Queue job dispatch
+ * const jobHeaders = {}
+ * injectTraceContext(jobHeaders)
+ * await queue.dispatch('process-order', { orderId }, { headers: jobHeaders })
+ * ```
+ */
+export function injectTraceContext(headers) {
+    propagation.inject(context.active(), headers);
+}
+/**
+ * Extract trace context from incoming headers.
+ *
+ * Use this in queue workers, background jobs, or any service receiving
+ * requests from another traced service to continue the trace.
+ *
+ * @returns The extracted context that can be used with `record()` or `trace.startActiveSpan()`
+ *
+ * @example
+ * ```ts
+ * import { extractTraceContext, record } from '@adonisjs/otel'
+ * import { context } from '@opentelemetry/api'
+ *
+ * // In a queue worker
+ * const extractedContext = extractTraceContext(job.headers)
+ *
+ * context.with(extractedContext, () => {
+ *   record('process-job', () => {
+ *     // This span will be a child of the original trace
+ *   })
+ * })
+ * ```
+ */
+export function extractTraceContext(headers) {
+    return propagation.extract(context.active(), headers);
+}
+/**
+ * Record an event on the currently active span.
+ *
+ * Events are time-stamped annotations that can be attached to spans
+ * to record discrete occurrences during a span's lifetime.
+ *
+ * @see https://opentelemetry.io/docs/concepts/signals/traces/#span-events
+ *
+ * @example
+ * ```ts
+ * import { recordEvent } from '@adonisjs/otel'
+ *
+ * // Simple event
+ * recordEvent('cache.miss')
+ *
+ * // Event with attributes
+ * recordEvent('order.processed', {
+ *   'order.id': orderId,
+ *   'order.total': 99.99,
+ * })
+ * ```
+ */
+export function recordEvent(name, attributes) {
+    getCurrentSpan()?.addEvent(name, attributes);
+}
+/**
+ * Preset for pino-pretty to hide OpenTelemetry-injected fields ( in development).
+ *
+ * By default, hides: pid, hostname, trace_id, span_id, trace_flags, route, request_id, x-request-id
+ *
+ * @example
+ * ```ts
+ * import { otelLoggingPreset } from '@adonisjs/otel'
+ *
+ * // Hide all OTEL fields
+ * targets.pretty(otelLoggingPreset())
+ *
+ * // Keep trace context visible
+ * targets.pretty(otelLoggingPreset({ keep: ['trace_id', 'span_id'] }))
+ * ```
+ */
+export function otelLoggingPreset(options) {
+    const keep = options?.keep ?? [];
+    return { ignore: hiddenFields.filter((field) => !keep.includes(field)).join(',') };
+}

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

@@ -0,0 +1,20 @@
+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.
+ *
+ * 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.
+ */
+export default class OtelMiddleware {
+    #private;
+    constructor(options: {
+        userContext?: UserContextConfig | false;
+    });
+    handle(ctx: HttpContext, next: NextFn): Promise<any>;
+}

package/build/src/middleware/otel_middleware.js

@@ -0,0 +1,64 @@
+import { trace } from '@opentelemetry/api';
+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.
+ *
+ * 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.
+ */
+export default class OtelMiddleware {
+    #userContextConfig;
+    constructor(options) {
+        this.#userContextConfig = options.userContext ?? {};
+    }
+    /**
+     * Try to extract user from auth and set on span
+     *
+     * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/user/
+     */
+    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 });
+    }
+    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);
+        }
+        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());
+        return output;
+    }
+}

package/build/src/otel.d.ts

@@ -0,0 +1,65 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import type { OtelConfig } from './types/index.js';
+/**
+ * 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 declare class OtelManager {
+    #private;
+    static readonly DEFAULT_IGNORED_URLS: string[];
+    readonly sdk: NodeSDK;
+    readonly serviceName: string;
+    readonly serviceVersion: string;
+    readonly environment: string;
+    constructor(config: OtelConfig);
+    /**
+     * Start the OpenTelemetry SDK
+     */
+    start(): void;
+    /**
+     * Gracefully shutdown the OpenTelemetry SDK
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Check if OpenTelemetry should be enabled based on config.
+     * Defaults to false when NODE_ENV === 'test'.
+     */
+    static isEnabled(config: OtelConfig): boolean;
+    /**
+     * 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: OtelConfig): OtelManager | null;
+    /**
+     * Get the global OtelManager instance.
+     * Returns null if OpenTelemetry is disabled or not yet initialized.
+     */
+    static getInstance(): OtelManager | null;
+}