From 5537fe85ed65444359bfd066707760d6395fc7a4 Mon Sep 17 00:00:00 2001
From: Mohamed Bassem <me@mbassem.com>
Date: Mon, 29 Dec 2025 19:11:16 +0200
Subject: feat: Add open telemetry (#2318)

* feat: add OpenTelemetry tracing infrastructure

Introduce distributed tracing capabilities using OpenTelemetry:

- Add @opentelemetry packages to shared-server for tracing
- Create tracing utility module with span helpers (withSpan, addSpanEvent, etc.)
- Add tRPC middleware for automatic span creation on API calls
- Initialize tracing in API and workers entry points
- Add demo instrumentation to bookmark creation and crawler worker
- Add configuration options (OTEL_TRACING_ENABLED, OTEL_EXPORTER_OTLP_ENDPOINT, etc.)
- Document tracing configuration in environment variables docs

When enabled, traces are collected for tRPC calls, bookmark creation flow,
and crawler operations, with support for any OTLP-compatible backend (Jaeger, Tempo, etc.)

* refactor: remove tracing from workers for now

Keep tracing infrastructure but remove worker instrumentation:
- Remove tracing initialization from workers entry point
- Remove tracing instrumentation from crawler worker
- Fix formatting in tracing files

The tracing infrastructure remains available for future use.

* add hono and next tracing

* remove extra span logging

* more fixes

* update config

* some fixes

* upgrade packages

* remove unneeded packages

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 packages/trpc/index.ts       |  5 +++-
 packages/trpc/lib/tracing.ts | 63 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 packages/trpc/lib/tracing.ts

(limited to 'packages/trpc')

diff --git a/packages/trpc/index.ts b/packages/trpc/index.ts
index 555ca3ba..178703f0 100644
--- a/packages/trpc/index.ts
+++ b/packages/trpc/index.ts
@@ -6,6 +6,7 @@ import type { db } from "@karakeep/db";
 import serverConfig from "@karakeep/shared/config";
 
 import { createRateLimitMiddleware } from "./lib/rateLimit";
+import { createTracingMiddleware } from "./lib/tracing";
 import {
   apiErrorsTotalCounter,
   apiRequestDurationSummary,
@@ -86,7 +87,9 @@ export const procedure = t.procedure
     });
     end();
     return res;
-  });
+  })
+  // OpenTelemetry tracing middleware
+  .use(createTracingMiddleware());
 
 // Default public procedure rate limiting
 export const publicProcedure = procedure.use(
diff --git a/packages/trpc/lib/tracing.ts b/packages/trpc/lib/tracing.ts
new file mode 100644
index 00000000..7b4fb39f
--- /dev/null
+++ b/packages/trpc/lib/tracing.ts
@@ -0,0 +1,63 @@
+import { SpanKind } from "@opentelemetry/api";
+
+import {
+  getTracer,
+  setSpanAttributes,
+  withSpan,
+} from "@karakeep/shared-server";
+import serverConfig from "@karakeep/shared/config";
+
+import type { Context } from "../index";
+
+const tracer = getTracer("@karakeep/trpc");
+
+/**
+ * tRPC middleware that creates a span for each procedure call.
+ * This integrates OpenTelemetry tracing into the tRPC layer.
+ */
+export function createTracingMiddleware() {
+  return async function tracingMiddleware<T>(opts: {
+    ctx: Context;
+    type: "query" | "mutation" | "subscription";
+    path: string;
+    input: unknown;
+    next: () => Promise<T>;
+  }): Promise<T> {
+    // Skip if tracing is disabled
+    if (!serverConfig.tracing.enabled) {
+      return opts.next();
+    }
+
+    const spanName = `trpc.${opts.type}.${opts.path}`;
+
+    return withSpan(
+      tracer,
+      spanName,
+      {
+        kind: SpanKind.SERVER,
+        attributes: {
+          "rpc.system": "trpc",
+          "rpc.method": opts.path,
+          "rpc.type": opts.type,
+          "user.id": opts.ctx.user?.id ?? "anonymous",
+          "user.role": opts.ctx.user?.role ?? "none",
+        },
+      },
+      async () => {
+        return await opts.next();
+      },
+    );
+  };
+}
+
+/**
+ * Helper to add tracing attributes within a tRPC procedure.
+ * Use this to add custom attributes to the current span.
+ */
+export function addTracingAttributes(
+  attributes: Record<string, string | number | boolean>,
+): void {
+  if (serverConfig.tracing.enabled) {
+    setSpanAttributes(attributes);
+  }
+}
-- 
cgit v1.2.3-70-g09d2