chore: support boolean for telemetry config and refactor server instrumentations (#41)

* chore: move server instrumentations to telemetry directory

* feat: support boolean for telemetry config

Author: pkosiec

apps/dev-playground/server/reconnect-plugin.ts

@@ -11,7 +11,7 @@ export class ReconnectPlugin extends Plugin {
       method: "get",
       path: "/",
       schema: z.object({ message: z.string() }),
-      handler: async (req, res) => {
+      handler: async (_req, res) => {
         res.json({ message: "Reconnected" });
       },
     });

packages/app-kit/src/server/index.ts

@@ -1,15 +1,14 @@
 import fs from "node:fs";
 import type { Server as HTTPServer } from "node:http";
 import path from "node:path";
-import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
-import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
 import { Plugin, toPlugin } from "../plugin";
 import type { BasePluginConfig, PluginPhase } from "shared";
 import { databricksClientMiddleware, isRemoteServerEnabled } from "../utils";
 import dotenv from "dotenv";
 import express from "express";
 import { DevModeManager } from "./dev-mode";
 import { getQueries, getRoutes } from "./utils";
+import { instrumentations } from "../telemetry";
 
 dotenv.config({ path: path.resolve(process.cwd(), "./server/.env") });
 
@@ -44,7 +43,10 @@ export class ServerPlugin extends Plugin {
     this.serverApplication = express();
     this.server = null;
     this.serverExtensions = [];
-    this.telemetry.registerInstrumentations(this.createInstrumentations());
+    this.telemetry.registerInstrumentations([
+      instrumentations.http,
+      instrumentations.express,
+    ]);
   }
 
   async setup() {
@@ -268,53 +270,6 @@ export class ServerPlugin extends Plugin {
       process.exit(0);
     }
   }
-
-  private createInstrumentations() {
-    return [
-      new HttpInstrumentation({
-        applyCustomAttributesOnSpan(span: any, request: any) {
-          let spanName: string | null = null;
-
-          if (request.route) {
-            const baseUrl = request.baseUrl || "";
-            const url = request.url?.split("?")[0] || "";
-            const fullPath = baseUrl + url;
-            if (fullPath) {
-              spanName = `${request.method} ${fullPath}`;
-            }
-          } else if (request.url) {
-            // No Express route (e.g., static assets) - use the raw URL path
-            // Remove query string for cleaner trace names
-            const path = request.url.split("?")[0];
-            spanName = `${request.method} ${path}`;
-          }
-
-          if (spanName) {
-            span.updateName(spanName);
-          }
-        },
-      }),
-      new ExpressInstrumentation({
-        requestHook: (span: any, info: any) => {
-          const req = info.request;
-
-          // Only update span name for route handlers (layerType: request_handler)
-          // This ensures we're not renaming middleware spans
-          if (info.layerType === "request_handler" && req.route) {
-            // Combine baseUrl with url to get full path with actual parameter values
-            // e.g., baseUrl="/api/analytics" + url="/query/spend_data" = "/api/analytics/query/spend_data"
-            const baseUrl = req.baseUrl || "";
-            const url = req.url?.split("?")[0] || "";
-            const fullPath = baseUrl + url;
-            if (fullPath) {
-              const spanName = `${req.method} ${fullPath}`;
-              span.updateName(spanName);
-            }
-          }
-        },
-      }),
-    ];
-  }
 }
 
 const EXCLUDED_PLUGINS = [ServerPlugin.name];

packages/app-kit/src/telemetry/config.ts

@@ -7,11 +7,20 @@ export interface TelemetryProviderConfig {
 }
 
 export function normalizeTelemetryOptions(
-  config: TelemetryOptions = {},
+  config?: TelemetryOptions,
 ): TelemetryProviderConfig {
+  if (typeof config === "undefined" || typeof config === "boolean") {
+    const value = config ?? true;
+    return {
+      traces: value,
+      metrics: value,
+      logs: value,
+    };
+  }
+
   return {
-    traces: config.traces ?? true,
-    metrics: config.metrics ?? true,
-    logs: config.logs ?? true,
+    traces: config?.traces ?? true,
+    metrics: config?.metrics ?? true,
+    logs: config?.logs ?? true,
   };
 }

packages/app-kit/src/telemetry/index.ts

@@ -11,6 +11,7 @@ export { context, SpanKind, SpanStatusCode } from "@opentelemetry/api";
 export type { LogAttributes, Logger, LogRecord } from "@opentelemetry/api-logs";
 export { SeverityNumber } from "@opentelemetry/api-logs";
 export { normalizeTelemetryOptions } from "./config";
