@elysiumjs/argus 0.1.0

package/index.ts

@@ -0,0 +1,15 @@
+// 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/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@elysiumjs/argus",
+	"version": "0.1.0",
+	"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"
+	},
+	"keywords": [
+		"elysium",
+		"framework",
+		"telemetry",
+		"opentelemetry",
+		"tracing",
+		"observability",
+		"typescript",
+		"bun"
+	],
+	"homepage": "https://github.com/workbud/elysium",
+	"module": "index.ts",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"sideEffects": ["./src/sdk.ts"],
+	"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:ts": "tsc",
+		"build": "bun run clean && bun run build:js && bun run build:ts",
+		"test": "bun test",
+		"test:coverage": "bun test --coverage",
+		"typecheck": "tsc --noEmit",
+		"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"
+	},
+	"devDependencies": {
+		"@elysiumjs/core": "workspace:*",
+		"@elysiumjs/hermes": "workspace:*"
+	},
+	"peerDependencies": {
+		"@elysiumjs/core": "workspace:^",
+		"@elysiumjs/hermes": "workspace:^"
+	},
+	"peerDependenciesMeta": {
+		"@elysiumjs/hermes": {
+			"optional": true
+		}
+	}
+}

package/src/correlation.ts

@@ -0,0 +1,45 @@
+// 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

@@ -0,0 +1,72 @@
+// 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

@@ -0,0 +1,20 @@
+// 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

@@ -0,0 +1,62 @@
+// 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

@@ -0,0 +1,110 @@
+// 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

@@ -0,0 +1,47 @@
+// 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

@@ -0,0 +1,86 @@
+// 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
+	});
+});

package/tests/sdk.test.ts

@@ -0,0 +1,129 @@
+// 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 { afterAll, beforeEach, describe, expect, it, spyOn } from 'bun:test';
+
+import { ArgusSDK } from '../src/sdk';
+
+describe('ArgusSDK', () => {
+	beforeEach(async () => {
+		// Shut down any existing SDK before resetting
+		await ArgusSDK.shutdown();
+		(ArgusSDK as any).instance = undefined;
+	});
+
+	afterAll(async () => {
+		await ArgusSDK.shutdown();
+		(ArgusSDK as any).instance = undefined;
+	});
+
+	describe('initialize', () => {
+		it('should create an instance when enabled is false', () => {
+			ArgusSDK.initialize({
+				enabled: false,
+				serviceName: 'test-service',
+				exporter: 'console'
+			});
+
+			// Should not throw, instance is created but SDK not started
+			expect((ArgusSDK as any).instance).toBeDefined();
+		});
+
+		it('should log error on duplicate initialization', () => {
+			const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
+
+			ArgusSDK.initialize({
+				enabled: false,
+				serviceName: 'test-1',
+				exporter: 'console'
+			});
+
+			ArgusSDK.initialize({
+				enabled: false,
+				serviceName: 'test-2',
+				exporter: 'console'
+			});
+
+			expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('already initialized'));
+
+			errorSpy.mockRestore();
+		});
+
+		it('should initialize with console exporter', () => {
+			ArgusSDK.initialize({
+				enabled: true,
+				serviceName: 'test-service',
+				exporter: 'console'
+			});
+
+			expect((ArgusSDK as any).instance).toBeDefined();
+			expect((ArgusSDK as any).instance.sdk).toBeDefined();
+		});
+
+		it('should initialize with otlp-http exporter', () => {
+			ArgusSDK.initialize({
+				enabled: true,
+				serviceName: 'test-service',
+				exporter: 'otlp-http',
+				endpoint: 'http://localhost:4318/v1/traces'
+			});
+
+			expect((ArgusSDK as any).instance).toBeDefined();
+			expect((ArgusSDK as any).instance.sdk).toBeDefined();
+		});
+
+		it('should accept samplingRate option', () => {
+			ArgusSDK.initialize({
+				enabled: true,
+				serviceName: 'test-service',
+				exporter: 'console',
+				samplingRate: 0.5
+			});
+
+			expect((ArgusSDK as any).instance.sdk).toBeDefined();
+		});
+	});
+
+	describe('shutdown', () => {
+		it('should not throw when not initialized', async () => {
+			await expect(ArgusSDK.shutdown()).resolves.toBeUndefined();
+		});
+
+		it('should not throw when initialized but disabled', async () => {
+			ArgusSDK.initialize({
+				enabled: false,
+				serviceName: 'test-service',
+				exporter: 'console'
+			});
+
+			await expect(ArgusSDK.shutdown()).resolves.toBeUndefined();
+		});
+
+		it('should shut down the SDK when initialized', async () => {
+			ArgusSDK.initialize({
+				enabled: true,
+				serviceName: 'test-service',
+				exporter: 'console'
+			});
+
+			const sdk = (ArgusSDK as any).instance.sdk;
+			const shutdownSpy = spyOn(sdk, 'shutdown').mockResolvedValue(undefined);
+
+			await ArgusSDK.shutdown();
+			expect(shutdownSpy).toHaveBeenCalled();
+
+			shutdownSpy.mockRestore();
+		});
+	});
+});

package/tests/setup.ts

@@ -0,0 +1,24 @@
+// 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 'reflect-metadata';
+
+import { mock } from 'bun:test';
+
+mock.module('node:async_hooks', () => ({
+	AsyncLocalStorage: class {
+		public run = mock((_map: any, callback: any) => callback());
+		public disable = mock();
+	}
+}));