@vtvlive/interactive-apm 0.0.2 → 0.0.4

package/dist/providers/opentelemetry.tracing-provider.js

@@ -34,6 +34,87 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenTelemetryTracingProvider = void 0;
+const otlp_transport_type_1 = require("../types/otlp-transport.type");
+const debug_logger_1 = require("../utils/debug-logger");
+const debug_exporter_wrapper_1 = require("../utils/debug-exporter-wrapper");
+/**
+ * Transaction Name Processor for OpenTelemetry
+ * Sets transaction names to format: "GET /api/healthcheck/ping"
+ */
+class TransactionNameProcessor {
+    constructor() {
+        this.cachedSpanKind = null;
+    }
+    onStart(span) {
+        // Lazy load SpanKind to avoid top-level import failure when @opentelemetry/api is absent
+        if (!this.cachedSpanKind) {
+            try {
+                // @ts-ignore - Optional peer dependency
+                this.cachedSpanKind = require("@opentelemetry/api").SpanKind;
+            }
+            catch {
+                // If @opentelemetry/api is not available, skip processing
+                return;
+            }
+        }
+        // Only process root spans (SERVER spans without parent)
+        const s = span;
+        if (s.parent || s.kind !== this.cachedSpanKind?.SERVER) {
+            return;
+        }
+        // Get HTTP attributes - use http.target first (path + query), fallback to http.path
+        const method = s.attributes?.["http.method"];
+        const target = s.attributes?.["http.target"]; // /api/healthcheck/ping?foo=bar
+        const path = s.attributes?.["http.path"]; // fallback - just path
+        const fullPath = target || path;
+        if (method && fullPath) {
+            // Format: GET /api/healthcheck/ping
+            const fullName = `${method} ${fullPath}`;
+            s.updateName?.(fullName);
+        }
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+    onEnd(_span) {
+        // No-op - name is set in onStart
+    }
+}
+/**
+ * Normalize OTLP endpoint URL to ensure consistent format
+ * - Ensure port is included
+ * - Remove trailing slashes
+ * - For gRPC, don't add /v1/traces (it uses different path)
+ */
+function normalizeEndpoint(endpoint, isGrpc) {
+    try {
+        const url = new URL(endpoint);
+        // Ensure port is specified
+        if (!url.port) {
+            const defaultPort = url.protocol === "https:" ? "443" : "80";
+            url.port = defaultPort;
+        }
+        // Remove trailing slash
+        let pathname = url.pathname.replace(/\/+$/, "");
+        // For gRPC, remove /v1/traces as it uses different path
+        if (isGrpc && pathname.endsWith("/v1/traces")) {
+            pathname = pathname.replace("/v1/traces", "");
+        }
+        // For HTTP/PROTO, ensure /v1/traces path exists
+        if (!isGrpc && !pathname.endsWith("/v1/traces")) {
+            pathname = pathname + "/v1/traces";
+        }
+        url.pathname = pathname;
+        return url.toString();
+    }
+    catch {
+        // If URL parsing fails, return as-is
+        return endpoint;
+    }
+}
 /**
  * OpenTelemetry Tracing Provider Implementation
  * Sử dụng OpenTelemetry SDK với OTLP exporter để gửi traces về Elastic APM
@@ -43,13 +124,29 @@ class OpenTelemetryTracingProvider {
         this.sdk = null;
         this.tracer = null;
         this.initialized = false;
-        this.serviceName = config.serviceName || process.env.ELASTIC_APM_SERVICE_NAME || 'interactive-backend';
-        this.environment = config.environment || process.env.ELASTIC_APM_ENVIRONMENT || 'development';
-        this.otlpEndpoint = config.otlpEndpoint || process.env.ELASTIC_OTLP_ENDPOINT || 'http://localhost:8200/v1/traces';
-        this.secretToken = config.secretToken || process.env.ELASTIC_APM_SECRET_TOKEN || '';
-        this.otlpAuthToken = config.otlpAuthToken || process.env.ELASTIC_OTLP_AUTH_TOKEN || '';
+        this.serviceName =
+            config.serviceName || process.env.ELASTIC_APM_SERVICE_NAME || "interactive-backend";
+        this.environment = config.environment || process.env.ELASTIC_APM_ENVIRONMENT || "development";
+        this.otlpEndpoint =
+            config.otlpEndpoint || process.env.ELASTIC_OTLP_ENDPOINT || "http://localhost:8200/v1/traces";
+        // Determine transport type (HTTP, gRPC, or PROTO)
+        const transportType = (config.otlpTransport ||
+            process.env.ELASTIC_OTLP_TRANSPORT ||
+            otlp_transport_type_1.OtlpTransport.HTTP).toLowerCase();
+        if (transportType === otlp_transport_type_1.OtlpTransport.GRPC || transportType === "grpc") {
+            this.otlpTransport = otlp_transport_type_1.OtlpTransport.GRPC;
+        }
+        else if (transportType === otlp_transport_type_1.OtlpTransport.PROTO || transportType === "proto") {
+            this.otlpTransport = otlp_transport_type_1.OtlpTransport.PROTO;
+        }
+        else {
+            this.otlpTransport = otlp_transport_type_1.OtlpTransport.HTTP;
+        }
+        this.secretToken = config.secretToken || process.env.ELASTIC_APM_SECRET_TOKEN || "";
+        this.otlpAuthToken = config.otlpAuthToken || process.env.ELASTIC_OTLP_AUTH_TOKEN || "";
         this.otlpHeaders = config.otlpHeaders || {};
-        this.enableConsoleExporter = config.enableConsoleExporter ?? process.env.ELASTIC_OTLP_ENABLE_CONSOLE_EXPORTER === 'true';
+        this.enableConsoleExporter =
+            config.enableConsoleExporter ?? process.env.ELASTIC_OTLP_ENABLE_CONSOLE_EXPORTER === "true";
     }
     /**
      * Initialize OpenTelemetry SDK
@@ -62,19 +159,37 @@ class OpenTelemetryTracingProvider {
         try {
             // Dynamic import to avoid errors when @opentelemetry packages are not installed
             // @ts-ignore - Optional peer dependency
-            const { NodeSDK } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/sdk-node')));
+            const { NodeSDK } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/sdk-node")));
             // @ts-ignore - Optional peer dependency
-            const { HttpInstrumentation } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/instrumentation-http')));
+            const { HttpInstrumentation } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/instrumentation-http")));
             // @ts-ignore - Optional peer dependency
-            const { ExpressInstrumentation } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/instrumentation-express')));
+            const { ExpressInstrumentation } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/instrumentation-express")));
             // @ts-ignore - Optional peer dependency
-            const { OTLPTraceExporter } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/exporter-trace-otlp-http')));
+            const { resourceFromAttributes } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/resources")));
             // @ts-ignore - Optional peer dependency
-            const { resourceFromAttributes } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/resources')));
-            // @ts-ignore - Optional peer dependency
-            const { trace } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/api')));
-            console.log(`[OpenTelemetry] Service: ${this.serviceName}, Environment: ${this.environment}`);
-            console.log(`[OpenTelemetry] Endpoint: ${config?.otlpEndpoint || this.otlpEndpoint}`);
+            const { trace } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/api")));
+            const endpoint = config?.otlpEndpoint || this.otlpEndpoint;
+            const isGrpc = this.otlpTransport === otlp_transport_type_1.OtlpTransport.GRPC;
+            const isProto = this.otlpTransport === otlp_transport_type_1.OtlpTransport.PROTO;
+            // Normalize endpoint to ensure consistent format
+            const normalizedEndpoint = normalizeEndpoint(endpoint, isGrpc);
+            // Log initialization details when debug mode is on
+            (0, debug_logger_1.logInitialization)("OpenTelemetry", {
+                serviceName: config?.serviceName || this.serviceName,
+                environment: config?.environment || this.environment,
+                otlpEndpoint: normalizedEndpoint,
+                transport: isGrpc ? "gRPC" : isProto ? "PROTO (protobuf over HTTP)" : "HTTP",
+                hasToken: !!(config?.otlpAuthToken ||
+                    this.otlpAuthToken ||
+                    config?.secretToken ||
+                    this.secretToken),
+                enableConsoleExporter: config?.enableConsoleExporter ?? this.enableConsoleExporter,
+            });
+            const transportLabel = isGrpc ? "gRPC" : isProto ? "PROTO" : "HTTP";
+            if ((0, debug_logger_1.isDebugEnabled)()) {
+                (0, debug_logger_1.infoLog)(`[OpenTelemetry] Service: ${this.serviceName}, Environment: ${this.environment}`);
+                (0, debug_logger_1.infoLog)(`[OpenTelemetry] Endpoint: ${normalizedEndpoint} (${transportLabel})`);
+            }
             // OTLP Exporter - Build headers with Authorization
             const buildHeaders = () => {
                 const headers = {
@@ -83,35 +198,44 @@ class OpenTelemetryTracingProvider {
                 };
                 const token = config?.otlpAuthToken || this.otlpAuthToken || config?.secretToken || this.secretToken;
                 if (token) {
-                    headers['Authorization'] = `Bearer ${token}`;
+                    headers["Authorization"] = `Bearer ${token}`;
                 }
                 return Object.keys(headers).length > 0 ? headers : undefined;
             };
-            const otlpExporter = new OTLPTraceExporter({
-                url: config?.otlpEndpoint || this.otlpEndpoint,
-                headers: buildHeaders(),
-            });
-            // Wrap OTLP exporter - only log errors
-            const otlpExporterWithLogging = {
-                export: (spans, resultCallback) => {
-                    otlpExporter.export(spans, (result) => {
-                        if (result.error) {
-                            const endpoint = config?.otlpEndpoint || this.otlpEndpoint;
-                            console.error(`[OpenTelemetry] Export to ${endpoint} failed: ${result.error instanceof Error ? result.error.message : result.error}`);
-                        }
-                        resultCallback(result);
-                    });
-                },
-                shutdown: async () => {
-                    await otlpExporter.shutdown();
-                },
-            };
+            // Import the correct exporter based on transport type
+            let otlpExporter;
+            if (isGrpc) {
+                // @ts-ignore - Optional peer dependency
+                const { OTLPTraceExporter } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/exporter-trace-otlp-grpc")));
+                otlpExporter = new OTLPTraceExporter({
+                    url: normalizedEndpoint,
+                    headers: buildHeaders(),
+                });
+            }
+            else if (isProto) {
+                // @ts-ignore - Optional peer dependency
+                const { OTLPTraceExporter } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/exporter-trace-otlp-proto")));
+                otlpExporter = new OTLPTraceExporter({
+                    url: normalizedEndpoint,
+                    headers: buildHeaders(),
+                });
+            }
+            else {
+                // @ts-ignore - Optional peer dependency
+                const { OTLPTraceExporter } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/exporter-trace-otlp-http")));
+                otlpExporter = new OTLPTraceExporter({
+                    url: normalizedEndpoint,
+                    headers: buildHeaders(),
+                });
+            }
+            // Wrap with debug exporter for detailed request/response logging
+            const otlpExporterWithLogging = (0, debug_exporter_wrapper_1.createDebugExporter)(otlpExporter, normalizedEndpoint);
             // Use console exporter if enabled
             const shouldEnableConsole = config?.enableConsoleExporter ?? this.enableConsoleExporter;
             let traceExporter = otlpExporterWithLogging;
             if (shouldEnableConsole) {
                 // @ts-ignore - Optional peer dependency
-                const { ConsoleSpanExporter } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/sdk-trace-base')));
+                const { ConsoleSpanExporter } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/sdk-trace-base")));
                 const consoleExporter = new ConsoleSpanExporter();
                 // Combined Exporter để export ra cả console và OTLP
                 traceExporter = {
@@ -121,74 +245,184 @@ class OpenTelemetryTracingProvider {
                         const errors = [];
                         const checkComplete = () => {
                             if (completed === 2) {
-                                resultCallback(hasError ? { code: 1, error: new Error(errors.map(e => e.message).join('; ')) } : { code: 0 });
+                                resultCallback(hasError
+                                    ? { code: 1, error: new Error(errors.map(e => e.message).join("; ")) }
+                                    : { code: 0 });
                             }
                         };
                         // Console exporter
                         consoleExporter.export(spans, (result) => {
-                            if (result.error) {
+                            const exportResult = result;
+                            if (exportResult.error) {
                                 hasError = true;
-                                errors.push(result.error);
+                                errors.push(exportResult.error);
                             }
                             completed++;
                             checkComplete();
                         });
                         // OTLP exporter with logging
                         otlpExporterWithLogging.export(spans, (result) => {
-                            if (result.error) {
+                            const exportResult = result;
+                            if (exportResult.error) {
                                 hasError = true;
-                                errors.push(result.error);
+                                errors.push(exportResult.error);
                             }
                             completed++;
                             checkComplete();
                         });
                     },
                     shutdown: async () => {
-                        await Promise.all([consoleExporter.shutdown(), otlpExporterWithLogging.shutdown()]);
+                        await Promise.all([
+                            consoleExporter.shutdown(),
+                            otlpExporterWithLogging.shutdown(),
+                        ]);
                     },
                 };
             }
             // Resource attributes
             const sdkResource = resourceFromAttributes({
-                'service.name': config?.serviceName || this.serviceName,
-                'deployment.environment': config?.environment || this.environment,
-                'service.version': process.env.npm_package_version || '1.0.0',
-                'service.instance.id': `${process.pid}`,
-                'host.name': require('os').hostname(),
+                "service.name": config?.serviceName || this.serviceName,
+                "deployment.environment": config?.environment || this.environment,
+                "service.version": process.env.npm_package_version || "1.0.0",
+                "service.instance.id": `${process.pid}`,
+                "host.name": require("os").hostname(),
             });
+            // Use BatchSpanProcessor for efficient batching with explicit flush
+            const { BatchSpanProcessor } = await Promise.resolve().then(() => __importStar(require("@opentelemetry/sdk-trace-base")));
+            // Create a custom processor that extends BatchSpanProcessor behavior
+            // but also applies transaction naming
+            const transactionNameProcessor = new TransactionNameProcessor();
+            const batchProcessor = new BatchSpanProcessor(traceExporter);
+            // Wrap the batch processor to also do transaction naming
+            const processorWithNaming = {
+                onStart: (span, context) => {
+                    transactionNameProcessor.onStart(span);
+                    batchProcessor.onStart(span, context);
+                },
+                onEnd: (span) => {
+                    transactionNameProcessor.onEnd(span);
+                    batchProcessor.onEnd(span);
+                },
+                forceFlush: async () => {
+                    await batchProcessor.forceFlush();
+                },
+                shutdown: async () => {
+                    await batchProcessor.shutdown();
+                },
+            };
             // Khởi tạo SDK
             this.sdk = new NodeSDK({
                 serviceName: config?.serviceName || this.serviceName,
-                traceExporter,
+                traceExporter: undefined, // Don't use traceExporter when using spanProcessor
                 instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
                 resource: sdkResource,
+                spanProcessor: processorWithNaming,
             });
             // Khởi động SDK
             this.sdk.start();
+            // Install HTTP interceptor for debug mode
+            const { createHttpRequestInterceptor } = require("../utils/debug-exporter-wrapper");
+            const interceptor = createHttpRequestInterceptor();
+            if (interceptor) {
+                interceptor.install();
+            }
             // Get tracer
             this.tracer = trace.getTracer(config?.serviceName || this.serviceName);
             this.initialized = true;
-            console.log('[OpenTelemetry] Initialized');
+            if ((0, debug_logger_1.isDebugEnabled)()) {
+                (0, debug_logger_1.infoLog)("[OpenTelemetry] Initialized");
+            }
         }
         catch (error) {
-            console.error('[OpenTelemetry] Failed to initialize:', error);
+            (0, debug_logger_1.errorLog)("[OpenTelemetry] Failed to initialize:", error);
             throw error;
         }
     }
     /**
      * Bắt đầu một span mới
      */
-    startSpan(name, attributes, spanKind = 'INTERNAL') {
+    startSpan(name, attributes, spanKind = "INTERNAL") {
         if (!this.initialized || !this.tracer) {
-            console.warn('[OpenTelemetry] Not initialized');
+            if ((0, debug_logger_1.isDebugEnabled)()) {
+                console.warn("[OpenTelemetry] Not initialized");
+            }
             return null;
         }
         // @ts-ignore - Optional peer dependency
-        const { context, SpanKind } = require('@opentelemetry/api');
-        const span = this.tracer.startSpan(name, {
+        const { context } = require("@opentelemetry/api");
+        const tracer = this.tracer;
+        const span = tracer.startSpan(name, {
             attributes,
             kind: this.mapSpanKind(spanKind),
         }, context.active());
+        // Log span details when debug mode is on
+        if (span) {
+            const spanForLog = { name, kind: this.mapSpanKind(spanKind) };
+            (0, debug_logger_1.logSpan)("OpenTelemetry", spanForLog);
+        }
+        // Add end protection to prevent operations on ended span
+        if (span) {
+            let isEnded = false;
+            // Override setAttribute to check if span has ended
+            if (typeof span.setAttribute === "function") {
+                const originalSetAttribute = span.setAttribute.bind(span);
+                span.setAttribute = (key, value) => {
+                    if (isEnded) {
+                        if ((0, debug_logger_1.isDebugEnabled)()) {
+                            console.warn(`[OpenTelemetry] Cannot set attribute "${key}" on ended span "${name}". ` +
+                                `This attribute will not be sent to APM server.`);
+                        }
+                        return span;
+                    }
+                    originalSetAttribute(key, value);
+                    return span;
+                };
+            }
+            // Override recordException to check if span has ended
+            if (typeof span.recordException === "function") {
+                const originalRecordException = span.recordException.bind(span);
+                span.recordException = (error) => {
+                    if (isEnded) {
+                        if ((0, debug_logger_1.isDebugEnabled)()) {
+                            console.warn(`[OpenTelemetry] Cannot record exception on ended span "${name}". ` +
+                                `This exception will not be sent to APM server.`);
+                        }
+                        return span;
+                    }
+                    originalRecordException(error);
+                    return span;
+                };
+            }
+            // Override setStatus to check if span has ended
+            if (typeof span.setStatus === "function") {
+                const originalSetStatus = span.setStatus.bind(span);
+                span.setStatus = (status) => {
+                    if (isEnded) {
+                        if ((0, debug_logger_1.isDebugEnabled)()) {
+                            console.warn(`[OpenTelemetry] Cannot set status on ended span "${name}". ` +
+                                `This status will not be sent to APM server.`);
+                        }
+                        return span;
+                    }
+                    originalSetStatus(status);
+                    return span;
+                };
+            }
+            // Override end to prevent duplicate ends
+            if (typeof span.end === "function") {
+                const originalEnd = span.end.bind(span);
+                span.end = () => {
+                    if (isEnded) {
+                        if ((0, debug_logger_1.isDebugEnabled)()) {
+                            console.warn(`[OpenTelemetry] Span "${name}" has already been ended. Ignoring duplicate end().`);
+                        }
+                        return;
+                    }
+                    isEnded = true;
+                    originalEnd();
+                };
+            }
+        }
         return span;
     }
     /**
@@ -196,7 +430,7 @@ class OpenTelemetryTracingProvider {
      */
     async startSpanWithParent(name, fn, attributes) {
         // @ts-ignore - Optional peer dependency
-        const { context, trace, SpanStatusCode } = require('@opentelemetry/api');
+        const { context, trace, SpanStatusCode } = require("@opentelemetry/api");
         return context.with(trace.setSpan(context.active(), this.startSpan(name, attributes)), async () => {
             const span = trace.getActiveSpan();
             try {
@@ -204,8 +438,16 @@ class OpenTelemetryTracingProvider {
                 return result;
             }
             catch (error) {
-                span?.recordException(error);
-                span?.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+                if (span) {
+                    span.recordException(error);
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                }
+                if ((0, debug_logger_1.isDebugEnabled)()) {
+                    console.log(`[APM-DEBUG] [OpenTelemetry] Span failed:`, name, error.message || error);
+                }
                 throw error;
             }
             finally {
@@ -221,11 +463,14 @@ class OpenTelemetryTracingProvider {
             return;
         }
         // @ts-ignore - Optional peer dependency
-        const { trace, SpanStatusCode } = require('@opentelemetry/api');
+        const { trace, SpanStatusCode } = require("@opentelemetry/api");
         const span = trace.getActiveSpan();
         if (span) {
             span.recordException(error);
-            span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error.message,
+            });
         }
     }
     /**
@@ -236,12 +481,28 @@ class OpenTelemetryTracingProvider {
             return;
         }
         // @ts-ignore - Optional peer dependency
-        const { trace } = require('@opentelemetry/api');
+        const { trace } = require("@opentelemetry/api");
         const span = trace.getActiveSpan();
         if (span) {
             span.setAttribute(key, value);
         }
     }
+    /**
+     * Force flush all pending spans
+     */
+    async forceFlush() {
+        if (this.sdk) {
+            try {
+                await this.sdk.forceFlush();
+                if ((0, debug_logger_1.isDebugEnabled)()) {
+                    console.log("[APM-DEBUG] Force flush completed");
+                }
+            }
+            catch (error) {
+                (0, debug_logger_1.errorLog)("[OpenTelemetry] Force flush failed:", error);
+            }
+        }
+    }
     /**
      * End span manually
      */
@@ -250,7 +511,7 @@ class OpenTelemetryTracingProvider {
             return;
         }
         // @ts-ignore - Optional peer dependency
-        const { trace } = require('@opentelemetry/api');
+        const { trace } = require("@opentelemetry/api");
         const activeSpan = span || trace.getActiveSpan();
         if (activeSpan) {
             activeSpan.end();
@@ -269,17 +530,17 @@ class OpenTelemetryTracingProvider {
      */
     mapSpanKind(kind) {
         // @ts-ignore - Optional peer dependency
-        const { SpanKind } = require('@opentelemetry/api');
+        const { SpanKind } = require("@opentelemetry/api");
         switch (kind.toUpperCase()) {
-            case 'SERVER':
+            case "SERVER":
                 return SpanKind.SERVER;
-            case 'CLIENT':
+            case "CLIENT":
                 return SpanKind.CLIENT;
-            case 'PRODUCER':
+            case "PRODUCER":
                 return SpanKind.PRODUCER;
-            case 'CONSUMER':
+            case "CONSUMER":
                 return SpanKind.CONSUMER;
-            case 'INTERNAL':
+            case "INTERNAL":
             default:
                 return SpanKind.INTERNAL;
         }

package/dist/services/tracing.service.d.ts

@@ -1,4 +1,5 @@
-import { ITracingProvider } from '../interfaces/tracing-provider.interface';
+import { ITracingProvider } from "../interfaces/tracing-provider.interface";
+import { ISpan } from "../types/apm.types";
 /**
  * Tracing Service - Wrapper cho ITracingProvider
  * Service này được inject vào controllers/services để sử dụng tracing
@@ -14,7 +15,7 @@ import { ITracingProvider } from '../interfaces/tracing-provider.interface';
  *   try {
  *     // ... code
  *   } finally {
- *     span.end();
+ *     span?.end();
  *   }
  * }
  *
@@ -46,7 +47,7 @@ export declare class TracingService {
      *   span.end();
      * }
      */
-    startSpan(name: string, attributes?: Record<string, string | number>, spanKind?: string): any;
+    startSpan(name: string, attributes?: Record<string, string | number>, spanKind?: string): ISpan | null;
     /**
      * Thực thi function với context tracing (auto-close span)
      * @param name Tên của span
@@ -63,7 +64,7 @@ export declare class TracingService {
      *   }
      * );
      */
-    startSpanWithParent<T>(name: string, fn: (span: any) => Promise<T>, attributes?: Record<string, string | number>): Promise<T>;
+    startSpanWithParent<T>(name: string, fn: (span: ISpan | null) => Promise<T>, attributes?: Record<string, string | number>): Promise<T>;
     /**
      * Capture error vào active span hiện tại
      * @param error Error object
@@ -79,7 +80,7 @@ export declare class TracingService {
      * Kết thúc span manually
      * @param span Span cần end (nếu không truyền, sẽ end active span)
      */
-    endSpan(span?: any): void;
+    endSpan(span?: ISpan): void;
     /**
      * Flush và shutdown APM provider (cho graceful shutdown)
      */

package/dist/services/tracing.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.service.d.ts","sourceRoot":"","sources":["../../src/services/tracing.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,gBAAgB;IAEvD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,QAAQ,GAAE,MAAmB,GAAG,GAAG;IAIzG;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,CAAC,CAAC,EACnB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAC3C,OAAO,CAAC,CAAC,CAAC;IAIb;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIhC;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIvD;;;OAGG;IACH,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAIzB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}
+{"version":3,"file":"tracing.service.d.ts","sourceRoot":"","sources":["../../src/services/tracing.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,gBAAgB;IAEvD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAC5C,QAAQ,GAAE,MAAmB,GAC5B,KAAK,GAAG,IAAI;IAIf;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,CAAC,CAAC,EACnB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACtC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAC3C,OAAO,CAAC,CAAC,CAAC;IAIb;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIhC;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIvD;;;OAGG;IACH,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI;IAI3B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}

package/dist/services/tracing.service.js

@@ -16,7 +16,7 @@ exports.TracingService = void 0;
  *   try {
  *     // ... code
  *   } finally {
- *     span.end();
+ *     span?.end();
  *   }
  * }
  *
@@ -49,7 +49,7 @@ class TracingService {
      *   span.end();
      * }
      */
-    startSpan(name, attributes, spanKind = 'INTERNAL') {
+    startSpan(name, attributes, spanKind = "INTERNAL") {
         return this.provider.startSpan(name, attributes, spanKind);
     }
     /**