@superblocksteam/sdk 2.0.83 → 2.0.84-next.0

package/src/telemetry/index.ts

@@ -1,16 +1,8 @@
 import os from "node:os";
-import { logs as logsAPI } from "@opentelemetry/api-logs";
-import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
-import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { trace, type Tracer } from "@opentelemetry/api";
+import { logs, type Logger } from "@opentelemetry/api-logs";
 import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
 import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
-import { Resource } from "@opentelemetry/resources";
-import { NodeSDK, logs, api } from "@opentelemetry/sdk-node";
-import {
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-} from "@opentelemetry/semantic-conventions";
 import {
   DeploymentTypeEnum,
   OBS_TAG_APPLICATION_ID,
@@ -18,10 +10,18 @@ import {
   OBS_TAG_ORG_ID,
   OBS_TAG_USER_EMAIL,
 } from "@superblocksteam/shared";
+import {
+  initNodeTelemetry,
+  getTelemetryInstance,
+  isTelemetryInitialized,
+  parseDeploymentType,
+  resetTelemetry,
+  getDefaultPolicy,
+} from "@superblocksteam/telemetry";
+// Note: dd-trace kept for LLMObs until Epic 07 completes
 import ddTrace from "dd-trace";
 import packageJson from "../../package.json" with { type: "json" };
 import {
-  ATTR_DEPLOYMENT_ENVIRONMENT,
   ATTR_SUPERBLOCKS_BASE_URL,
   ATTR_SUPERBLOCKS_CLI_TOKEN,
   ATTR_SUPERBLOCKS_CSB_ID,
@@ -29,44 +29,34 @@ import {
   ATTR_SUPERBLOCKS_USER_ID,
   getEnvironmentFromHostname,
 } from "./attributes.js";
+import { applyLocalObsEnvVars, isLocalObsEnabled } from "./local-obs.js";
 import { getLogger as getStandardLogger } from "./logging.js";
 import { getConfiguration, SERVICE_NAME } from "./util.js";
 import type { ApplicationConfigWithTokenConfigAndUserInfo } from "../types/index.js";
-import type { Tracer } from "@opentelemetry/api";
-import type { Logger } from "@opentelemetry/api-logs";
 
-let config = undefined;
+// Apply local observability env vars early, before dd-trace auto-init
+applyLocalObsEnvVars();
+
+// Configuration state
+let config: Awaited<ReturnType<typeof getConfiguration>> | undefined =
+  undefined;
 let configured = false;
-let sdkInstance: NodeSDK | undefined = undefined;
 
 /**
- * Validate and return a valid DeploymentTypeEnum value.
- * Returns CLOUD if not specified or if an invalid value is provided.
+ * Current deployment type based on SUPERBLOCKS_DEPLOYMENT_TYPE env var.
+ * Defaults to CLOUD if not specified or invalid.
  */
-function getValidDeploymentType(value: string | undefined): DeploymentTypeEnum {
-  if (!value || value === "") {
-    return DeploymentTypeEnum.CLOUD;
-  }
-  if (
-    !Object.values(DeploymentTypeEnum).includes(value as DeploymentTypeEnum)
-  ) {
+export const deploymentType = (() => {
+  try {
+    return parseDeploymentType(process.env.SUPERBLOCKS_DEPLOYMENT_TYPE);
+  } catch (error) {
     console.warn(
-      `Invalid SUPERBLOCKS_DEPLOYMENT_TYPE: "${value}". ` +
-        `Valid values are: ${Object.values(DeploymentTypeEnum).join(", ")}. ` +
-        `Defaulting to "${DeploymentTypeEnum.CLOUD}".`,
+      "[Telemetry] Invalid SUPERBLOCKS_DEPLOYMENT_TYPE, defaulting to CLOUD:",
+      error,
     );
     return DeploymentTypeEnum.CLOUD;
   }
-  return value as DeploymentTypeEnum;
-}
-
-/**
- * Current deployment type based on SUPERBLOCKS_DEPLOYMENT_TYPE env var.
- * Defaults to CLOUD if not specified. Throws if an invalid value is provided.
- */
-export const deploymentType = getValidDeploymentType(
-  process.env.SUPERBLOCKS_DEPLOYMENT_TYPE,
-);
+})();
 
 /**
  * Whether the current deployment is CLOUD_PREM.
@@ -77,16 +67,21 @@ export const deploymentType = getValidDeploymentType(
 export const isCloudPrem = deploymentType === DeploymentTypeEnum.CLOUD_PREM;
 
 async function shutdownTelemetry(): Promise<void> {
-  if (sdkInstance) {
-    await sdkInstance.shutdown();
-    sdkInstance = undefined;
-    configured = false;
+  if (isTelemetryInitialized()) {
+    try {
+      await getTelemetryInstance().shutdown();
+    } catch (error) {
+      console.error("Error during telemetry shutdown:", error);
+    } finally {
+      resetTelemetry();
+      configured = false;
+    }
   }
 }
 
 export async function configureTelemetry(
   applicationConfig?: ApplicationConfigWithTokenConfigAndUserInfo,
-) {
+): Promise<boolean> {
   const logger = getStandardLogger();
   if (configured) {
     await shutdownTelemetry();
@@ -99,21 +94,28 @@ export async function configureTelemetry(
   } catch (error) {
     console.error(error);
     configured = false;
-    return;
+    return false;
   }
 
   logger.info(
     `[INIT] Initializing telemetry for service ${config.serviceName} at Superblocks instance ${config.superblocksHostname}`,
   );
 
+  // Check for local observability mode (SUPERBLOCKS_LOCAL_OBS=true)
+  const isLocalObs = isLocalObsEnabled();
+
+  // Allow env var override for local development testing (AGENT-1048)
+  // Local obs mode always enables LLMObs
   const llmobsEnabled =
-    applicationConfig?.featureFlags.devServerLlmobsEnabled() ?? false;
+    isLocalObs ||
+    process.env.SUPERBLOCKS_LLMOBS_ENABLED === "true" ||
+    (applicationConfig?.featureFlags.devServerLlmobsEnabled() ?? false);
 
   logger.debug(
-    `[INIT] superblocks.dev-server.llmobs.enabled=${llmobsEnabled} for service ${config.serviceName}`,
+    `[INIT] superblocks.dev-server.llmobs.enabled=${llmobsEnabled} (localObs=${isLocalObs}) for service ${config.serviceName}`,
   );
 
-  // Configure dd-trace for APM and LLM tracing
+  // Configure dd-trace for LLMObs (migrated to OTEL in Epic 07)
   process.env.DD_SITE = "datadoghq.com";
   // stop ddTrace from trying to get remote configuration
   process.env.DD_REMOTE_CONFIGURATION_ENABLED = "false";
@@ -149,48 +151,68 @@ export async function configureTelemetry(
     } for service ${config.serviceName}`,
   );
 
-  // Configure OpenTelemetry for APM traces and logs
-  sdkInstance = new NodeSDK({
-    resource: Resource.default().merge(
-      new Resource({
-        [ATTR_SERVICE_NAME]: config.serviceName,
-        [ATTR_SERVICE_VERSION]: packageJson.version,
-        [ATTR_DEPLOYMENT_ENVIRONMENT]: getEnvironmentFromHostname(
-          config.superblocksHostname,
-        ),
-        [ATTR_SUPERBLOCKS_BASE_URL]: config.superblocksHostname,
-        [ATTR_SUPERBLOCKS_CLI_TOKEN]: config.token,
-        [ATTR_SUPERBLOCKS_IS_CSB]: !!process.env.SUPERBLOCKS_IS_CSB,
-        [ATTR_SUPERBLOCKS_CSB_ID]: process.env.SUPERBLOCKS_IS_CSB
-          ? os.hostname()
-          : undefined,
-        [OBS_TAG_APPLICATION_ID]: applicationConfig?.id,
-        [OBS_TAG_BRANCH]: applicationConfig?.branchName,
-        [OBS_TAG_USER_EMAIL]: applicationConfig?.userEmail,
-        [ATTR_SUPERBLOCKS_USER_ID]: applicationConfig?.userId,
-        [OBS_TAG_ORG_ID]: applicationConfig?.organizationId,
-      }),
-    ),
-    // APM traces exported via OTEL
-    traceExporter: new OTLPTraceExporter({
-      url: config.superblocksTracesUrl,
-    }),
-    logRecordProcessors: [
-      new logs.SimpleLogRecordProcessor(
-        new OTLPLogExporter({ url: config.superblocksLogsUrl }),
-      ),
-    ],
-    contextManager: new AsyncLocalStorageContextManager(),
-    instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
-  });
+  // Configure OpenTelemetry for APM traces and logs via shared telemetry package
+  const policy = getDefaultPolicy(deploymentType);
+
+  try {
+    initNodeTelemetry(
+      {
+        serviceName: config.serviceName,
+        serviceVersion: packageJson.version,
+        environment: getEnvironmentFromHostname(config.superblocksHostname),
+        otlpUrl: config.otlpBaseUrl,
+        resourceAttributes: {
+          [ATTR_SUPERBLOCKS_BASE_URL]: config.superblocksHostname,
+          [ATTR_SUPERBLOCKS_CLI_TOKEN]: config.token,
+          [ATTR_SUPERBLOCKS_IS_CSB]: String(!!process.env.SUPERBLOCKS_IS_CSB),
+          ...(process.env.SUPERBLOCKS_IS_CSB && {
+            [ATTR_SUPERBLOCKS_CSB_ID]: os.hostname(),
+          }),
+          ...(applicationConfig?.id && {
+            [OBS_TAG_APPLICATION_ID]: applicationConfig.id,
+          }),
+          ...(applicationConfig?.branchName && {
+            [OBS_TAG_BRANCH]: applicationConfig.branchName,
+          }),
+          ...(applicationConfig?.userEmail && {
+            [OBS_TAG_USER_EMAIL]: applicationConfig.userEmail,
+          }),
+          ...(applicationConfig?.userId && {
+            [ATTR_SUPERBLOCKS_USER_ID]: applicationConfig.userId,
+          }),
+          ...(applicationConfig?.organizationId && {
+            [OBS_TAG_ORG_ID]: applicationConfig.organizationId,
+          }),
+        },
+        instrumentations: [
+          new HttpInstrumentation(),
+          new ExpressInstrumentation(),
+        ],
+        logsEnabled: true,
+      },
+      policy,
+    );
+  } catch (error) {
+    console.error("[Telemetry] Failed to initialize OpenTelemetry:", error);
+    configured = false;
+    return false;
+  }
 
-  sdkInstance.start();
+  return true;
 }
 
 export function getLogger(): Logger {
-  return logsAPI.getLogger(SERVICE_NAME, packageJson.version);
+  if (isTelemetryInitialized()) {
+    return getTelemetryInstance().getLogger(SERVICE_NAME);
+  }
+  // Fallback to global API if telemetry not initialized
+  return logs.getLogger(SERVICE_NAME, packageJson.version);
 }
 
 export function getTracer(): Tracer {
-  return api.trace.getTracer(SERVICE_NAME, packageJson.version);
+  if (isTelemetryInitialized()) {
+    return getTelemetryInstance().getTracer(SERVICE_NAME);
+  }
+  // Fallback to global API if telemetry not initialized
+  return trace.getTracer(SERVICE_NAME, packageJson.version);
 }

package/src/telemetry/local-obs.ts

@@ -0,0 +1,138 @@
+/**
+ * Local Observability Configuration
+ *
+ * Provides a single toggle (SUPERBLOCKS_LOCAL_OBS=true) that auto-configures
+ * all environment variables needed for local observability testing with the
+ * LGTM stack (Loki, Grafana, Tempo, Mimir).
+ *
+ * This eliminates the need to manually set 9+ environment variables:
+ * - SUPERBLOCKS_DEPLOYMENT_TYPE
+ * - SUPERBLOCKS_LLMOBS_ENABLED
+ * - OTEL_EXPORTER_OTLP_ENDPOINT
+ * - SUPERBLOCKS_OTEL_COLLECTOR_URL
+ * - DD_LLMOBS_ENABLED
+ * - DD_LLMOBS_ML_APP
+ * - DD_LLMOBS_AGENTLESS_ENABLED
+ * - DD_SITE
+ * - DD_API_KEY
+ *
+ * Usage:
+ *   SUPERBLOCKS_LOCAL_OBS=true pnpm start:all
+ *
+ * Or with custom OTEL endpoint:
+ *   SUPERBLOCKS_LOCAL_OBS=true OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 pnpm start:all
+ */
+
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+
+const DEFAULT_LOCAL_OTEL_ENDPOINT = "http://localhost:24318";
+const DEFAULT_ML_APP_NAME = "superblocks-ai-code-gen";
+
+export interface LocalObsConfig {
+  /** Whether local observability mode is enabled */
+  enabled: boolean;
+  /** OTEL endpoint for traces, metrics, logs */
+  otelEndpoint: string;
+  /** Deployment type (cloud-prem for local obs) */
+  deploymentType: DeploymentTypeEnum.CLOUD_PREM;
+  /** LLMObs configuration */
+  llmobs: {
+    enabled: true;
+    mlApp: string;
+    agentlessEnabled: true;
+  };
+  /** Datadog configuration for dd-trace */
+  datadog: {
+    site: string;
+    apiKey: string;
+  };
+}
+
+/**
+ * Checks if local observability mode is enabled.
+ *
+ * Returns true if:
+ * - SUPERBLOCKS_LOCAL_OBS=true (primary toggle)
+ * - OR all required env vars are manually configured (legacy mode)
+ */
+export function isLocalObsEnabled(): boolean {
+  // Primary toggle
+  if (process.env.SUPERBLOCKS_LOCAL_OBS === "true") {
+    return true;
+  }
+
+  // Legacy mode: all env vars manually configured
+  const hasLegacyConfig =
+    process.env.SUPERBLOCKS_DEPLOYMENT_TYPE === DeploymentTypeEnum.CLOUD_PREM &&
+    process.env.SUPERBLOCKS_LLMOBS_ENABLED === "true" &&
+    !!process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+
+  return hasLegacyConfig;
+}
+
+/**
+ * Gets the local observability configuration.
+ *
+ * When SUPERBLOCKS_LOCAL_OBS=true, this returns a complete configuration
+ * with sensible defaults for local development. Individual values can still
+ * be overridden via environment variables.
+ *
+ * @returns LocalObsConfig if local obs is enabled, null otherwise
+ */
+export function getLocalObsConfig(): LocalObsConfig | null {
+  if (!isLocalObsEnabled()) {
+    return null;
+  }
+
+  return {
+    enabled: true,
+    otelEndpoint:
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_LOCAL_OTEL_ENDPOINT,
+    deploymentType: DeploymentTypeEnum.CLOUD_PREM,
+    llmobs: {
+      enabled: true,
+      mlApp: process.env.DD_LLMOBS_ML_APP || DEFAULT_ML_APP_NAME,
+      agentlessEnabled: true,
+    },
+    datadog: {
+      site: process.env.DD_SITE || "datadoghq.com",
+      // Dummy key for agentless mode - not used when exporting to local OTEL
+      apiKey: process.env.DD_API_KEY || "local-dev-dummy-key",
+    },
+  };
+}
+
+/**
+ * Applies local observability configuration to process.env.
+ *
+ * This ensures that all downstream code that reads env vars directly
+ * (like dd-trace auto-initialization) gets the correct values.
+ *
+ * Should be called early in the application lifecycle, before any
+ * telemetry initialization occurs.
+ */
+export function applyLocalObsEnvVars(): void {
+  const config = getLocalObsConfig();
+  if (!config) {
+    return;
+  }
+
+  // Apply env vars if not already set (allow explicit overrides)
+  const envDefaults: Record<string, string> = {
+    SUPERBLOCKS_DEPLOYMENT_TYPE: config.deploymentType,
+    SUPERBLOCKS_LLMOBS_ENABLED: "true",
+    OTEL_EXPORTER_OTLP_ENDPOINT: config.otelEndpoint,
+    SUPERBLOCKS_OTEL_COLLECTOR_URL: config.otelEndpoint,
+    DD_LLMOBS_ENABLED: "1",
+    DD_LLMOBS_ML_APP: config.llmobs.mlApp,
+    DD_LLMOBS_AGENTLESS_ENABLED: "1",
+    DD_SITE: config.datadog.site,
+    DD_API_KEY: config.datadog.apiKey,
+  };
+
+  for (const [key, value] of Object.entries(envDefaults)) {
+    if (!process.env[key]) {
+      process.env[key] = value;
+    }
+  }
+}

package/src/telemetry/util.ts

@@ -2,12 +2,36 @@ import { getLocalTokenWithUrl } from "@superblocksteam/util";
 
 export const SERVICE_NAME = "sdk-dev-server";
 
+/**
+ * Get the OTLP base URL for telemetry export.
+ *
+ * Priority:
+ * 1. SUPERBLOCKS_OTEL_COLLECTOR_URL env var (for local obs mode)
+ * 2. Superblocks API endpoint derived from base URL
+ *
+ * When SUPERBLOCKS_OTEL_COLLECTOR_URL is set (e.g., http://localhost:24318),
+ * telemetry is sent directly to the local OTEL collector.
+ *
+ * Note: This returns the BASE URL. The telemetry library appends /v1/traces,
+ * /v1/metrics, /v1/logs to this URL.
+ */
+function getOtlpBaseUrl(superblocksBaseUrl: URL): string {
+  const localOtelUrl = process.env.SUPERBLOCKS_OTEL_COLLECTOR_URL;
+  if (localOtelUrl) {
+    // Remove trailing /v1/traces etc. if present (just use base URL)
+    return localOtelUrl.replace(/\/v1\/(traces|metrics|logs)$/, "");
+  }
+  // Default: Superblocks API proxies OTLP requests
+  // The server expects /api/v1/traces but the telemetry lib adds /v1/traces,
+  // so we return /api and let telemetry lib append /v1/traces
+  return superblocksBaseUrl.origin + "/api";
+}
+
 export async function getConfiguration() {
   try {
     const tokenWithUrl = await getLocalTokenWithUrl();
     const superblocksBaseUrl = new URL(tokenWithUrl.superblocksBaseUrl);
-    const superblocksTracesUrl = superblocksBaseUrl.origin + "/api/v1/traces";
-    const superblocksLogsUrl = superblocksBaseUrl.origin + "/api/v1/logs";
+    const otlpBaseUrl = getOtlpBaseUrl(superblocksBaseUrl);
     const superblocksHostname = superblocksBaseUrl.hostname;
     let token = "";
     if ("token" in tokenWithUrl) {
@@ -15,8 +39,7 @@ export async function getConfiguration() {
     }
     return {
       superblocksBaseUrl,
-      superblocksTracesUrl,
-      superblocksLogsUrl,
+      otlpBaseUrl,
       superblocksHostname,
       serviceName: SERVICE_NAME,
       token,