feat: add extra instrumentation in the otel traces (#2453)

2 files changed, 52 insertions, 5 deletions

diff --git a/packages/shared-server/src/tracing.ts b/packages/shared-server/src/tracing.ts
index e831e019..10222f88 100644
--- a/packages/shared-server/src/tracing.ts
+++ b/packages/shared-server/src/tracing.ts
@@ -24,6 +24,10 @@ import {
 import serverConfig from "@karakeep/shared/config";
 import logger from "@karakeep/shared/logger";
 
+import type { TracingAttributes } from "./tracingTypes";
+
+export type { TracingAttributeKey, TracingAttributes } from "./tracingTypes";
+
 let tracerProvider: NodeTracerProvider | null = null;
 let isInitialized = false;
 
@@ -129,7 +133,7 @@ export async function withSpan<T>(
   spanName: string,
   options: {
     kind?: SpanKind;
-    attributes?: Record<string, string | number | boolean>;
+    attributes?: TracingAttributes;
   },
   fn: (span: Span) => Promise<T>,
 ): Promise<T> {
@@ -168,7 +172,7 @@ export function withSpanSync<T>(
   spanName: string,
   options: {
     kind?: SpanKind;
-    attributes?: Record<string, string | number | boolean>;
+    attributes?: TracingAttributes;
   },
   fn: (span: Span) => T,
 ): T {
@@ -213,9 +217,7 @@ export function addSpanEvent(
 /**
  * Set attributes on the current active span.
  */
-export function setSpanAttributes(
-  attributes: Record<string, string | number | boolean>,
-): void {
+export function setSpanAttributes(attributes: TracingAttributes): void {
   const span = getActiveSpan();
   if (span) {
     span.setAttributes(attributes);
diff --git a/packages/shared-server/src/tracingTypes.ts b/packages/shared-server/src/tracingTypes.ts
new file mode 100644
index 00000000..f397fa6f
--- /dev/null
+++ b/packages/shared-server/src/tracingTypes.ts
@@ -0,0 +1,45 @@
+export type TracingAttributeKey =
+  // User attributes
+  | "user.id"
+  | "user.role"
+  | "user.tier"
+  // RPC attributes
+  | "rpc.system"
+  | "rpc.method"
+  | "rpc.type"
+  // Job attributes
+  | "job.id"
+  | "job.priority"
+  | "job.runNumber"
+  | "job.groupId"
+  // Bookmark attributes
+  | "bookmark.id"
+  | "bookmark.url"
+  | "bookmark.domain"
+  | "bookmark.content.size"
+  | "bookmark.content.type"
+  // Asset attributes
+  | "asset.id"
+  | "asset.type"
+  | "asset.size"
+  // Crawler-specific attributes
+  | "crawler.forceStorePdf"
+  | "crawler.archiveFullPage"
+  | "crawler.hasPrecrawledArchive"
+  | "crawler.getContentType.statusCode"
+  | "crawler.contentType"
+  | "crawler.statusCode"
+  // Inference-specific attributes
+  | "inference.tagging.numGeneratedTags"
+  | "inference.tagging.style"
+  | "inference.summary.size"
+  | "inference.lang"
+  | "inference.prompt.size"
+  | "inference.prompt.customCount"
+  | "inference.totalTokens"
+  | "inference.model"
+  | "inference.type";
+
+export type TracingAttributes = Partial<
+  Record<TracingAttributeKey, string | number | boolean>
+>;