@vtvlive/interactive-apm 0.0.2

package/dist/services/tracing.service.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracingService = void 0;
+/**
+ * Tracing Service - Wrapper cho ITracingProvider
+ * Service này được inject vào controllers/services để sử dụng tracing
+ *
+ * Provider implementation (OpenTelemetry hoặc Elastic APM) được inject thông qua DI
+ *
+ * @example
+ * // NestJS usage
+ * constructor(private readonly tracingService: TracingService) {}
+ *
+ * someMethod() {
+ *   const span = this.tracingService.startSpan('my.operation', { 'key': 'value' }, 'SERVER');
+ *   try {
+ *     // ... code
+ *   } finally {
+ *     span.end();
+ *   }
+ * }
+ *
+ * @example
+ * // Standalone usage
+ * const provider = createTracingProvider();
+ * const tracingService = new TracingService(provider);
+ */
+class TracingService {
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /**
+     * Bắt đầu một span mới để trace operation
+     * @param name Tên của span
+     * @param attributes Các attributes metadata
+     * @param spanKind Loại span (mặc định: INTERNAL)
+     *   - INTERNAL: Internal operation
+     *   - SERVER: Server-side request handler (API endpoints)
+     *   - CLIENT: Client-side call (outgoing HTTP, database)
+     *   - PRODUCER: Message producer
+     *   - CONSUMER: Message consumer
+     * @returns Span object - cần gọi end() khi hoàn thành
+     *
+     * @example
+     * const span = this.tracingService.startSpan('my.operation', { 'key': 'value' }, 'SERVER');
+     * try {
+     *   // ... code
+     * } finally {
+     *   span.end();
+     * }
+     */
+    startSpan(name, attributes, spanKind = 'INTERNAL') {
+        return this.provider.startSpan(name, attributes, spanKind);
+    }
+    /**
+     * Thực thi function với context tracing (auto-close span)
+     * @param name Tên của span
+     * @param fn Function cần trace
+     * @param attributes Các attributes metadata
+     * @returns Kết quả của function
+     *
+     * @example
+     * const result = await this.tracingService.startSpanWithParent(
+     *   'my.operation',
+     *   async (span) => {
+     *     span.setAttribute('custom', 'value');
+     *     return await someAsyncOperation();
+     *   }
+     * );
+     */
+    startSpanWithParent(name, fn, attributes) {
+        return this.provider.startSpanWithParent(name, fn, attributes);
+    }
+    /**
+     * Capture error vào active span hiện tại
+     * @param error Error object
+     */
+    captureError(error) {
+        this.provider.captureError(error);
+    }
+    /**
+     * Set attribute cho active span hiện tại
+     * @param key Tên attribute
+     * @param value Giá trị attribute
+     */
+    setAttribute(key, value) {
+        this.provider.setAttribute(key, value);
+    }
+    /**
+     * Kết thúc span manually
+     * @param span Span cần end (nếu không truyền, sẽ end active span)
+     */
+    endSpan(span) {
+        this.provider.endSpan(span);
+    }
+    /**
+     * Flush và shutdown APM provider (cho graceful shutdown)
+     */
+    async shutdown() {
+        await this.provider.shutdown();
+    }
+}
+exports.TracingService = TracingService;

package/dist/types/apm-provider.type.d.ts

@@ -0,0 +1,47 @@
+/**
+ * APM Provider types
+ */
+/**
+ * Enum for available APM providers
+ */
+export declare enum ApmProvider {
+    /** OpenTelemetry with OTLP exporter */
+    OPENTELEMETRY = "opentelemetry",
+    /** Elastic APM Node.js agent */
+    ELASTIC_APM = "elastic-apm"
+}
+/**
+ * Span kind types for tracing
+ */
+export declare enum SpanKind {
+    /** Internal operation */
+    INTERNAL = "INTERNAL",
+    /** Server-side request handler (API endpoints) */
+    SERVER = "SERVER",
+    /** Client-side call (outgoing HTTP, database) */
+    CLIENT = "CLIENT",
+    /** Message producer */
+    PRODUCER = "PRODUCER",
+    /** Message consumer */
+    CONSUMER = "CONSUMER"
+}
+/**
+ * APM provider configuration options
+ */
+export interface TracingProviderConfig {
+    /** Provider type */
+    provider?: ApmProvider | string;
+    /** Service name for APM */
+    serviceName?: string;
+    /** Deployment environment */
+    environment?: string;
+    /** Elastic APM server URL (for elastic-apm provider) */
+    serverUrl?: string;
+    /** Secret token for authentication */
+    secretToken?: string;
+    /** OTLP endpoint URL (for opentelemetry provider) */
+    otlpEndpoint?: string;
+    /** Service version */
+    serviceVersion?: string;
+}
+//# sourceMappingURL=apm-provider.type.d.ts.map

