@superblocksteam/sdk 2.0.139 → 2.0.140-next.0

package/src/telemetry/otlp-config.ts

@@ -0,0 +1,250 @@
+/**
+ * Shared OTLP configuration for the dev-server CLI.
+ *
+ * This is the single source of truth for where the dev-server sends telemetry
+ * and how it tags it. It is imported by three places that must agree:
+ *   - the early telemetry preload (`preload.mts`, full OTel SDK),
+ *   - the SDK telemetry init (`util.ts` / `index.ts`),
+ *   - the lightweight dev-server parent (`parent-otlp-metric.mts`), which hand-
+ *     rolls OTLP because it must stay small and cannot load the OTel SDK.
+ *
+ * Because the parent imports this, the module MUST depend only on `node:`
+ * builtins and other import-free modules in this package (`attributes.ts`). Do
+ * NOT import OpenTelemetry, dd-trace, or the `@superblocksteam/sdk` barrel
+ * here — that would drag the SDK into the lightweight parent.
+ *
+ * Endpoint policy: the dev-server always exports through the Superblocks server's
+ * OTLP proxy at `<baseUrl>/api/v1/{traces,metrics,logs}`. The server forwards to
+ * the LGTM collector locally and to the in-cluster collector when deployed, so
+ * the client behaves identically in every environment — there is no
+ * direct-to-collector path.
+ */
+
+import * as http from "node:http";
+import * as https from "node:https";
+
+import { getEnvironmentFromHostname } from "./attributes.js";
+
+/** Resource `service.name` for every dev-server telemetry signal. */
+export const SERVICE_NAME = "sdk-dev-server";
+
+/** OTel instrument scope for parent-emitted metrics (distinct from the child). */
+const SCOPE_NAME = "superblocks.cli.dev-parent";
+
+/** Default fire-and-forget POST budget. Telemetry must never delay the parent. */
+const DEFAULT_TIMEOUT_MS = 1000;
+
+/**
+ * Base URL the dev-server exports OTLP to: `<baseUrl origin>/api`. Callers append
+ * `/v1/traces`, `/v1/metrics`, or `/v1/logs`. Returns undefined when the base URL
+ * is missing or unparseable so callers can skip emission rather than crash.
+ */
+export function otlpBaseUrl(
+  baseUrl: string | URL | undefined,
+): string | undefined {
+  if (!baseUrl) {
+    return undefined;
+  }
+  try {
+    return `${new URL(baseUrl).origin}/api`;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Full OTLP metrics endpoint derived from `SUPERBLOCKS_BASE_URL`. Used by the
+ * lightweight parent's hand-rolled emitter.
+ */
+export function otlpMetricsUrl(
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  const base = otlpBaseUrl(env.SUPERBLOCKS_BASE_URL);
+  return base ? `${base}/v1/metrics` : null;
+}
+
+/**
+ * Derives the `deployment.environment.name` resource attribute from
+ * `SUPERBLOCKS_BASE_URL` so every dev-server signal carries the same environment
+ * tag. Defaults to `"other"` when the host is unknown or unavailable.
+ */
+export function deploymentEnvironment(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const baseUrl = env.SUPERBLOCKS_BASE_URL;
+  if (!baseUrl) {
+    return "other";
+  }
+  let hostname: string;
+  try {
+    hostname = new URL(baseUrl).hostname;
+  } catch {
+    return "other";
+  }
+  return getEnvironmentFromHostname(hostname);
+}
+
+// The direct-to-collector export path was removed: the dev-server always goes
+// through the server proxy. Anyone still setting the old env var gets one
+// visible notice instead of silently-dropped configuration.
+let warnedCollectorUrlIgnored = false;
+export function warnIfCollectorUrlIgnored(
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  if (warnedCollectorUrlIgnored || !env.SUPERBLOCKS_OTEL_COLLECTOR_URL) {
+    return;
+  }
+  warnedCollectorUrlIgnored = true;
+  console.warn(
+    "[Telemetry] SUPERBLOCKS_OTEL_COLLECTOR_URL is set but ignored: the dev-server always exports through the Superblocks server proxy at <SUPERBLOCKS_BASE_URL>/api.",
+  );
+}
+warnIfCollectorUrlIgnored();
+
+function toAttributeArray(
+  attributes: Record<string, string>,
+): Array<{ key: string; value: { stringValue: string } }> {
+  return Object.entries(attributes).map(([key, value]) => ({
+    key,
+    value: { stringValue: value },
+  }));
+}
+
+/**
+ * Builds a minimal OTLP/HTTP `ExportMetricsServiceRequest` body for a single
+ * monotonic DELTA counter increment (value 1). Timestamps are nanosecond
+ * decimal strings built with BigInt so JS number precision can't corrupt them;
+ * `startTimeUnixNano <= timeUnixNano` is required by the protocol.
+ */
+export function buildDeltaCounterPayload(opts: {
+  name: string;
+  description: string;
+  attributes: Record<string, string>;
+  environment: string;
+  serviceName?: string;
+  scopeName?: string;
+  nowMs?: number;
+}): unknown {
+  const nowNano = BigInt(opts.nowMs ?? Date.now()) * 1_000_000n;
+  // A 1ms window keeps start strictly <= time without implying real duration.
+  const startNano = nowNano - 1_000_000n;
+
+  return {
+    resourceMetrics: [
+      {
+        resource: {
+          attributes: toAttributeArray({
+            "service.name": opts.serviceName ?? SERVICE_NAME,
+            "deployment.environment.name": opts.environment,
+          }),
+        },
+        scopeMetrics: [
+          {
+            scope: { name: opts.scopeName ?? SCOPE_NAME },
+            metrics: [
+              {
+                name: opts.name,
+                description: opts.description,
+                sum: {
+                  aggregationTemporality: 1, // AGGREGATION_TEMPORALITY_DELTA
+                  isMonotonic: true,
+                  dataPoints: [
+                    {
+                      attributes: toAttributeArray(opts.attributes),
+                      startTimeUnixNano: startNano.toString(),
+                      timeUnixNano: nowNano.toString(),
+                      asInt: "1",
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * Fire-and-forget POST of a single counter increment as OTLP/HTTP JSON.
+ *
+ * Never throws and never rejects: any failure (no endpoint, DNS, timeout,
+ * non-2xx) resolves quietly so telemetry cannot break or delay the parent's
+ * supervision loop or shutdown. In production the request socket and timeout are
+ * `unref`'d so a slow collector can't keep the parent alive; tests pass
+ * `unref: false` and `await` to observe the request deterministically.
+ */
+export function emitOtlpCounter(opts: {
+  name: string;
+  description: string;
+  attributes: Record<string, string>;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+  unref?: boolean;
+}): Promise<void> {
+  const env = opts.env ?? process.env;
+  const url = otlpMetricsUrl(env);
+  if (!url) {
+    return Promise.resolve();
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return Promise.resolve();
+  }
+
+  const body = JSON.stringify(
+    buildDeltaCounterPayload({
+      name: opts.name,
+      description: opts.description,
+      attributes: opts.attributes,
+      environment: deploymentEnvironment(env),
+    }),
+  );
+
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const unref = opts.unref ?? true;
+  const transport = parsed.protocol === "https:" ? https : http;
+
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    const done = (): void => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+
+    const req = transport.request(
+      {
+        protocol: parsed.protocol,
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: parsed.pathname + parsed.search,
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(body),
+        },
+      },
+      (res) => {
+        // Drain so the socket can close; the status is irrelevant to the parent.
+        res.on("data", () => {});
+        res.on("end", done);
+        res.on("error", done);
+      },
+    );
+
+    req.on("error", done);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      done();
+    });
+    if (unref) {
+      req.on("socket", (socket) => socket.unref());
+    }
+    req.end(body);
+  });
+}

package/src/telemetry/preload.ts

@@ -0,0 +1,113 @@
+/**
+ * Early telemetry preload for the dev-server child.
+ *
+ * This module has ONE job: start the OpenTelemetry SDK before any instrumented
+ * module (node:http, express, the ai-service) is loaded. OTel auto-instrumentation
+ * patches modules at require time, so if the SDK starts late — as it did when the
+ * only init was `configureTelemetry` at connect time — those modules load
+ * unpatched and the dev-server exports nothing. The child entry (`dev.mts`)
+ * imports this as its very first import so it runs before the SDK barrel.
+ *
+ * It intentionally does NOT init dd-trace/LLMObs. Those spans are created during
+ * generation (after connect) and need the application id that is only known then,
+ * so `configureTelemetry` still owns LLMObs. `configureTelemetry`'s own
+ * `initNodeTelemetry` call becomes a no-op here: `initNodeTelemetry` returns the
+ * already-created instance, so we init once, early.
+ *
+ * Config comes from the environment (available at process start), not the auth
+ * file, so nothing here has to await a network/disk read. The endpoint and
+ * environment tag are resolved by the shared `otlp-config` module, the same one
+ * the lightweight parent uses, so parent and child agree on where telemetry goes.
+ */
+
+import os from "node:os";
+
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+import {
+  getDefaultPolicy,
+  initNodeTelemetry,
+  parseDeploymentType,
+} from "@superblocksteam/telemetry";
+
+import packageJson from "../../package.json" with { type: "json" };
+import {
+  ATTR_SUPERBLOCKS_BASE_URL,
+  ATTR_SUPERBLOCKS_CSB_ID,
+  ATTR_SUPERBLOCKS_IS_CSB,
+  getEnvironmentFromHostname,
+} from "./attributes.js";
+import { getTelemetryIdentity } from "./identity.js";
+import { applyLocalObsEnvVars } from "./local-obs.js";
+import { otlpBaseUrl, SERVICE_NAME } from "./otlp-config.js";
+
+// Apply local-obs env defaults first so deployment type / export policy are set
+// before we read them below (mirrors the module-scope call in index.ts).
+applyLocalObsEnvVars();
+
+const baseUrl = process.env.SUPERBLOCKS_BASE_URL;
+const otlpUrl = otlpBaseUrl(baseUrl);
+
+// Without a base URL we have no proxy to export to; skip early init and let the
+// later configureTelemetry path (which resolves config from the auth file) run.
+// Warn so the fallback is visible: by then http/express are already loaded
+// unpatched, so auto-instrumented traces are missing for this run.
+if (!otlpUrl) {
+  console.warn(
+    "[Telemetry] SUPERBLOCKS_BASE_URL is not set; skipping early OpenTelemetry init. Auto-instrumented HTTP/Express traces will be missing for this run.",
+  );
+} else {
+  const hostname = (() => {
+    try {
+      return baseUrl ? new URL(baseUrl).hostname : "";
+    } catch {
+      return "";
+    }
+  })();
+  const isCsb = !!process.env.SUPERBLOCKS_IS_CSB;
+
+  // A typo'd SUPERBLOCKS_DEPLOYMENT_TYPE must not abort early init; default to
+  // CLOUD like the connect-time path in index.ts does.
+  const deploymentType = (() => {
+    try {
+      return parseDeploymentType(process.env.SUPERBLOCKS_DEPLOYMENT_TYPE);
+    } catch (error) {
+      console.warn(
+        "[Telemetry] Invalid SUPERBLOCKS_DEPLOYMENT_TYPE, defaulting to CLOUD:",
+        error,
+      );
+      return DeploymentTypeEnum.CLOUD;
+    }
+  })();
+
+  try {
+    initNodeTelemetry(
+      {
+        serviceName: SERVICE_NAME,
+        serviceVersion: packageJson.version,
+        environment: getEnvironmentFromHostname(hostname),
+        otlpUrl,
+        resourceAttributes: {
+          [ATTR_SUPERBLOCKS_BASE_URL]: hostname,
+          [ATTR_SUPERBLOCKS_IS_CSB]: String(isCsb),
+          ...(isCsb && { [ATTR_SUPERBLOCKS_CSB_ID]: os.hostname() }),
+        },
+        instrumentations: [
+          new HttpInstrumentation(),
+          new ExpressInstrumentation(),
+        ],
+        logsEnabled: true,
+        // Identity (application/user/org) is only known at connect;
+        // configureTelemetry fills it in and every span and exported log
+        // record picks it up here.
+        dynamicAttributes: getTelemetryIdentity,
+      },
+      getDefaultPolicy(deploymentType),
+    );
+  } catch (error) {
+    // Never let telemetry init crash the dev-server boot.
+    console.error("[Telemetry] Early preload failed to initialize:", error);
+  }
+}

package/src/telemetry/util.ts

@@ -1,48 +1,22 @@
 import { getLocalTokenWithUrl } from "@superblocksteam/util";
 
-export const SERVICE_NAME = "sdk-dev-server";
+import { otlpBaseUrl, SERVICE_NAME } from "./otlp-config.js";
 
-/**
- * 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:4318),
- * 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";
-}
+// Re-exported so existing importers of `./util.js` keep resolving SERVICE_NAME
+// from the single source of truth in otlp-config.
+export { SERVICE_NAME };
 
 export async function getConfiguration() {
   try {
     const tokenWithUrl = await getLocalTokenWithUrl();
     const superblocksBaseUrl = new URL(tokenWithUrl.superblocksBaseUrl);
-    const otlpBaseUrl = getOtlpBaseUrl(superblocksBaseUrl);
+    const otlpBase = otlpBaseUrl(superblocksBaseUrl);
     const superblocksHostname = superblocksBaseUrl.hostname;
-    let token = "";
-    if ("token" in tokenWithUrl) {
-      token = tokenWithUrl.token.substring(0, 8);
-    }
     return {
       superblocksBaseUrl,
-      otlpBaseUrl,
+      otlpBaseUrl: otlpBase,
       superblocksHostname,
       serviceName: SERVICE_NAME,
-      token,
     };
   } catch (e) {
     console.error(