feat: add OpenTelemetry distributed tracing (enterprise) (#232)

* feat(tracing): add OpenTelemetry dependencies and --import preload flag * feat(enterprise): add distributed_tracing feature gate * feat(tracing): add SDK bootstrap with enterprise gating * fix(tracing): correct test coverage for enterprise-unavailable path and prevent double-init Test 2 now mocks @snapotter/enterprise to throw an import error, exercising the catch block in the preload. Test 3 imports with no endpoint so the preload is a no-op, avoiding leaked SDK from double-initialization. Added idempotency guard to initTracing() as a safety net. * feat(tracing): add Pino trace mixin and shared logger When OTel tracing is active, every Pino log line now includes traceId, spanId, and traceFlags fields for log-to-trace correlation. The mixin is a no-op when no SDK is registered (community users). * feat(tracing): add _otel to ToolJobData and inject trace context at enqueue Add optional _otel carrier field to ToolJobData for W3C trace context propagation across BullMQ job boundaries. When an active OTel span exists, propagation.inject() writes traceparent/tracestate into the job data before queue.add(). When no SDK is registered (community edition), the carrier stays empty and _otel remains undefined -- zero overhead. * feat(tracing): extract trace context and create spans in BullMQ worker * feat(tracing): inject trace context into Python sidecar calls * feat(tracing): add trace context extraction to Python sidecar * feat(tracing): add shutdownTracing to graceful shutdown sequence * feat(tracing): enrich HTTP spans with tool_id and user_id attributes * docs: add OpenTelemetry env var documentation to .env.example * test(tracing): add lifecycle integration tests for trace propagation * fix(tracing): inject trace context into pipeline and batch flow jobs * fix(tracing): add sidecar.execute Node-side span and remove unnecessary comment Wraps PythonDispatcher.run() with a sidecar.execute span on the Node side so traces show the full round-trip (Node span -> Python span). Also removes an obvious comment from logger.ts.
2026-08-03 07:46:42 +02:00 · 2026-06-15 12:53:06 +08:00
parent 5af1ac4dcf
commit 3fb8164fa5
25 changed files with 1968 additions and 320 deletions
@@ -0,0 +1,93 @@
+import { createRequire } from "node:module";
+import type { SpanExporter } from "@opentelemetry/sdk-trace-base";
+
+let _active = false;
+let _sdk: { shutdown(): Promise<void> } | null = null;
+
+export function isTracingActive(): boolean {
+  return _active;
+}
+
+export async function initTracing(options: { exporter?: SpanExporter } = {}): Promise<void> {
+  if (_active) return;
+
+  const { NodeSDK } = await import("@opentelemetry/sdk-node");
+  const { BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
+  const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+  const { defaultResource, resourceFromAttributes } = await import("@opentelemetry/resources");
+  const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } = await import(
+    "@opentelemetry/semantic-conventions"
+  );
+  const { HttpInstrumentation } = await import("@opentelemetry/instrumentation-http");
+  const { FastifyInstrumentation } = await import("@opentelemetry/instrumentation-fastify");
+  const { PgInstrumentation } = await import("@opentelemetry/instrumentation-pg");
+  const { IORedisInstrumentation } = await import("@opentelemetry/instrumentation-ioredis");
+  const { AwsInstrumentation } = await import("@opentelemetry/instrumentation-aws-sdk");
+
+  const require = createRequire(import.meta.url);
+  const { version } = require("../package.json");
+
+  const exporter = options.exporter ?? new OTLPTraceExporter();
+
+  const resource = defaultResource().merge(
+    resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: "snapotter-api",
+      [ATTR_SERVICE_VERSION]: version,
+    }),
+  );
+
+  const sdk = new NodeSDK({
+    resource,
+    spanProcessors: [new BatchSpanProcessor(exporter)],
+    instrumentations: [
+      new HttpInstrumentation({
+        ignoreOutgoingRequestHook: (req) => {
+          const host = req.hostname || req.host || "";
+          return host.includes("posthog") || host.includes("sentry");
+        },
+      }),
+      new FastifyInstrumentation(),
+      new PgInstrumentation(),
+      new IORedisInstrumentation({
+        requireParentSpan: true,
+        dbStatementSerializer: (cmd, args) => {
+          if (cmd === "evalsha" || cmd === "eval") return `${cmd} <lua>`;
+          return `${cmd} ${(args ?? []).slice(0, 2).join(" ")}`;
+        },
+      }),
+      new AwsInstrumentation(),
+    ],
+  });
+
+  sdk.start();
+  _sdk = sdk;
+  _active = true;
+}
+
+export async function shutdownTracing(): Promise<void> {
+  if (_sdk) {
+    await _sdk.shutdown().catch(() => {});
+    _sdk = null;
+    _active = false;
+  }
+}
+
+// -- Preload entry point --
+// When loaded via --import, this top-level await runs before the app.
+
+const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+if (endpoint) {
+  try {
+    const enterprise = await import("@snapotter/enterprise");
+    const licenseKey = process.env.LICENSE_KEY ?? "";
+    if (licenseKey) {
+      enterprise.initEnterprise(licenseKey);
+    }
+    if (enterprise.isFeatureEnabled("distributed_tracing")) {
+      await initTracing();
+      console.log("[tracing] OpenTelemetry initialized, exporting to", endpoint);
+    }
+  } catch {
+    // Enterprise package not available or license invalid -- tracing stays off
+  }
+}