feat: update version to 0.2.3 and enhance OpenTelemetry tracing with new handle (#17)

Author: simpros

apps/web/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leader/web",
   "private": true,
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "scripts": {
     "dev": "vite dev",

apps/web/src/hooks.server.ts

@@ -13,6 +13,7 @@ import { and, db, eq, runMigrations, schema, withRLS } from "@leader/db";
 import { configureLogging, getLogger } from "@leader/logging";
 import { ensureInitialUserWithOrganization } from "$lib/server/bootstrap";
 import { getOtelSink } from "$lib/server/telemetry";
+import { tracingHandle } from "$lib/server/tracing-handle";
 import { randomUUIDv7 } from "bun";
 
 const ALLOW_SIGN_UP = process.env.ALLOW_SIGN_UP === "true";
@@ -253,6 +254,7 @@ const wideEventHandle: Handle = async ({ event, resolve }) => {
 };
 
 export const handle = sequence(
+  tracingHandle,
   wideEventHandle,
   requestLocaleHandle,
   sessionHandle,

apps/web/src/lib/server/telemetry.ts

@@ -1,5 +1,7 @@
 import { getOpenTelemetrySink } from "@logtape/otel";
 import type { OpenTelemetrySink } from "@logtape/otel";
+import { SpanKind, trace } from "@opentelemetry/api";
+import type { Span as ApiSpan } from "@opentelemetry/api";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
 import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
@@ -9,11 +11,58 @@ import {
   LoggerProvider,
 } from "@opentelemetry/sdk-logs";
 import { NodeSDK } from "@opentelemetry/sdk-node";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import type { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-node";
 
 let sdk: NodeSDK | null = null;
 let loggerProvider: LoggerProvider | null = null;
 let otelSink: OpenTelemetrySink | null = null;
 
+// ── SvelteKit root-span promotion ───────────────────────────────────
+// SvelteKit's built-in tracing creates `sveltekit.handle.root` as
+// SpanKind.INTERNAL.  Dynatrace (and most APM backends) require a
+// SpanKind.SERVER entry-point span to detect and link services.
+//
+// This processor intercepts root spans on start and overwrites their
+// kind to SERVER.  The handle hook (`tracingHandle`) later enriches
+// the same span with HTTP semantic-convention attributes.
+
+const rootSpansByTrace = new Map<string, ApiSpan>();
+
+const svelteKitServerSpanProcessor: SpanProcessor = {
+  onStart(span) {
+    const name = (span as unknown as ReadableSpan).name;
+    if (name === "sveltekit.handle.root") {
+      // `kind` is declared `readonly` in TS but is a plain JS property.
+      Object.defineProperty(span, "kind", {
+        value: SpanKind.SERVER,
+        writable: true,
+        configurable: true,
+      });
+      rootSpansByTrace.set(span.spanContext().traceId, span);
+    }
+  },
+  onEnd(span) {
+    if (span.name === "sveltekit.handle.root") {
+      rootSpansByTrace.delete(span.spanContext().traceId);
+    }
+  },
+  async shutdown() {
+    rootSpansByTrace.clear();
+  },
+  async forceFlush() {},
+};
+
+/**
+ * Return the promoted root SERVER span for the current trace, or
+ * `undefined` when telemetry is disabled or the span is unavailable.
+ */
+export function getRootServerSpan(): ApiSpan | undefined {
+  const active = trace.getActiveSpan();
+  if (!active) return undefined;
+  return rootSpansByTrace.get(active.spanContext().traceId);
+}
+
 /**
  * Initialise OpenTelemetry for traces and logs.
  *
@@ -54,7 +103,10 @@ export function configureTelemetry(): void {
 
   sdk = new NodeSDK({
     resource,
-    traceExporter,
+    spanProcessors: [
+      svelteKitServerSpanProcessor,
+      new BatchSpanProcessor(traceExporter),
+    ],
     instrumentations: [new HttpInstrumentation()],
   });
   sdk.start();

apps/web/src/lib/server/tracing-handle.test.ts

@@ -0,0 +1,270 @@
+import {
+  describe,
+  it,
+  expect,
+  mock,
+  beforeAll,
+  beforeEach,
+  afterAll,
+} from "bun:test";
+import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import type { Span as ApiSpan } from "@opentelemetry/api";
+import {
+  NodeTracerProvider,
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-node";
+import type { ReadableSpan } from "@opentelemetry/sdk-trace-node";
+import type { Handle } from "@sveltejs/kit";
+
+// ── mock $lib/server/telemetry ──────────────────────────────────────
+// We provide a fake `getRootServerSpan` that returns a real OTel span
+// created by the test tracer.  This simulates the promoted root span
+// that the SvelteKitServerSpanProcessor would provide in production.
+
+let fakeRootSpan: ApiSpan | undefined;
+
+mock.module("$lib/server/telemetry", () => ({
+  getRootServerSpan: () => fakeRootSpan,
+}));
+
+// ── OTel test provider ──────────────────────────────────────────────
+
+const exporter = new InMemorySpanExporter();
+const provider = new NodeTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(exporter)],
+});
+
+function getFinishedSpans(): ReadableSpan[] {
+  return exporter.getFinishedSpans();
+}
+
+// ── fake SvelteKit errors (duck-typed) ──────────────────────────────
+
+function fakeRedirect(status: number, location: string) {
+  return Object.assign(new Error("redirect"), { status, location });
+}
+
+function fakeHttpError(status: number, message: string) {
+  return Object.assign(new Error(message), {
+    status,
+    body: { message },
+  });
+}
+
+// ── mock event builder ──────────────────────────────────────────────
+
+interface MockEventOptions {
+  method?: string;
+  pathname?: string;
+  search?: string;
+  routeId?: string | null;
+  userAgent?: string | null;
+  port?: string;
+}
+
+function mockEvent(overrides: MockEventOptions = {}) {
+  const {
+    method = "GET",
+    pathname = "/test",
+    search = "",
+    routeId = "/test",
+    userAgent = "TestAgent/1.0",
+    port = "",
+  } = overrides;
+
+  return {
+    request: {
+      method,
+      headers: new Headers(userAgent ? { "user-agent": userAgent } : {}),
+    },
+    url: new URL(
+      `https://localhost${port ? `:${port}` : ""}${pathname}${search}`,
+    ),
+    route: { id: routeId },
+  };
+}
+
+// ── typed wrapper ───────────────────────────────────────────────────
+
+type HandleInput = Parameters<Handle>[0];
+
+function callHandle(
+  event: ReturnType<typeof mockEvent>,
+  resolve: () => Response | Promise<Response>,
+) {
+  return tracingHandle({
+    event: event as unknown as HandleInput["event"],
+    resolve: resolve as unknown as HandleInput["resolve"],
+  });
+}
+
+// ── tests ────────────────────────────────────────────────────────────
+
+let tracingHandle: Handle;
+let tracer: ReturnType<typeof trace.getTracer>;
+
+describe("tracingHandle", () => {
+  beforeAll(async () => {
+    provider.register();
+    tracer = trace.getTracer("test");
+    ({ tracingHandle } = await import("./tracing-handle"));
+  });
+
+  afterAll(async () => {
+    await provider.shutdown();
+    trace.disable();
+  });
+
+  beforeEach(() => {
+    exporter.reset();
+    // Create a fresh "root" span that simulates sveltekit.handle.root
+    // after promotion by SvelteKitServerSpanProcessor.
+    fakeRootSpan = tracer.startSpan("sveltekit.handle.root", {
+      kind: SpanKind.SERVER,
+    });
+  });
+
+  it("enriches the root span with HTTP attributes for a normal response", async () => {
+    const response = await callHandle(
+      mockEvent(),
+      () => new Response("ok", { status: 200 }),
+    );
+    fakeRootSpan!.end();
+
+    expect(response.status).toBe(200);
+
+    const spans = getFinishedSpans();
+    const root = spans.find((s) => s.name === "GET /test")!;
+    expect(root).toBeDefined();
+    expect(root.kind).toBe(SpanKind.SERVER);
+    expect(root.attributes["http.request.method"]).toBe("GET");
+    expect(root.attributes["url.path"]).toBe("/test");
+    expect(root.attributes["url.scheme"]).toBe("https");
+    expect(root.attributes["server.address"]).toBe("localhost");
+    expect(root.attributes["http.route"]).toBe("/test");
+    expect(root.attributes["user_agent.original"]).toBe("TestAgent/1.0");
+    expect(root.attributes["http.response.status_code"]).toBe(200);
+    expect(root.status.code).toBe(SpanStatusCode.UNSET);
+  });
+
+  it("marks the root span as ERROR for 5xx responses", async () => {
+    await callHandle(mockEvent(), () => new Response("fail", { status: 503 }));
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["http.response.status_code"]).toBe(503);
+    expect(root.status.code).toBe(SpanStatusCode.ERROR);
+  });
+
+  it("does not mark 4xx as ERROR", async () => {
+    await callHandle(
+      mockEvent(),
+      () => new Response("not found", { status: 404 }),
+    );
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["http.response.status_code"]).toBe(404);
+    expect(root.status.code).toBe(SpanStatusCode.UNSET);
+  });
+
+  it("records redirect status code without marking ERROR", async () => {
+    await expect(
+      callHandle(mockEvent(), () => {
+        throw fakeRedirect(303, "/other");
+      }),
+    ).rejects.toThrow();
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["http.response.status_code"]).toBe(303);
+    expect(root.status.code).toBe(SpanStatusCode.UNSET);
+  });
+
+  it("records HttpError status and marks ERROR for 5xx", async () => {
+    await expect(
+      callHandle(mockEvent(), () => {
+        throw fakeHttpError(502, "Bad Gateway");
+      }),
+    ).rejects.toThrow();
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["http.response.status_code"]).toBe(502);
+    expect(root.status.code).toBe(SpanStatusCode.ERROR);
+    expect(root.status.message).toBe("Bad Gateway");
+  });
+
+  it("records HttpError status without ERROR for 4xx", async () => {
+    await expect(
+      callHandle(mockEvent(), () => {
+        throw fakeHttpError(403, "Forbidden");
+      }),
+    ).rejects.toThrow();
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["http.response.status_code"]).toBe(403);
+    expect(root.status.code).toBe(SpanStatusCode.UNSET);
+  });
+
+  it("records status 500 and ERROR for unknown thrown errors", async () => {
+    await expect(
+      callHandle(mockEvent(), () => {
+        throw new Error("unexpected");
+      }),
+    ).rejects.toThrow("unexpected");
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["http.response.status_code"]).toBe(500);
+    expect(root.status.code).toBe(SpanStatusCode.ERROR);
+    expect(root.status.message).toBe("unexpected");
+  });
+
+  it("uses pathname as span name when route id is null", async () => {
+    await callHandle(
+      mockEvent({ routeId: null, pathname: "/static/file.css" }),
+      () => new Response("ok", { status: 200 }),
+    );
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find(
+      (s) => s.name === "GET /static/file.css",
+    )!;
+    expect(root).toBeDefined();
+    expect(root.attributes["http.route"]).toBeUndefined();
+  });
+
+  it("sets server.port when present", async () => {
+    await callHandle(
+      mockEvent({ port: "3000" }),
+      () => new Response("ok", { status: 200 }),
+    );
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["server.port"]).toBe(3000);
+  });
+
+  it("does not set server.port when empty", async () => {
+    await callHandle(mockEvent(), () => new Response("ok", { status: 200 }));
+    fakeRootSpan!.end();
+
+    const root = getFinishedSpans().find((s) => s.name === "GET /test")!;
+    expect(root.attributes["server.port"]).toBeUndefined();
+  });
+
+  it("is a no-op when no root span is available", async () => {
+    fakeRootSpan = undefined;
+
+    const response = await callHandle(
+      mockEvent(),
+      () => new Response("ok", { status: 200 }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(getFinishedSpans()).toHaveLength(0);
+  });
+});