@elysiumjs/argus 0.1.1 → 0.2.3

package/dist/plugin.d.ts

@@ -0,0 +1,40 @@
+import { Elysia } from 'elysia';
+/**
+ * Elysia plugin that creates OpenTelemetry request spans.
+ *
+ * Each HTTP request gets a span with method, path, and status information.
+ * Errors (5xx) are recorded as error spans.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @returns An Elysia plugin instance.
+ */
+export declare const argusPlugin: () => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {
+        readonly __argusSpan: import("@opentelemetry/api").Span;
+    };
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/sdk.d.ts

@@ -0,0 +1,56 @@
+import type { TracingConfig } from './types';
+/**
+ * ArgusSDK initializes OpenTelemetry for the Elysium framework.
+ *
+ * CRITICAL: For full auto-instrumentation this MUST be called before any
+ * application code runs (e.g. from a `--preload` file). Auto-instrumentation
+ * patches modules at import time; modules imported before OTel is initialized
+ * won't be instrumented. `ArgusModule` initialises the SDK in `onInit`, which
+ * only covers modules loaded afterwards; when the SDK was already initialised
+ * (e.g. by a preload), the module detects it with {@link ArgusSDK.isInitialized}
+ * and leaves it alone.
+ *
+ * @example
+ * ```typescript
+ * // src/instrument.ts (loaded FIRST via --preload or entrypoint)
+ * import { ArgusSDK } from '@elysiumjs/argus';
+ *
+ * ArgusSDK.initialize({
+ *   enabled: true,
+ *   serviceName: 'my-api',
+ *   exporter: 'otlp-http',
+ *   endpoint: 'http://localhost:4318/v1/traces'
+ * });
+ * ```
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ArgusSDK {
+    private static instance;
+    private sdk;
+    private constructor();
+    /**
+     * Whether {@link ArgusSDK.initialize} has already been called.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static isInitialized(): boolean;
+    /**
+     * Initializes the OpenTelemetry SDK.
+     * Can only be called once — subsequent calls are ignored with a warning.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param config The tracing configuration.
+     */
+    static initialize(config: TracingConfig): void;
+    /**
+     * Creates the appropriate trace exporter based on the config.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param config The tracing configuration.
+     * @returns A span exporter instance.
+     */
+    private static createExporter;
+    /**
+     * Shuts down the OpenTelemetry SDK gracefully.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static shutdown(): Promise<void>;
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration for the Argus telemetry SDK.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface TracingConfig {
+    /**
+     * Whether tracing is enabled.
+     */
+    enabled: boolean;
+    /**
+     * The service name reported in spans.
+     */
+    serviceName: string;
+    /**
+     * The exporter to use. Only `otlp-http` and `console` are supported.
+     * gRPC is not supported on Bun.
+     */
+    exporter: 'otlp-http' | 'console';
+    /**
+     * The OTLP endpoint URL.
+     * @default 'http://localhost:4318/v1/traces'
+     */
+    endpoint?: string;
+    /**
+     * Sampling rate between 0.0 and 1.0.
+     * @default 1.0
+     */
+    samplingRate?: number;
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@elysiumjs/argus",
-  "version": "0.1.1",
+  "version": "0.2.3",
   "license": "Apache-2.0",
   "description": "OpenTelemetry telemetry package for the Elysium.js framework.",
   "private": false,
   "author": "Workbud Technologies Inc.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/workbud/elysium"
+    "url": "git+https://github.com/na2axl/elysiumjs.git",
+    "directory": "@elysiumjs/argus"
   },
   "keywords": [
     "elysium",
@@ -19,18 +20,23 @@
     "typescript",
     "bun"
   ],