package/dist/types/apm-provider.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apm-provider.type.d.ts","sourceRoot":"","sources":["../../src/types/apm-provider.type.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,oBAAY,WAAW;IACrB,uCAAuC;IACvC,aAAa,kBAAkB;IAC/B,gCAAgC;IAChC,WAAW,gBAAgB;CAC5B;AAED;;GAEG;AACH,oBAAY,QAAQ;IAClB,yBAAyB;IACzB,QAAQ,aAAa;IACrB,kDAAkD;IAClD,MAAM,WAAW;IACjB,iDAAiD;IACjD,MAAM,WAAW;IACjB,uBAAuB;IACvB,QAAQ,aAAa;IACrB,uBAAuB;IACvB,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oBAAoB;IACpB,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAChC,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/types/apm-provider.type.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * APM Provider types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanKind = exports.ApmProvider = void 0;
+/**
+ * Enum for available APM providers
+ */
+var ApmProvider;
+(function (ApmProvider) {
+    /** OpenTelemetry with OTLP exporter */
+    ApmProvider["OPENTELEMETRY"] = "opentelemetry";
+    /** Elastic APM Node.js agent */
+    ApmProvider["ELASTIC_APM"] = "elastic-apm";
+})(ApmProvider || (exports.ApmProvider = ApmProvider = {}));
+/**
+ * Span kind types for tracing
+ */
+var SpanKind;
+(function (SpanKind) {
+    /** Internal operation */
+    SpanKind["INTERNAL"] = "INTERNAL";
+    /** Server-side request handler (API endpoints) */
+    SpanKind["SERVER"] = "SERVER";
+    /** Client-side call (outgoing HTTP, database) */
+    SpanKind["CLIENT"] = "CLIENT";
+    /** Message producer */
+    SpanKind["PRODUCER"] = "PRODUCER";
+    /** Message consumer */
+    SpanKind["CONSUMER"] = "CONSUMER";
+})(SpanKind || (exports.SpanKind = SpanKind = {}));

package/dist/utils/tracing.helper.d.ts

@@ -0,0 +1,68 @@
+import { Span, SpanKind } from '@opentelemetry/api';
+/**
+ * TracingHelper - Static utility class for direct OpenTelemetry usage
+ *
+ * This class provides direct access to OpenTelemetry tracing without requiring
+ * dependency injection or the TracingService wrapper.
+ *
+ * Note: This requires @opentelemetry/api to be installed.
+ *
+ * @example
+ * import { TracingHelper } from '@vtvlive/interactive-apm';
+ *
+ * const span = TracingHelper.startSpan('my.operation', { 'key': 'value' }, SpanKind.SERVER);
+ * try {
+ *   // ... code
+ * } catch (error) {
+ *   TracingHelper.captureError(error);
+ *   throw error;
+ * } finally {
+ *   TracingHelper.endSpan(span);
+ * }
+ */
+export declare class TracingHelper {
+    private static tracer;
+    /**
+     * Bắt đầu một span mới để trace operation
+     * @param name Tên của span
+     * @param attributes Các attributes metadata
+     * @param spanKind Loại span (mặc định: INTERNAL). Dùng SERVER cho API endpoints
+     * @returns Span object
+     */
+    static startSpan(name: string, attributes?: Record<string, string | number>, spanKind?: SpanKind): Span;
+    /**
+     * Thực thi function với context tracing (auto-close span)
+     * @param name Tên của span
+     * @param fn Function cần trace
+     * @param attributes Các attributes metadata
+     * @returns Kết quả của function
+     */
+    static startSpanWithParent<T>(name: string, fn: (span: Span) => Promise<T>, attributes?: Record<string, string | number>): Promise<T>;
+    /**
+     * Capture error vào active span hiện tại
+     * @param error Error object
+     */
+    static captureError(error: Error): void;
+    /**
+     * Set attribute cho active span hiện tại
+     * @param key Tên attribute
+     * @param value Giá trị attribute
+     */
+    static setAttribute(key: string, value: string | number): void;
+    /**
+     * Kết thúc span manually
+     * @param span Span cần end
+     */
+    static endSpan(span?: Span): void;
+    /**
+     * Get the current active span
+     * @returns The active span or undefined
+     */
+    static getActiveSpan(): Span | undefined;
+    /**
+     * Get the current trace ID
+     * @returns The trace ID or undefined
+     */
+    static getTraceId(): string | undefined;
+}
+//# sourceMappingURL=tracing.helper.d.ts.map

package/dist/utils/tracing.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.helper.d.ts","sourceRoot":"","sources":["../../src/utils/tracing.helper.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,IAAI,EAAkB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAsC;IAE3D;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,QAAQ,GAAE,QAA4B,GAAG,IAAI;IAa1H;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiBrI;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAQvC;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAO9D;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI;IAOjC;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI,GAAG,SAAS;IAIxC;;;OAGG;IACH,MAAM,CAAC,UAAU,IAAI,MAAM,GAAG,SAAS;CAIxC"}

