@glasstrace/sdk 1.3.3 → 1.3.4

package/README.md

@@ -163,6 +163,94 @@ GLASSTRACE_SUPPRESS_ACTION_NUDGE=1
 The nudge never fires in production (detected via `NODE_ENV` or
 `VERCEL_ENV`) unless `GLASSTRACE_FORCE_ENABLE=true` is also set.
 
+## Production deployment under Next 16
+
+Next 16 (`next build && next start`) registers an OpenTelemetry
+TracerProvider before user code runs. When `registerGlasstrace()` then
+detects that provider, the SDK attempts to attach its span processor to
+the existing pipeline. On most providers this auto-attach succeeds and
+no further action is required; on a small number of provider shapes —
+including Next 16's production-runtime provider in some versions — the
+provider exposes no injection point and auto-attach returns
+unsuccessfully. In that case spans flow through the existing pipeline
+without reaching the Glasstrace exporter, so no traces appear in MCP
+queries or the dashboard.
+
+The SDK signals this case in three ways:
+
+1. **Log line.** The SDK logs a guidance message at `warn` level in
+   development and `error` level under `NODE_ENV=production`:
+
+   ```text
+   [glasstrace] An existing OTel TracerProvider is registered but
+   Glasstrace could not auto-attach its span processor.
+   Add Glasstrace to your provider configuration:
+   ...
+   ```
+
+2. **Programmatic signal.** `getStatus().tracing === "not-configured"`
+   after `registerGlasstrace()` has resolved indicates spans are not
+   reaching the Glasstrace exporter. Poll this from a health endpoint
+   or a startup readiness check:
+
+   ```ts
+   import { getStatus } from "@glasstrace/sdk";
+
+   const { tracing } = getStatus();
+   if (tracing === "not-configured") {
+     // Spans are not being exported. Apply the manual workaround below.
+   }
+   ```
+
+3. **CLI bridge.** `.glasstrace/runtime-state.json` carries a
+   structured `lastError` record that downstream tooling (custom
+   dashboards, CI assertions, the `npx @glasstrace/sdk status`
+   command in future releases) can surface verbatim:
+
+   ```json
+   {
+     "otel": { "state": "COEXISTENCE_FAILED", "scenario": "C/F" },
+     "lastError": {
+       "category": "auto-attach-returned-null",
+       "message": "tryAutoAttachGlasstraceProcessor returned null — ...",
+       "timestamp": "2026-05-04T12:34:56.789Z",
+       "providerClass": "BasicTracerProvider"
+     }
+   }
+   ```
+
+   The `providerClass` field is the constructor name of the existing
+   provider's delegate. URLs, headers, and credentials are never
+   captured.
+
+### Manual workaround
+
+When auto-attach cannot succeed, register Glasstrace's span processor
+on the provider you already own:
+
+```ts
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import { createGlasstraceSpanProcessor } from "@glasstrace/sdk";
+
+const provider = new BasicTracerProvider({
+  spanProcessors: [
+    // ... your existing processors,
+    createGlasstraceSpanProcessor(),
+  ],
+});
+```
+
+`createGlasstraceSpanProcessor()` produces a processor with the same
+branded exporter the auto-attach path uses, so duplicate
+`registerGlasstrace()` calls remain idempotent. `registerGlasstrace()`
+is still required when wiring the processor manually — it handles the
+init handshake, anonymous-key resolution, session management, and
+discovery endpoint, none of which are owned by the span processor.
+
+A future SDK release may extend the auto-attach detection to recognize
+additional Next 16 provider shapes; until that ships, the manual path
+above is the production-supported integration.
+
 ## Capturing error response bodies
 
 When debugging a 4xx or 5xx, the response body is often the most useful

package/dist/{chunk-XNKG4WNQ.js → chunk-XFNK4YEW.js}

@@ -3763,11 +3763,27 @@ async function runCoexistencePath(existingProvider, config) {
   setOtelState(OtelState.COEXISTENCE_FAILED);
   emitLifecycleEvent("otel:configured", { state: OtelState.COEXISTENCE_FAILED, scenario: "C/F" });
   emitLifecycleEvent("otel:injection_failed", { reason: "provider internals inaccessible" });
+  emitLifecycleEvent("otel:failed", {
+    category: "auto-attach-returned-null",
+    message: "tryAutoAttachGlasstraceProcessor returned null \u2014 the existing OTel TracerProvider exposed no injection point. Spans are not reaching the Glasstrace exporter. Apply the manual createGlasstraceSpanProcessor() workaround documented in the SDK README.",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    providerClass: readProviderClass(existingProvider)
+  });
   const coreState = getCoreState();
   if (coreState === CoreState.ACTIVE || coreState === CoreState.KEY_RESOLVED) {
     setCoreState(CoreState.ACTIVE_DEGRADED);
   }
 }
