@elysiumjs/argus 0.2.0 → 0.2.3

package/src/sdk.ts

@@ -1,122 +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 { resourceFromAttributes } 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: 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 class ArgusSDK {
-	private static instance: ArgusSDK | undefined;
-	private sdk: NodeSDK | null = null;
-
-	private constructor() {}
-
-	/**
-	 * Whether {@link ArgusSDK.initialize} has already been called.
-	 * @author Axel Nana <axel.nana@workbud.com>
-	 */
-	public static isInitialized(): boolean {
-		return ArgusSDK.instance !== undefined;
-	}
-
-	/**
-	 * 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: resourceFromAttributes({
-				[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();
-		}
-		ArgusSDK.instance = undefined;
-	}
-}

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/argus.module.test.ts

@@ -1,120 +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 { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { Application, MissingModuleConfigError, Module } from '@elysiumjs/core';
-import { afterEach, describe, expect, it, mock, spyOn } from 'bun:test';
-import { Elysia } from 'elysia';
-
-import { ArgusModule, argusPlugin, ArgusSDK } from '../src';
-
-const withConfig = (config: Record<string, unknown>) => {
-	@Module.register({ imports: [ArgusModule.with(config as any)] })
-	class AppModule extends Module {}
-	return AppModule;
-};
-
-describe('ArgusModule', () => {
-	afterEach(() => {
-		mock.restore();
-		(ArgusSDK as any).instance = undefined;
-	});
-
-	it('has no bare side-effect imports in its entry point', () => {
-		const source = readFileSync(join(import.meta.dir, '../src/index.ts'), 'utf8');
-		const bare = source.match(/^import\s+['"][^'"]+['"]/gm) ?? [];
-		expect(bare).toEqual([]);
-	});
-
-	it('requires a serviceName', async () => {
-		@Module.register({ imports: [ArgusModule] })
-		class Bare extends Module {}
-		await expect(Application.testing({ modules: [Bare] })).rejects.toBeInstanceOf(
-			MissingModuleConfigError
-		);
-	});
-
-	it('starts the SDK with the resolved config on init', async () => {
-		const init = spyOn(ArgusSDK, 'initialize').mockImplementation(() => {});
-		const app = await Application.testing({
-			modules: [withConfig({ serviceName: 'svc' })],
-			boot: 'eager'
-		});
-		try {
-			expect(init).toHaveBeenCalledWith(
-				expect.objectContaining({ serviceName: 'svc', enabled: true, exporter: 'console' })
-			);
-		} finally {
-			await app.shutdown();
-		}
-	});
-
-	it('installs the argus plugin on serve', async () => {
-		spyOn(ArgusSDK, 'initialize').mockImplementation(() => {});
-		const app = await Application.testing({
-			modules: [withConfig({ serviceName: 'svc' })],
-			boot: 'eager'
-		});
-		try {
-			const use = mock((_plugin: unknown) => {});
-			const instance = app.kernel.moduleInstance(app.kernel.graph.node(ArgusModule)!);
-			await instance.onServe({ use } as any);
-			expect(use).toHaveBeenCalledTimes(1);
-			const installed = (use.mock.calls[0] as unknown[])[0] as any;
-			expect(installed).toBeInstanceOf(Elysia);
-			expect(installed.config.name).toBe((argusPlugin() as any).config.name);
-		} finally {
-			await app.shutdown();
-		}
-	});
-
-	it('shuts the SDK down on destroy when it was started', async () => {
-		spyOn(ArgusSDK, 'initialize').mockImplementation(() => {});
-		const shutdown = spyOn(ArgusSDK, 'shutdown').mockResolvedValue(undefined);
-		const app = await Application.testing({
-			modules: [withConfig({ serviceName: 'svc' })],
-			boot: 'eager'
-		});
-		await app.shutdown();
-		expect(shutdown).toHaveBeenCalledTimes(1);
-	});
-
-	it('leaves a pre-initialised SDK alone', async () => {
-		const init = spyOn(ArgusSDK, 'initialize').mockImplementation(() => {});
-		const shutdown = spyOn(ArgusSDK, 'shutdown').mockResolvedValue(undefined);
-		spyOn(ArgusSDK, 'isInitialized').mockReturnValue(true);
-		const app = await Application.testing({
-			modules: [withConfig({ serviceName: 'svc' })],
-			boot: 'eager'
-		});
-		await app.shutdown();
-		expect(init).not.toHaveBeenCalled();
-		expect(shutdown).not.toHaveBeenCalled();
-	});
-
-	it('does not shut the SDK down when its init failed', async () => {
-		spyOn(ArgusSDK, 'initialize').mockImplementation(() => {
-			throw new Error('boom');
-		});
-		const shutdown = spyOn(ArgusSDK, 'shutdown').mockResolvedValue(undefined);
-		const app = await Application.testing({
-			modules: [withConfig({ serviceName: 'svc' })],
-			boot: 'eager'
-		}).catch(() => undefined);
-		await app?.shutdown();
-		expect(shutdown).not.toHaveBeenCalled();
-	});
-});

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
-	});
-});

package/tests/sdk.test.ts

@@ -1,129 +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 { 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

@@ -1,13 +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.

package/tests/traced.decorator.test.ts

@@ -1,173 +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 { afterEach, beforeEach, describe, expect, it, mock, spyOn } from 'bun:test';
-
-import { Traced } from '../src/decorators/traced';
-
-describe('@Traced decorator', () => {
-	let mockSpan: any;
-	let mockTracer: any;
-	let getTracerSpy: ReturnType<typeof spyOn>;
-
-	beforeEach(() => {
-		mockSpan = {
-			setStatus: mock(() => {}),
-			recordException: mock(() => {}),
-			end: mock(() => {})
-		};
-
-		mockTracer = {
-			startActiveSpan: mock(async (_name: string, _options: any, fn: any) => {
-				return fn(mockSpan);
-			})
-		};
-
-		getTracerSpy = spyOn(trace, 'getTracer').mockReturnValue(mockTracer);
-	});
-
-	afterEach(() => {
-		getTracerSpy.mockRestore();
-	});
-
-	it('should call the original method and return its result', async () => {
-		class MyService {
-			@Traced()
-			async greet(name: string): Promise<string> {
-				return `Hello, ${name}`;
-			}
-		}
-
-		const service = new MyService();
-		const result = await service.greet('World');
-		expect(result).toBe('Hello, World');
-	});
-
-	it('should create a span with default name', async () => {
-		class MyService {
-			@Traced()
-			async doWork(): Promise<void> {}
-		}
-
-		const service = new MyService();
-		await service.doWork();
-
-		expect(mockTracer.startActiveSpan).toHaveBeenCalled();
-		const [spanName] = mockTracer.startActiveSpan.mock.calls[0];
-		expect(spanName).toBe('MyService.doWork');
-	});
-
-	it('should create a span with custom name', async () => {
-		class MyService {
-			@Traced('custom.span.name')
-			async doWork(): Promise<void> {}
-		}
-
-		const service = new MyService();
-		await service.doWork();
-
-		const [spanName] = mockTracer.startActiveSpan.mock.calls[0];
-		expect(spanName).toBe('custom.span.name');
-	});
-
-	it('should set OK status on success', async () => {
-		class MyService {
-			@Traced()
-			async success(): Promise<string> {
-				return 'ok';
-			}
-		}
-
-		const service = new MyService();
-		await service.success();
-
-		expect(mockSpan.setStatus).toHaveBeenCalledWith({
-			code: SpanStatusCode.OK
-		});
-		expect(mockSpan.end).toHaveBeenCalled();
-	});
-
-	it('should set ERROR status and record exception on failure', async () => {
-		const error = new Error('test failure');
-
-		class MyService {
-			@Traced()
-			async failing(): Promise<void> {
-				throw error;
-			}
-		}
-
-		const service = new MyService();
-		await expect(service.failing()).rejects.toThrow('test failure');
-
-		expect(mockSpan.setStatus).toHaveBeenCalledWith({
-			code: SpanStatusCode.ERROR,
-			message: 'test failure'
-		});
-		expect(mockSpan.recordException).toHaveBeenCalledWith(error);
-		expect(mockSpan.end).toHaveBeenCalled();
-	});
-
-	it('should handle non-Error throws', async () => {
-		class MyService {
-			@Traced()
-			async throwString(): Promise<void> {
-				throw 'string error';
-			}
-		}
-
-		const service = new MyService();
-		try {
-			await service.throwString();
-		} catch {
-			// expected
-		}
-
-		expect(mockSpan.setStatus).toHaveBeenCalledWith({
-			code: SpanStatusCode.ERROR,
-			message: 'Unknown error'
-		});
-	});
-
-	it('should always end the span', async () => {
-		class MyService {
-			@Traced()
-			async mayFail(): Promise<void> {
-				throw new Error('fail');
-			}
-		}
-
-		const service = new MyService();
-		try {
-			await service.mayFail();
-		} catch {
-			// expected
-		}
-
-		expect(mockSpan.end).toHaveBeenCalledTimes(1);
-	});
-
-	it('should use the @elysiumjs/argus tracer', async () => {
-		class MyService {
-			@Traced()
-			async work(): Promise<void> {}
-		}
-
-		const service = new MyService();
-		await service.work();
-
-		expect(getTracerSpy).toHaveBeenCalledWith('@elysiumjs/argus');
-	});
-});