package/dist/utils/tracing.helper.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracingHelper = void 0;
+// @ts-ignore - Optional peer dependency
+const api_1 = require("@opentelemetry/api");
+/**
+ * TracingHelper - Static utility class for direct OpenTelemetry usage
+ *
+ * This class provides direct access to OpenTelemetry tracing without requiring
+ * dependency injection or the TracingService wrapper.
+ *
+ * Note: This requires @opentelemetry/api to be installed.
+ *
+ * @example
+ * import { TracingHelper } from '@vtvlive/interactive-apm';
+ *
+ * const span = TracingHelper.startSpan('my.operation', { 'key': 'value' }, SpanKind.SERVER);
+ * try {
+ *   // ... code
+ * } catch (error) {
+ *   TracingHelper.captureError(error);
+ *   throw error;
+ * } finally {
+ *   TracingHelper.endSpan(span);
+ * }
+ */
+class TracingHelper {
+    /**
+     * Bắt đầu một span mới để trace operation
+     * @param name Tên của span
+     * @param attributes Các attributes metadata
+     * @param spanKind Loại span (mặc định: INTERNAL). Dùng SERVER cho API endpoints
+     * @returns Span object
+     */
+    static startSpan(name, attributes, spanKind = api_1.SpanKind.INTERNAL) {
+        const span = this.tracer.startSpan(name, {
+            attributes,
+            kind: spanKind,
+        }, api_1.context.active());
+        return span;
+    }
+    /**
+     * Thực thi function với context tracing (auto-close span)
+     * @param name Tên của span
+     * @param fn Function cần trace
+     * @param attributes Các attributes metadata
+     * @returns Kết quả của function
+     */
+    static startSpanWithParent(name, fn, attributes) {
+        return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), TracingHelper.startSpan(name, attributes)), async () => {
+            const span = api_1.trace.getActiveSpan();
+            try {
+                const result = await fn(span);
+                return result;
+            }
+            catch (error) {
+                span?.recordException(error);
+                span?.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                throw error;
+            }
+            finally {
+                span?.end();
+            }
+        });
+    }
+    /**
+     * Capture error vào active span hiện tại
+     * @param error Error object
+     */
+    static captureError(error) {
+        const span = api_1.trace.getActiveSpan();
+        if (span) {
+            span.recordException(error);
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+        }
+    }
+    /**
+     * Set attribute cho active span hiện tại
+     * @param key Tên attribute
+     * @param value Giá trị attribute
+     */
+    static setAttribute(key, value) {
+        const span = api_1.trace.getActiveSpan();
+        if (span) {
+            span.setAttribute(key, value);
+        }
+    }
+    /**
+     * Kết thúc span manually
+     * @param span Span cần end
+     */
+    static endSpan(span) {
+        const activeSpan = span || api_1.trace.getActiveSpan();
+        if (activeSpan) {
+            activeSpan.end();
+        }
+    }
+    /**
+     * Get the current active span
+     * @returns The active span or undefined
+     */
+    static getActiveSpan() {
+        return api_1.trace.getActiveSpan();
+    }
+    /**
+     * Get the current trace ID
+     * @returns The trace ID or undefined
+     */
+    static getTraceId() {
+        const span = api_1.trace.getActiveSpan();
+        return span?.spanContext().traceId;
+    }
+}
+exports.TracingHelper = TracingHelper;
+TracingHelper.tracer = api_1.trace.getTracer('interactive-apm');

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@vtvlive/interactive-apm",
+  "version": "0.0.2",
+  "description": "APM integration package supporting both Elastic APM and OpenTelemetry with NestJS integration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "keywords": [
+    "apm",
+    "elastic-apm",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "monitoring",
+    "nestjs",
+    "observability"
+  ],
+  "author": {
+    "name": "VTVLive"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:unit": "jest __tests__/unit",
+    "test:integration": "jest __tests__/integration"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
+    "@nestjs/config": "^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.0",
+    "@opentelemetry/api": "^1.0.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0",
+    "@opentelemetry/instrumentation-express": ">=0.50.0",
+    "@opentelemetry/instrumentation-http": ">=0.200.0",
+    "@opentelemetry/resources": ">=1.0.0",
+    "@opentelemetry/sdk-node": ">=0.200.0",
+    "@opentelemetry/sdk-trace-base": ">=1.0.0",
+    "@opentelemetry/semantic-conventions": ">=1.0.0",
+    "elastic-apm-node": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/config": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-express": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-http": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/semantic-conventions": {
+      "optional": true
+    },
+    "elastic-apm-node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.17",
+    "@nestjs/config": "^4.0.3",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/instrumentation-express": "^0.61.0",
+    "@opentelemetry/instrumentation-http": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@opentelemetry/sdk-trace-base": "^1.22.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "elastic-apm-node": "^4.15.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}