@elysiumjs/argus 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elysiumjs/argus",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "description": "OpenTelemetry telemetry package for the Elysium.js framework.",
   "private": false,
@@ -24,13 +24,11 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "sideEffects": [
-    "./src/sdk.ts"
-  ],
+  "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 +37,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.8.0",
+    "@elysiumjs/hermes": "0.4.0"
   },
   "peerDependencies": {
-    "@elysiumjs/core": "^0.6.1",
-    "@elysiumjs/hermes": "^0.3.1"
+    "@elysiumjs/core": "^0.8.0",
+    "@elysiumjs/hermes": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@elysiumjs/hermes": {

package/src/argus.module.ts

@@ -0,0 +1,55 @@
+// 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 { Module } from '@elysiumjs/core';
+
+import { argusPlugin } from './plugin';
+import { ArgusSDK } from './sdk';
+
+/**
+ * Configurable module that starts the {@link ArgusSDK} on init, installs the request-span
+ * plugin on the root app when serving, and shuts the SDK down on destroy.
+ *
+ * If the SDK was already initialised (e.g. by a preload), the module leaves it running and
+ * does not shut it down.
+ *
+ * `serviceName` has no sensible default and is required.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+@Module.register({})
+export class ArgusModule extends Module.configurable<TracingConfig>({
+	defaults: { enabled: true, exporter: 'console' },
+	required: ['serviceName']
+}) {
+	#started = false;
+
+	public override onInit(): void {
+		// A preload (or anything else) already owns the SDK: leave it alone.
+		if (ArgusSDK.isInitialized()) return;
+		ArgusSDK.initialize(this.config);
+		this.#started = true;
+	}
+
+	public override onServe(app: Parameters<Module['onServe']>[0]): void {
+		app.use(argusPlugin());
+	}
+
+	public override async onDestroy(): Promise<void> {
+		if (!this.#started) return;
+		this.#started = false;
+		await ArgusSDK.shutdown();
+	}
+}

package/src/index.ts

@@ -18,3 +18,4 @@ export { ArgusSDK } from './sdk';
 export { Traced } from './decorators/traced';
 export { withTraceContext } from './correlation';
 export { argusPlugin } from './plugin';
+export { ArgusModule } from './argus.module';

package/src/sdk.ts

@@ -15,7 +15,7 @@
 import type { TracingConfig } from './types';
 
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { Resource } from '@opentelemetry/resources';
+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';
@@ -23,10 +23,13 @@ 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.
+ * 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
@@ -44,11 +47,19 @@ import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export class ArgusSDK {
-	private static instance: 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.
@@ -68,7 +79,7 @@ export class ArgusSDK {
 		const exporter = ArgusSDK.createExporter(config);
 
 		ArgusSDK.instance.sdk = new NodeSDK({
-			resource: new Resource({
+			resource: resourceFromAttributes({
 				[ATTR_SERVICE_NAME]: config.serviceName
 			}),
 			traceExporter: exporter,
@@ -106,5 +117,6 @@ export class ArgusSDK {
 		if (ArgusSDK.instance?.sdk) {
 			await ArgusSDK.instance.sdk.shutdown();
 		}
+		ArgusSDK.instance = undefined;
 	}
 }

package/tests/argus.module.test.ts

@@ -0,0 +1,120 @@
+// 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/setup.ts

@@ -11,14 +11,3 @@
 // 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();
-	}
-}));