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.

apps/api/src/lib/log-trace-mixin.ts

@@ -0,0 +1,8 @@
+import { trace } from "@opentelemetry/api";
+
+export function traceMixin(): Record<string, unknown> {
+  const span = trace.getActiveSpan();
+  if (!span) return {};
+  const { traceId, spanId, traceFlags } = span.spanContext();
+  return { traceId, spanId, traceFlags };
+}

apps/api/src/lib/logger.ts

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+import type { FastifyBaseLogger } from "fastify";
+import pino from "pino";
+import { env } from "../config.js";
+import { traceMixin } from "./log-trace-mixin.js";
+
+export const logger: FastifyBaseLogger = pino({
+  level: env.LOG_LEVEL,
+  mixin: traceMixin,
+  transport: {
+    targets: [
+      { target: "pino/file", options: { destination: 1 } },
+      {
+        target: "pino-roll",
+        options: {
+          file: join(env.LOG_DIR, "snapotter"),
+          extension: ".log",
+          size: "10m",
+          limit: { count: 5 },
+          mkdir: true,
+        },
+      },
+    ],
+  },
+  redact: ["req.headers.authorization", "req.headers.cookie"],
+});