@adonisjs/otel 1.0.0-next.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @adonisjs/otel
+
+<br />
+
+[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]
+
+## Introduction
+
+OpenTelemetry integration for AdonisJS with sensible defaults and zero-config setup. Get distributed tracing, metrics, and automatic instrumentation out of the box.
+
+## Official Documentation
+
+The documentation is available on the [AdonisJS website](https://docs.adonisjs.com/guides/digging-deeper/otel)
+
+## Contributing
+
+One of the primary goals of AdonisJS is to have a vibrant community of users and contributors who believes in the principles of the framework.
+
+We encourage you to read the [contribution guide](https://github.com/adonisjs/.github/blob/main/docs/CONTRIBUTING.md) before contributing to the framework.
+
+## Code of Conduct
+
+In order to ensure that the AdonisJS community is welcoming to all, please review and abide by the [Code of Conduct](https://github.com/adonisjs/.github/blob/main/docs/CODE_OF_CONDUCT.md).
+
+## License
+
+AdonisJS OpenTelemetry is open-sourced software licensed under the [MIT license](LICENSE.md).
+
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/otel/checks.yml?style=for-the-badge
+[gh-workflow-url]: https://github.com/adonisjs/otel/actions/workflows/checks.yml "Github action"
+
+[npm-image]: https://img.shields.io/npm/v/@adonisjs/otel/latest.svg?style=for-the-badge&logo=npm
+[npm-url]: https://www.npmjs.com/package/@adonisjs/otel/v/latest "npm"
+
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+
+[license-url]: LICENSE.md
+[license-image]: https://img.shields.io/github/license/adonisjs/otel?style=for-the-badge

package/build/configure.d.ts

@@ -0,0 +1,2 @@
+import ConfigureCommand from '@adonisjs/core/commands/configure';
+export declare function configure(command: ConfigureCommand): Promise<void>;

package/build/configure.js

@@ -0,0 +1,69 @@
+/*
+|--------------------------------------------------------------------------
+| Configure hook
+|--------------------------------------------------------------------------
+|
+| The configure hook is called when someone runs "node ace configure <package>"
+| command. You are free to perform any operations inside this function to
+| configure the package.
+|
+| To make things easier, you have access to the underlying "ConfigureCommand"
+| instance and you can use codemods to modify the source files.
+|
+*/
+import { stubsRoot } from './stubs/main.js';
+export async function configure(command) {
+    const codemods = await command.createCodemods();
+    /**
+     * Publish the configuration file
+     */
+    await codemods.makeUsingStub(stubsRoot, 'config.stub', {});
+    /**
+     * Publish the bin/otel.ts file
+     */
+    await codemods.makeUsingStub(stubsRoot, 'otel.stub', {});
+    /**
+     * Add import to bin/server.ts as the FIRST import
+     * This is critical for auto-instrumentation to work
+     */
+    const project = await codemods.getTsMorphProject();
+    const serverFile = project?.getSourceFile(command.app.makePath('bin/server.ts'));
+    if (serverFile) {
+        const firstImport = serverFile.getImportDeclarations()[0];
+        const insertIndex = firstImport?.getChildIndex() ?? 0;
+        serverFile.insertStatements(insertIndex, [
+            '/**',
+            ' * OpenTelemetry initialization - MUST be the first import',
+            ' * @see https://opentelemetry.io/docs/languages/js/getting-started/nodejs/',
+            ' */',
+            `import './otel.js'`,
+            '',
+        ]);
+        await serverFile.save();
+    }
+    /**
+     * Register the provider
+     */
+    await codemods.updateRcFile((rcFile) => rcFile.addProvider('@adonisjs/otel/otel_provider'));
+    /**
+     * Register the middleware
+     */
+    await codemods.registerMiddleware('router', [
+        { path: '@adonisjs/otel/otel_middleware', position: 'before' },
+    ]);
+    /**
+     * Add new environment variables
+     */
+    await codemods.defineEnvVariables({
+        APP_NAME: command.app.appName,
+        APP_VERSION: '0.0.1',
+        APP_ENV: 'development',
+    });
+    await codemods.defineEnvValidations({
+        variables: {
+            APP_NAME: 'Env.schema.string()',
+            APP_VERSION: 'Env.schema.string()',
+            APP_ENV: "Env.schema.enum(['development', 'staging', 'production'] as const)",
+        },
+    });
+}

package/build/index.d.ts

@@ -0,0 +1,11 @@
+export { configure } from './configure.js';
+export { defineConfig } from './src/define_config.js';
+export { OtelManager } from './src/otel.js';
+/**
+ * Re-export OTLP exporters so users don't need to install those 100 packages
+ * from OpenTelemetry just to get the exporters.
+ */
+export { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
+export { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-grpc';
+export { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+export { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';

package/build/index.js

@@ -0,0 +1,19 @@
+/*
+|--------------------------------------------------------------------------
+| Package entrypoint
+|--------------------------------------------------------------------------
+|
+| Export values from the package entrypoint as you see fit.
+|
+*/
+export { configure } from './configure.js';
+export { defineConfig } from './src/define_config.js';
+export { OtelManager } from './src/otel.js';
+/**
+ * Re-export OTLP exporters so users don't need to install those 100 packages
+ * from OpenTelemetry just to get the exporters.
+ */
+export { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
+export { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-grpc';
+export { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+export { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';

package/build/providers/otel_provider.d.ts

@@ -0,0 +1,11 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+export default class OtelProvider {
+    #private;
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    register(): void;
+    /**
+     * Gracefully flush pending spans
+     */
+    shutdown(): Promise<void>;
+}

package/build/providers/otel_provider.js

@@ -0,0 +1,50 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import { configProvider } from '@adonisjs/core';
+import { ExceptionHandler } from '@adonisjs/core/http';
+import { getCurrentSpan } from '../src/helpers.js';
+import OtelMiddleware from '../src/middleware/otel_middleware.js';
+import { OtelManager } from '../src/otel.js';
+export default class OtelProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    /**
+     * Hook into ExceptionHandler to record exceptions in spans
+     */
+    #registerExceptionHandler() {
+        const originalReport = ExceptionHandler.prototype.report;
+        ExceptionHandler.macro('report', async function (error, ctx) {
+            // @ts-expect-error - protected method
+            const httpError = this.toHttpError(error);
+            if (!this.shouldReport(httpError))
+                return;
+            const span = getCurrentSpan();
+            if (span && error instanceof Error) {
+                span.recordException(error);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+            }
+            return originalReport.call(this, error, ctx);
+        });
+    }
+    register() {
+        this.#registerExceptionHandler();
+        this.#registerMiddleware();
+    }
+    /**
+     * Register the OtelMiddleware as a singleton in the container
+     */
+    #registerMiddleware() {
+        this.app.container.singleton(OtelMiddleware, async () => {
+            const otelConfigProvider = this.app.config.get('otel', {});
+            const config = await configProvider.resolve(this.app, otelConfigProvider);
+            return new OtelMiddleware({ userContext: config?.userContext });
+        });
+    }
+    /**
+     * Gracefully flush pending spans
+     */
+    async shutdown() {
+        await OtelManager.getInstance()?.shutdown();
+    }
+}

package/build/src/decorators.d.ts

@@ -0,0 +1,68 @@
+import type { SpanOptions } from './types/index.js';
+type Constructor = new (...args: any[]) => any;
+/**
+ * Decorator to create a span around a method.
+ *
+ * Automatically handles:
+ * - Creating and closing the span
+ * - Capturing exceptions and setting error status
+ * - Async/await support
+ *
+ * @example
+ * ```ts
+ * import { span } from '@adonisjs/otel'
+ *
+ * class UserService {
+ *   @span()
+ *   async findById(id: string) {
+ *     // Span name: "UserService.findById"
+ *     return db.users.find(id)
+ *   }
+ *
+ *   @span({ name: 'user.create', attributes: { operation: 'create' } })
+ *   async create(data: UserData) {
+ *     return db.users.create(data)
+ *   }
+ * }
+ * ```
+ */
+export declare function span(options?: SpanOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator to create spans around all methods of a class.
+ *
+ * Automatically handles:
+ * - Creating and closing spans for each method
+ * - Capturing exceptions and setting error status
+ * - Async/await support
+ *
+ * @example
+ * ```ts
+ * import { spanAll } from '@adonisjs/otel'
+ *
+ * @spanAll()
+ * class OrderService {
+ *   async create(data: OrderData) {
+ *     // Span name: "OrderService.create"
+ *     return db.orders.create(data)
+ *   }
+ *
+ *   async findById(id: string) {
+ *     // Span name: "OrderService.findById"
+ *     return db.orders.find(id)
+ *   }
+ * }
+ *
+ * @spanAll({ prefix: 'order' })
+ * class OrderService {
+ *   async create(data: OrderData) {
+ *     // Span name: "order.create"
+ *     return db.orders.create(data)
+ *   }
+ * }
+ * ```
+ */
+export declare function spanAll(options?: {
+    prefix?: string;
+    attributes?: Record<string, string | number | boolean>;
+}): <T extends Constructor>(constructor: T) => T;
+export {};

package/build/src/decorators.js

@@ -0,0 +1,102 @@
+import { record } from './helpers.js';
+/**
+ * Wrap a method to create a span around its execution
+ */
+function wrapMethod(target, propertyKey, descriptor, options) {
+    const originalMethod = descriptor.value;
+    const className = target.constructor.name;
+    descriptor.value = function (...args) {
+        const spanName = options?.name ?? `${className}.${propertyKey}`;
+        return record(spanName, (activeSpan) => {
+            if (options?.attributes)
+                activeSpan.setAttributes(options.attributes);
+            return originalMethod.apply(this, args);
+        });
+    };
+    return descriptor;
+}
+/**
+ * Decorator to create a span around a method.
+ *
+ * Automatically handles:
+ * - Creating and closing the span
+ * - Capturing exceptions and setting error status
+ * - Async/await support
+ *
+ * @example
+ * ```ts
+ * import { span } from '@adonisjs/otel'
+ *
+ * class UserService {
+ *   @span()
+ *   async findById(id: string) {
+ *     // Span name: "UserService.findById"
+ *     return db.users.find(id)
+ *   }
+ *
+ *   @span({ name: 'user.create', attributes: { operation: 'create' } })
+ *   async create(data: UserData) {
+ *     return db.users.create(data)
+ *   }
+ * }
+ * ```
+ */
+export function span(options) {
+    return function (target, propertyKey, descriptor) {
+        return wrapMethod(target, propertyKey, descriptor, options);
+    };
+}
+/**
+ * Decorator to create spans around all methods of a class.
+ *
+ * Automatically handles:
+ * - Creating and closing spans for each method
+ * - Capturing exceptions and setting error status
+ * - Async/await support
+ *
+ * @example
+ * ```ts
+ * import { spanAll } from '@adonisjs/otel'
+ *
+ * @spanAll()
+ * class OrderService {
+ *   async create(data: OrderData) {
+ *     // Span name: "OrderService.create"
+ *     return db.orders.create(data)
+ *   }
+ *
+ *   async findById(id: string) {
+ *     // Span name: "OrderService.findById"
+ *     return db.orders.find(id)
+ *   }
+ * }
+ *
+ * @spanAll({ prefix: 'order' })
+ * class OrderService {
+ *   async create(data: OrderData) {
+ *     // Span name: "order.create"
+ *     return db.orders.create(data)
+ *   }
+ * }
+ * ```
+ */
+export function spanAll(options) {
+    return function (constructor) {
+        const prototype = constructor.prototype;
+        const propertyNames = Object.getOwnPropertyNames(prototype);
+        for (const propertyName of propertyNames) {
+            if (propertyName === 'constructor')
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, propertyName);
+            if (!descriptor || typeof descriptor.value !== 'function')
+                continue;
+            const spanName = options?.prefix ? `${options.prefix}.${propertyName}` : undefined;
+            const wrappedDescriptor = wrapMethod(prototype, propertyName, descriptor, {
+                name: spanName,
+                attributes: options?.attributes,
+            });
+            Object.defineProperty(prototype, propertyName, wrappedDescriptor);
+        }
+        return constructor;
+    };
+}

package/build/src/define_config.d.ts

@@ -0,0 +1,2 @@
+import type { OtelConfig } from './types/index.js';
+export declare function defineConfig(config: OtelConfig): OtelConfig;

package/build/src/define_config.js

@@ -0,0 +1,3 @@
+export function defineConfig(config) {
+    return config;
+}

package/build/src/helpers.d.ts

@@ -0,0 +1,174 @@
+import type { Attributes, Span } from '@opentelemetry/api';
+import { type HeadersCarrier, type OtelLoggingPresetOptions, type UserContextResult } 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 declare function getCurrentSpan(): Span | undefined;
+/**
+ * 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 declare function setAttributes(attributes: Attributes): void;
+/**
+ * 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 declare function record<T>(name: string, callback: (span: Span) => T): T;
+export declare function handleError(span: Span, error: Error): void;
+/**
+ * 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 declare function setUser(user: UserContextResult): void;
+/**
+ * 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 declare function injectTraceContext(headers: HeadersCarrier): void;
+/**
+ * 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 declare function extractTraceContext(headers: HeadersCarrier): import("@opentelemetry/api").Context;
+/**
+ * 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 declare function recordEvent(name: string, attributes?: Attributes): void;
+/**
+ * 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 declare function otelLoggingPreset(options?: OtelLoggingPresetOptions): {
+    ignore: string;
+};