-  "homepage": "https://github.com/workbud/elysium",
-  "module": "index.ts",
+  "homepage": "https://github.com/na2axl/elysiumjs/tree/main/@elysiumjs/argus#readme",
+  "bugs": {
+    "url": "https://github.com/na2axl/elysiumjs/issues"
+  },
+  "module": "dist/index.js",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "sideEffects": [
-    "./src/sdk.ts"
+  "files": [
+    "dist",
+    "CHANGELOG.md"
   ],
+  "sideEffects": false,
   "scripts": {
     "format": "prettier --write \"./src/**/*.ts\"",
     "clean": "rimraf dist",
-    "build:js": "bun build ./src/index.ts --outdir ./dist --target bun -e @elysiumjs/* -e @opentelemetry/* --root ./src --minify",
+    "build:js": "bun build ./src/index.ts --outdir ./dist --target bun -e @elysiumjs/* -e @opentelemetry/* --root ./src --minify-syntax --minify-whitespace",
     "build:ts": "tsc",
     "build": "bun run clean && bun run build:js && bun run build:ts",
     "test": "bun test",
@@ -39,20 +45,20 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-node": "^0.57.0",
-    "@opentelemetry/sdk-trace-base": "^1.30.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
-    "@opentelemetry/resources": "^1.30.0",
-    "@opentelemetry/semantic-conventions": "^1.30.0"
+    "@opentelemetry/api": "^1.10.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.300.0",
+    "@opentelemetry/resources": "^3.0.0",
+    "@opentelemetry/sdk-node": "^0.300.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0"
   },
   "devDependencies": {
-    "@elysiumjs/core": "0.6.1",
-    "@elysiumjs/hermes": "0.3.1"
+    "@elysiumjs/core": "0.10.0",
+    "@elysiumjs/hermes": "0.4.3"
   },
   "peerDependencies": {
-    "@elysiumjs/core": "^0.6.1",
-    "@elysiumjs/hermes": "^0.3.1"
+    "@elysiumjs/core": "^0.10.0",
+    "@elysiumjs/hermes": "^0.4.3"
   },
   "peerDependenciesMeta": {
     "@elysiumjs/hermes": {

package/.turbo/turbo-build.log

@@ -1,8 +0,0 @@
-$ bun run clean && bun run build:js && bun run build:ts
-$ rimraf dist
-$ bun build ./src/index.ts --outdir ./dist --target bun -e @elysiumjs/* -e @opentelemetry/* --root ./src --minify
-Bundled 287 modules in 90ms
-
-  index.js  0.38 MB  (entry point)
-
-$ tsc

package/index.ts

@@ -1,15 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-export * from './src/index';

package/src/correlation.ts

@@ -1,45 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import { trace } from '@opentelemetry/api';
-
-/**
- * Enriches a log context object with `traceId` and `spanId` from the
- * active OpenTelemetry span.
- *
- * Use this in Hermes log calls to correlate logs with traces:
- *
- * @example
- * ```typescript
- * import { withTraceContext } from '@elysiumjs/argus';
- *
- * logger.info('Processing request', withTraceContext({ userId: '123' }));
- * // Output: { msg: "Processing request", userId: "123", traceId: "abc...", spanId: "def..." }
- * ```
- *
- * @author Axel Nana <axel.nana@workbud.com>
- * @param ctx The base context to enrich.
- * @returns The context with `traceId` and `spanId` injected if an active span exists.
- */
-export function withTraceContext(ctx: Record<string, unknown> = {}): Record<string, unknown> {
-	const span = trace.getActiveSpan();
-	if (!span) return ctx;
-
-	const spanCtx = span.spanContext();
-	return {
-		...ctx,
-		traceId: spanCtx.traceId,
-		spanId: spanCtx.spanId
-	};
-}

package/src/decorators/traced.ts

@@ -1,72 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import type { SpanOptions } from '@opentelemetry/api';
-
-import { SpanStatusCode, trace } from '@opentelemetry/api';
-
-/**
- * Decorator that wraps a method in an OpenTelemetry span.
- *
- * Creates a child span for each method invocation, recording success
- * or error status. Exceptions are recorded on the span before re-throwing.
- *
- * @example
- * ```typescript
- * class UserService {
- *   @Traced('user.findById')
- *   async findById(id: string) {
- *     return db.query('SELECT * FROM users WHERE id = $1', [id]);
- *   }
- * }
- * ```
- *
- * @author Axel Nana <axel.nana@workbud.com>
- * @param name Optional span name. Defaults to `ClassName.methodName`.
- * @param options Optional OpenTelemetry span options.
- * @returns A method decorator.
- */
-export function Traced(name?: string, options?: SpanOptions): MethodDecorator {
-	return function (
-		target: object,
-		propertyKey: string | symbol,
-		descriptor: TypedPropertyDescriptor<any>
-	) {
-		const original = descriptor.value;
-		const spanName = name ?? `${target.constructor.name}.${String(propertyKey)}`;
-
-		descriptor.value = async function (...args: any[]) {
-			const tracer = trace.getTracer('@elysiumjs/argus');
-
-			return tracer.startActiveSpan(spanName, options ?? {}, async (span) => {
-				try {
-					const result = await original.apply(this, args);
-					span.setStatus({ code: SpanStatusCode.OK });
-					return result;
-				} catch (error) {
-					span.setStatus({
-						code: SpanStatusCode.ERROR,
-						message: error instanceof Error ? error.message : 'Unknown error'
-					});
-					span.recordException(error as Error);
-					throw error;
-				} finally {
-					span.end();
-				}
-			});
-		};
-
-		return descriptor;
-	};
-}

package/src/index.ts

@@ -1,20 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-export type { TracingConfig } from './types';
-
-export { ArgusSDK } from './sdk';
-export { Traced } from './decorators/traced';
-export { withTraceContext } from './correlation';
-export { argusPlugin } from './plugin';

package/src/plugin.ts

@@ -1,62 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import { SpanStatusCode, trace } from '@opentelemetry/api';
-import { Elysia } from 'elysia';
-
-/**
- * Elysia plugin that creates OpenTelemetry request spans.
- *
- * Each HTTP request gets a span with method, path, and status information.
- * Errors (5xx) are recorded as error spans.
- *
- * @author Axel Nana <axel.nana@workbud.com>
- * @returns An Elysia plugin instance.
- */
-export const argusPlugin = () => {
-	const tracer = trace.getTracer('@elysiumjs/argus');
-
-	return new Elysia({ name: '@elysiumjs/argus' })
-		.derive(({ request }) => {
-			const url = new URL(request.url);
-			const span = tracer.startSpan(`${request.method} ${url.pathname}`, {
-				attributes: {
-					'http.method': request.method,
-					'http.url': request.url,
-					'http.target': url.pathname
-				}
-			});
-
-			return { __argusSpan: span };
-		})
-		.onAfterResponse(({ __argusSpan, request }) => {
-			if (__argusSpan) {
-				__argusSpan.setStatus({ code: SpanStatusCode.OK });
-				__argusSpan.setAttribute('http.method', request.method);
-				__argusSpan.end();
-			}
-		})
-		.onError(({ __argusSpan, error }) => {
-			if (__argusSpan) {
-				__argusSpan.setStatus({
-					code: SpanStatusCode.ERROR,
-					message: error instanceof Error ? error.message : 'Unknown error'
-				});
-				if (error instanceof Error) {
-					__argusSpan.recordException(error);
-				}
-				__argusSpan.end();
-			}
-		});
-};

package/src/sdk.ts

@@ -1,110 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import type { TracingConfig } from './types';
-
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { Resource } from '@opentelemetry/resources';
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { ConsoleSpanExporter, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';
-import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
-
-/**
- * ArgusSDK initializes OpenTelemetry for the Elysium framework.
- *
- * CRITICAL: This MUST be called before any application code runs.
- * Auto-instrumentation patches modules at import time; if app code
- * imports modules before OTel is initialized, those imports won't
- * be instrumented.
- *
- * @example
- * ```typescript
- * // src/instrument.ts (loaded FIRST via --preload or entrypoint)
- * import { ArgusSDK } from '@elysiumjs/argus';
- *
- * ArgusSDK.initialize({
- *   enabled: true,
- *   serviceName: 'my-api',
- *   exporter: 'otlp-http',
- *   endpoint: 'http://localhost:4318/v1/traces'
- * });
- * ```
- *
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export class ArgusSDK {
-	private static instance: ArgusSDK;
-	private sdk: NodeSDK | null = null;
-
-	private constructor() {}
-
-	/**
-	 * Initializes the OpenTelemetry SDK.
-	 * Can only be called once — subsequent calls are ignored with a warning.
-	 * @author Axel Nana <axel.nana@workbud.com>
-	 * @param config The tracing configuration.
-	 */
-	public static initialize(config: TracingConfig): void {
-		if (ArgusSDK.instance) {
-			console.error('[Argus] SDK already initialized. Ignoring duplicate call.');
-			return;
-		}
-
-		ArgusSDK.instance = new ArgusSDK();
-
-		if (!config.enabled) return;
-
-		const exporter = ArgusSDK.createExporter(config);
-
-		ArgusSDK.instance.sdk = new NodeSDK({
-			resource: new Resource({
-				[ATTR_SERVICE_NAME]: config.serviceName
-			}),
-			traceExporter: exporter,
-			...(config.samplingRate !== undefined && {
-				sampler: new TraceIdRatioBasedSampler(config.samplingRate)
-			})
-		});
-
-		ArgusSDK.instance.sdk.start();
-	}
-
-	/**
-	 * Creates the appropriate trace exporter based on the config.
-	 * @author Axel Nana <axel.nana@workbud.com>
-	 * @param config The tracing configuration.
-	 * @returns A span exporter instance.
-	 */
-	private static createExporter(config: TracingConfig) {
-		switch (config.exporter) {
-			case 'otlp-http':
-				return new OTLPTraceExporter({
-					url: config.endpoint ?? 'http://localhost:4318/v1/traces'
-				});
-			case 'console':
-			default:
-				return new ConsoleSpanExporter();
-		}
-	}
-
-	/**
-	 * Shuts down the OpenTelemetry SDK gracefully.
-	 * @author Axel Nana <axel.nana@workbud.com>
-	 */
-	public static async shutdown(): Promise<void> {
-		if (ArgusSDK.instance?.sdk) {
-			await ArgusSDK.instance.sdk.shutdown();
-		}
-	}
-}

package/src/types.ts

@@ -1,47 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-/**
- * Configuration for the Argus telemetry SDK.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-export interface TracingConfig {
-	/**
-	 * Whether tracing is enabled.
-	 */
-	enabled: boolean;
-
-	/**
-	 * The service name reported in spans.
-	 */
-	serviceName: string;
-
-	/**
-	 * The exporter to use. Only `otlp-http` and `console` are supported.
-	 * gRPC is not supported on Bun.
-	 */
-	exporter: 'otlp-http' | 'console';
-
-	/**
-	 * The OTLP endpoint URL.
-	 * @default 'http://localhost:4318/v1/traces'
-	 */
-	endpoint?: string;
-
-	/**
-	 * Sampling rate between 0.0 and 1.0.
-	 * @default 1.0
-	 */
-	samplingRate?: number;
-}

package/tests/correlation.test.ts

@@ -1,86 +0,0 @@
-// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import { trace } from '@opentelemetry/api';
-import { afterEach, describe, expect, it, spyOn } from 'bun:test';
-
-import { withTraceContext } from '../src/correlation';
-
-describe('withTraceContext', () => {
-	let getActiveSpanSpy: ReturnType<typeof spyOn>;
-
-	afterEach(() => {
-		getActiveSpanSpy?.mockRestore();
-	});
-
-	it('should return context unchanged when no active span', () => {
-		getActiveSpanSpy = spyOn(trace, 'getActiveSpan').mockReturnValue(undefined as any);
-
-		const ctx = { userId: '123' };
-		const result = withTraceContext(ctx);
-
-		expect(result).toEqual({ userId: '123' });
-		expect(result).toBe(ctx); // Same reference
-	});
-
-	it('should enrich context with traceId and spanId', () => {
-		const mockSpan = {
-			spanContext: () => ({
-				traceId: 'abc123',
-				spanId: 'def456',
-				traceFlags: 1
-			})
-		};
-		getActiveSpanSpy = spyOn(trace, 'getActiveSpan').mockReturnValue(mockSpan as any);
-
-		const result = withTraceContext({ userId: '123' });
-
-		expect(result.userId).toBe('123');
-		expect(result.traceId).toBe('abc123');
-		expect(result.spanId).toBe('def456');
-	});
-
-	it('should work with empty context', () => {
-		const mockSpan = {
-			spanContext: () => ({
-				traceId: 'trace-1',
-				spanId: 'span-1',
-				traceFlags: 1
-			})
-		};
-		getActiveSpanSpy = spyOn(trace, 'getActiveSpan').mockReturnValue(mockSpan as any);
-
-		const result = withTraceContext();
-
-		expect(result.traceId).toBe('trace-1');
-		expect(result.spanId).toBe('span-1');
-	});
-
-	it('should not mutate the original context', () => {
-		const mockSpan = {
-			spanContext: () => ({
-				traceId: 'trace-1',
-				spanId: 'span-1',
-				traceFlags: 1
-			})
-		};
-		getActiveSpanSpy = spyOn(trace, 'getActiveSpan').mockReturnValue(mockSpan as any);
-
-		const original = { key: 'value' };
-		const result = withTraceContext(original);
-
-		expect(original).toEqual({ key: 'value' }); // Not mutated
-		expect(result).not.toBe(original); // New object
-	});
-});