+export { instrumentations } from "./instrumentations";
 export { TelemetryManager } from "./telemetry-manager";
 export { TelemetryProvider } from "./telemetry-provider";
 export type {

packages/app-kit/src/telemetry/instrumentations.ts

@@ -0,0 +1,55 @@
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import type { Instrumentation } from "@opentelemetry/instrumentation";
+
+/**
+ * Registry of pre-configured instrumentations for common use cases.
+ * These can be selectively registered by plugins that need them.
+ *
+ * While instrumentations are generally safe to re-register,
+ * the recommended approach is to register them once in a corresponding plugin constructor.
+ */
+export const instrumentations: Record<string, Instrumentation> = {
+  http: new HttpInstrumentation({
+    applyCustomAttributesOnSpan(span: any, request: any) {
+      let spanName: string | null = null;
+
+      if (request.route) {
+        const baseUrl = request.baseUrl || "";
+        const url = request.url?.split("?")[0] || "";
+        const fullPath = baseUrl + url;
+        if (fullPath) {
+          spanName = `${request.method} ${fullPath}`;
+        }
+      } else if (request.url) {
+        // No Express route (e.g., static assets) - use the raw URL path
+        // Remove query string for cleaner trace names
+        const path = request.url.split("?")[0];
+        spanName = `${request.method} ${path}`;
+      }
+
+      if (spanName) {
+        span.updateName(spanName);
+      }
+    },
+  }),
+  express: new ExpressInstrumentation({
+    requestHook: (span: any, info: any) => {
+      const req = info.request;
+
+      // Only update span name for route handlers (layerType: request_handler)
+      // This ensures we're not renaming middleware spans
+      if (info.layerType === "request_handler" && req.route) {
+        // Combine baseUrl with url to get full path with actual parameter values
+        // e.g., baseUrl="/api/analytics" + url="/query/spend_data" = "/api/analytics/query/spend_data"
+        const baseUrl = req.baseUrl || "";
+        const url = req.url?.split("?")[0] || "";
+        const fullPath = baseUrl + url;
+        if (fullPath) {
+          const spanName = `${req.method} ${fullPath}`;
+          span.updateName(spanName);
+        }
+      }
+    },
+  }),
+};

packages/app-kit/src/telemetry/tests/config.test.ts

@@ -10,19 +10,19 @@ describe("normalizeTelemetryOptions", () => {
       expected: { traces: true, metrics: true, logs: true },
     },
     {
-      description: "should return config object as-is when provided",
-      input: { traces: true, metrics: false, logs: true },
-      expected: { traces: true, metrics: false, logs: true },
+      description: "should return all enabled when config is true",
+      input: true,
+      expected: { traces: true, metrics: true, logs: true },
     },
     {
-      description: "should handle all traces/metrics/logs disabled in object",
-      input: { traces: false, metrics: false, logs: false },
+      description: "should return all disabled when config is false",
+      input: false,
       expected: { traces: false, metrics: false, logs: false },
     },
     {
-      description: "should handle all traces/metrics/logs enabled in object",
-      input: { traces: true, metrics: true, logs: true },
-      expected: { traces: true, metrics: true, logs: true },
+      description: "should return config object as-is when provided",
+      input: { traces: true, metrics: false, logs: true },
+      expected: { traces: true, metrics: false, logs: true },
     },
     {
       description:
@@ -35,6 +35,11 @@ describe("normalizeTelemetryOptions", () => {
       input: { traces: false, metrics: true, logs: false },
       expected: { traces: false, metrics: true, logs: false },
     },
+    {
+      description: "should handle partial configuration",
+      input: { traces: false },
+      expected: { traces: false, metrics: true, logs: true },
+    },
   ])("$description", ({ input, expected }) => {
     const result = normalizeTelemetryOptions(input);
     expect(result).toEqual(expected);

packages/shared/src/plugin.ts

@@ -26,11 +26,13 @@ export interface BasePluginConfig {
   telemetry?: TelemetryOptions;
 }
 
-export type TelemetryOptions = {
-  traces?: boolean;
-  metrics?: boolean;
-  logs?: boolean;
-};
+export type TelemetryOptions =
+  | boolean
+  | {
+      traces?: boolean;
+      metrics?: boolean;
+      logs?: boolean;
+    };
 
 export interface PluginConfig {
   config?: unknown;