@powerhousedao/reactor-api 5.1.0-dev.25 → 5.1.0-dev.27

package/dist/src/tracing.js

@@ -0,0 +1,259 @@
+/**
+ * Datadog APM Tracing Module
+ *
+ * This module provides Datadog tracing, profiling, and logging integration.
+ * Tracing is enabled when DD_TRACE_ENABLED=true or DD_ENV is set.
+ *
+ * Environment Variables (aligned with vetra-cloud ECS configuration):
+ * - DD_TRACE_ENABLED: Enable tracing (default: "false"). Set to "true" to enable.
+ * - DD_ENV: Environment name (e.g., "production", "staging"). Also enables tracing if set.
+ * - DD_SERVICE: Service name (default: "reactor-api")
+ * - DD_VERSION: Service version (default: "1.0.0" or reads from package.json)
+ * - DD_AGENT_HOST: Datadog agent host (default: "localhost")
+ * - DD_TRACE_AGENT_PORT: Datadog trace agent port (default: 8126)
+ * - DD_DOGSTATSD_PORT: DogStatsD port for metrics (default: 8125)
+ * - DD_SITE: Datadog site (default: "datadoghq.com")
+ * - DD_PROFILING_ENABLED: Enable continuous profiling (default: "true" when tracing enabled)
+ * - DD_LOGS_INJECTION: Enable log correlation (default: "true" when tracing enabled)
+ * - DD_RUNTIME_METRICS_ENABLED: Enable runtime metrics (default: "true")
+ */
+let tracer = null;
+let isInitialized = false;
+/**
+ * Check if Datadog tracing should be enabled based on environment variables.
+ * Tracing is enabled when DD_TRACE_ENABLED=true or DD_ENV is set.
+ */
+export function isTracingEnabled() {
+    return process.env.DD_TRACE_ENABLED === "true" || !!process.env.DD_ENV;
+}
+/**
+ * Initialize Datadog tracing.
+ * This should be called as early as possible in the application lifecycle,
+ * ideally before any other imports.
+ *
+ * @returns The initialized tracer instance, or null if tracing is disabled.
+ */
+export async function initTracing() {
+    if (isInitialized) {
+        return tracer;
+    }
+    isInitialized = true;
+    if (!isTracingEnabled()) {
+        return null;
+    }
+    const ddTrace = await import("dd-trace");
+    // Get version - default to "1.0.0" per vetra-cloud config, or read from package.json
+    let version = process.env.DD_VERSION;
+    if (!version) {
+        try {
+            const { readPackage } = await import("read-pkg");
+            const pkg = await readPackage();
+            version = pkg.version || "1.0.0";
+        }
+        catch {
+            version = "1.0.0";
+        }
+    }
+    const serviceName = process.env.DD_SERVICE ?? "reactor-api";
+    const env = process.env.DD_ENV ?? "development";
+    const hostname = process.env.DD_AGENT_HOST ?? "localhost";
+    const port = parseInt(process.env.DD_TRACE_AGENT_PORT ?? "8126", 10);
+    const dogstatsdPort = parseInt(process.env.DD_DOGSTATSD_PORT ?? "8125", 10);
+    // Initialize the tracer with vetra-cloud aligned configuration
+    tracer = ddTrace.default.init({
+        service: serviceName,
+        env,
+        version,
+        hostname,
+        port,
+        dogstatsd: {
+            hostname,
+            port: dogstatsdPort,
+        },
+        logInjection: process.env.DD_LOGS_INJECTION !== "false",
+        runtimeMetrics: process.env.DD_RUNTIME_METRICS_ENABLED !== "false",
+        profiling: process.env.DD_PROFILING_ENABLED !== "false",
+        // Enable common integrations
+        plugins: true,
+        // Tags for better categorization
+        tags: {
+            "dd.source": "nodejs",
+        },
+    });
+    // Enable profiling if not explicitly disabled
+    if (process.env.DD_PROFILING_ENABLED !== "false") {
+        try {
+            /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call */
+            // @ts-expect-error - dd-trace/profiling doesn't have type declarations
+            const { profiler } = await import("dd-trace/profiling");
+            profiler.start();
+            /* eslint-enable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call */
+        }
+        catch (err) {
+            console.warn("[tracing] Failed to start profiler:", err);
+        }
+    }
+    console.info(`[tracing] Datadog tracing initialized: service=${serviceName}, env=${env}, version=${version}, agent=${hostname}:${port}`);
+    return tracer;
+}
+/**
+ * Get the current tracer instance.
+ * Returns null if tracing is not initialized or disabled.
+ */
+export function getTracer() {
+    return tracer;
+}
+/**
+ * Create a new span for tracing a specific operation.
+ * If tracing is disabled, this returns a no-op wrapper.
+ *
+ * @param name - The name of the operation
+ * @param options - Optional span options
+ * @param fn - The function to trace
+ * @returns The result of the function
+ */
+export async function trace(name, options, fn) {
+    if (!tracer) {
+        return fn(undefined);
+    }
+    return tracer.trace(name, options, fn);
+}
+/**
+ * Synchronous version of trace.
+ */
+export function traceSync(name, options, fn) {
+    if (!tracer) {
+        return fn(undefined);
+    }
+    return tracer.trace(name, options, fn);
+}
+/**
+ * Add tags to the current active span.
+ */
+export function addTags(tags) {
+    if (!tracer) {
+        return;
+    }
+    const span = tracer.scope().active();
+    if (span) {
+        span.addTags(tags);
+    }
+}
+/**
+ * Set an error on the current active span.
+ */
+export function setError(error) {
+    if (!tracer) {
+        return;
+    }
+    const span = tracer.scope().active();
+    if (span) {
+        span.setTag("error", true);
+        span.setTag("error.message", error.message);
+        span.setTag("error.stack", error.stack ?? "");
+    }
+}
+/**
+ * Get trace context for log correlation.
+ * Returns trace_id and span_id for the current active span.
+ */
+export function getTraceContext() {
+    if (!tracer) {
+        return {};
+    }
+    const span = tracer.scope().active();
+    if (!span) {
+        return {
+            service: process.env.DD_SERVICE ?? "reactor-api",
+            env: process.env.DD_ENV,
+        };
+    }
+    const context = span.context();
+    return {
+        trace_id: context.toTraceId(),
+        span_id: context.toSpanId(),
+        service: process.env.DD_SERVICE ?? "reactor-api",
+        env: process.env.DD_ENV,
+    };
+}
+/**
+ * Create a structured log entry with trace correlation.
+ * This format is compatible with Datadog log ingestion via FireLens.
+ */
+export function createStructuredLog(level, message, data) {
+    const traceContext = getTraceContext();
+    const service = process.env.DD_SERVICE ?? "reactor-api";
+    const env = process.env.DD_ENV ?? "development";
+    const version = process.env.DD_VERSION ?? "1.0.0";
+    const projectName = process.env.PH_PROJECT_NAME ?? "powerhouse";
+    const log = {
+        timestamp: new Date().toISOString(),
+        level,
+        message,
+        // Datadog standard fields for log processing
+        ddsource: "nodejs",
+        ddtags: `env:${env},project:${projectName},version:${version}`,
+        service,
+        env,
+        version,
+        ...data,
+    };
+    // Add trace correlation if available
+    if (traceContext.trace_id || traceContext.span_id) {
+        log.dd = {
+            trace_id: traceContext.trace_id,
+            span_id: traceContext.span_id,
+        };
+    }
+    return log;
+}
+/**
+ * Logger that outputs structured JSON logs compatible with Datadog.
+ * When tracing is disabled, falls back to simple console logging.
+ */
+export const structuredLogger = {
+    debug(message, data) {
+        if (isTracingEnabled()) {
+            console.log(JSON.stringify(createStructuredLog("debug", message, data)));
+        }
+        else {
+            console.debug(message, data ?? "");
+        }
+    },
+    info(message, data) {
+        if (isTracingEnabled()) {
+            console.log(JSON.stringify(createStructuredLog("info", message, data)));
+        }
+        else {
+            console.info(message, data ?? "");
+        }
+    },
+    warn(message, data) {
+        if (isTracingEnabled()) {
+            console.log(JSON.stringify(createStructuredLog("warn", message, data)));
+        }
+        else {
+            console.warn(message, data ?? "");
+        }
+    },
+    error(message, error, data) {
+        const errorData = { ...data };
+        if (error instanceof Error) {
+            errorData.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            };
+        }
+        else if (error !== undefined) {
+            errorData.error = error;
+        }
+        if (isTracingEnabled()) {
+            console.log(JSON.stringify(createStructuredLog("error", message, errorData)));
+        }
+        else {
+            console.error(message, error ?? "", data ?? "");
+        }
+    },
+};
+//# sourceMappingURL=tracing.js.map

package/dist/src/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/tracing.ts"],"names":[],"mappings":"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"}