+function readProviderClass(tracerProvider) {
+  try {
+    const proxy = tracerProvider;
+    const delegate = typeof proxy.getDelegate === "function" ? proxy.getDelegate() : tracerProvider;
+    const name = delegate?.constructor?.name;
+    return typeof name === "string" && name.length > 0 ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function runRegistrationPath(config, sessionManager) {
   const exporterUrl = `${config.endpoint}/v1/traces`;
   const createOtlpExporter = (url, headers) => new OTLPTraceExporter({ url, headers });
@@ -4152,6 +4168,7 @@ import { join } from "node:path";
 var _projectRoot = null;
 var _sdkVersion = "unknown";
 var _lastScenario;
+var _lastError;
 var _debounceTimer = null;
 var _started = false;
 function startRuntimeStateWriter(options) {
@@ -4174,6 +4191,10 @@ function startRuntimeStateWriter(options) {
     _lastScenario = scenario;
     debouncedWrite();
   });
+  onLifecycleEvent("otel:failed", (payload) => {
+    _lastError = { ...payload };
+    debouncedWrite();
+  });
   onLifecycleEvent("auth:key_resolved", () => debouncedWrite());
   onLifecycleEvent("auth:claim_started", () => debouncedWrite());
   onLifecycleEvent("auth:claim_completed", () => debouncedWrite());
@@ -4201,6 +4222,9 @@ function writeStateNow() {
       auth: { state: state.auth },
       otel: { state: state.otel, scenario: _lastScenario }
     };
+    if (_lastError) {
+      runtimeState.lastError = _lastError;
+    }
     const dir = join(_projectRoot, ".glasstrace");
     const filePath = join(dir, "runtime-state.json");
     mkdirSync(dir, { recursive: true, mode: 448 });
@@ -4245,7 +4269,7 @@ function registerGlasstrace(options) {
     setCoreState(CoreState.REGISTERING);
     startRuntimeStateWriter({
       projectRoot: process.cwd(),
-      sdkVersion: "1.3.3"
+      sdkVersion: "1.3.4"
     });
     const config = resolveConfig(options);
     if (config.verbose) {
@@ -4411,8 +4435,8 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   if (config.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("1.3.3");
-  const initResult = await performInit(config, anonKeyForInit, "1.3.3", healthReport);
+  const healthReport = collectHealthReport("1.3.4");
+  const initResult = await performInit(config, anonKeyForInit, "1.3.4", healthReport);
   if (generation !== registrationGeneration) return;
   const currentState = getCoreState();
   if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
@@ -4435,7 +4459,7 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config, anonKeyForInit, "1.3.3", generation, (newApiKey, accountId) => {
+    startHeartbeat(config, anonKeyForInit, "1.3.4", generation, (newApiKey, accountId) => {
       setAuthState(AuthState.CLAIMING);
       emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);
@@ -4572,9 +4596,11 @@ This message will not appear once Glasstrace is added to your provider config.`
 }
 function emitGuidanceMessage() {
   const isSentry = detectSentry();
+  const isProduction = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  const level = isProduction ? "error" : "warn";
   if (isSentry) {
     sdkLog(
-      "warn",
+      level,
       `[glasstrace] An existing OTel TracerProvider is registered but Glasstrace could not auto-attach its span processor.
 Add Glasstrace to your Sentry config:
 
@@ -4587,7 +4613,7 @@ Add Glasstrace to your Sentry config:
     );
   } else {
     sdkLog(
-      "warn",
+      level,
       `[glasstrace] An existing OTel TracerProvider is registered but Glasstrace could not auto-attach its span processor.
 Add Glasstrace to your provider configuration:
 
@@ -4833,4 +4859,4 @@ export {
   withGlasstraceConfig,
   captureError
 };
-//# sourceMappingURL=chunk-XNKG4WNQ.js.map
+//# sourceMappingURL=chunk-XFNK4YEW.js.map