@glasstrace/sdk 0.13.5 → 0.14.0

package/dist/index.cjs

@@ -14601,7 +14601,8 @@ var init_dist = __esm({
       envVarValues: external_exports.boolean(),
       fullConsoleOutput: external_exports.boolean(),
       importGraph: external_exports.boolean(),
-      consoleErrors: external_exports.boolean().optional().default(false)
+      consoleErrors: external_exports.boolean().optional().default(false),
+      errorResponseBodies: external_exports.boolean().optional().default(false)
     });
     SdkCachedConfigSchema = external_exports.object({
       response: external_exports.record(external_exports.string(), external_exports.unknown()),
@@ -14732,6 +14733,8 @@ var init_dist = __esm({
       SOURCE_FILE: "glasstrace.source.file",
       SOURCE_LINE: "glasstrace.source.line",
       SOURCE_MAPPED: "glasstrace.source.mapped",
+      TRPC_PROCEDURE: "glasstrace.trpc.procedure",
+      ERROR_RESPONSE_BODY: "glasstrace.error.response_body",
       // Client-side attributes
       PLATFORM: "glasstrace.platform",
       GESTURE_TYPE: "glasstrace.gesture.type",
@@ -14746,7 +14749,8 @@ var init_dist = __esm({
       envVarValues: false,
       fullConsoleOutput: false,
       importGraph: false,
-      consoleErrors: false
+      consoleErrors: false,
+      errorResponseBodies: false
     };
   }
 });
@@ -16614,7 +16618,6 @@ async function uploadSourceMaps(apiKey, endpoint, buildHash, maps) {
     }
   }
   const body = {
-    apiKey,
     buildHash,
     files
   };
@@ -16836,6 +16839,7 @@ __export(src_exports, {
   collectSourceMaps: () => collectSourceMaps,
   computeBuildHash: () => computeBuildHash,
   createDiscoveryHandler: () => createDiscoveryHandler,
+  createGlasstraceSpanProcessor: () => createGlasstraceSpanProcessor,
   deriveSessionId: () => deriveSessionId,
   discoverSourceMapFiles: () => discoverSourceMapFiles,
   discoverTestFiles: () => discoverTestFiles,
@@ -16846,8 +16850,10 @@ __export(src_exports, {
   getLinkedAccountId: () => getLinkedAccountId,
   getOrCreateAnonKey: () => getOrCreateAnonKey,
   getOrigin: () => getOrigin,
+  getStatus: () => getStatus,
   isAnonymousMode: () => isAnonymousMode,
   isProductionDisabled: () => isProductionDisabled,
+  isReady: () => isReady,
   loadCachedConfig: () => loadCachedConfig,
   performInit: () => performInit,
   readAnonKey: () => readAnonKey,
@@ -16859,6 +16865,7 @@ __export(src_exports, {
   uploadSourceMaps: () => uploadSourceMaps,
   uploadSourceMapsAuto: () => uploadSourceMapsAuto,
   uploadSourceMapsPresigned: () => uploadSourceMapsPresigned,
+  waitForReady: () => waitForReady,
   withGlasstraceConfig: () => withGlasstraceConfig
 });
 module.exports = __toCommonJS(src_exports);
@@ -17229,7 +17236,6 @@ async function sendInitRequest(config2, anonKey, sdkVersion, importGraph, health
     throw new Error("No API key available for init request");
   }
   const payload = {
-    apiKey: effectiveKey,
     sdkVersion
   };
   if (config2.apiKey && anonKey) {
@@ -17466,7 +17472,7 @@ init_cjs_shims();
 var GlasstraceSpanProcessor = class {
   wrappedProcessor;
   /* eslint-disable @typescript-eslint/no-unused-vars -- backward compat signature */
-  constructor(wrappedProcessor, _sessionManager, _apiKey, _getConfig, _environment) {
+  constructor(wrappedProcessor, _sessionManager2, _apiKey, _getConfig, _environment) {
     this.wrappedProcessor = wrappedProcessor;
   }
   onStart(span, parentContext) {
@@ -17498,6 +17504,7 @@ var GlasstraceExporter = class {
   environment;
   endpointUrl;
   createDelegateFn;
+  verbose;
   delegate = null;
   delegateKey = null;
   pendingBatches = [];
@@ -17510,6 +17517,8 @@ var GlasstraceExporter = class {
     this.environment = options.environment;
     this.endpointUrl = options.endpointUrl;
     this.createDelegateFn = options.createDelegate;
+    this.verbose = options.verbose ?? false;
+    this[/* @__PURE__ */ Symbol.for("glasstrace.exporter")] = true;
   }
   export(spans, resultCallback) {
     const currentKey = this.getApiKey();
@@ -17607,6 +17616,22 @@ var GlasstraceExporter = class {
       if (route) {
         extra[ATTR.ROUTE] = route;
       }
+      const rawUrl = attrs["http.url"] ?? attrs["url.full"] ?? attrs["http.target"];
+      const trpcUrl = typeof rawUrl === "string" ? rawUrl : void 0;
+      if (trpcUrl) {
+        const trpcMatch = trpcUrl.match(/\/api\/trpc\/([^/?#]+)/);
+        if (trpcMatch) {
+          let procedure;
+          try {
+            procedure = decodeURIComponent(trpcMatch[1]);
+          } catch {
+            procedure = trpcMatch[1];
+          }
+          if (procedure) {
+            extra[ATTR.TRPC_PROCEDURE] = procedure;
+          }
+        }
+      }
       const method = attrs["http.method"] ?? attrs["http.request.method"];
       if (method) {
         extra[ATTR.HTTP_METHOD] = method;
@@ -17615,7 +17640,17 @@ var GlasstraceExporter = class {
       if (statusCode !== void 0) {
         extra[ATTR.HTTP_STATUS_CODE] = statusCode;
       }
-      if (method && span.status?.code === SpanStatusCode.ERROR) {
+      const isErrorByStatus = span.status?.code === SpanStatusCode.ERROR;
+      const isErrorByEvent = hasExceptionEvent(span);
+      const isErrorByAttrs = typeof attrs["exception.type"] === "string" || typeof attrs["exception.message"] === "string";
+      const statusNotExplicitlyOK = span.status?.code !== SpanStatusCode.OK;
+      if (this.verbose && method) {
+        sdkLog(
+          "info",
+          `[glasstrace] enrichSpan "${name}": status.code=${span.status?.code}, http.status_code=${statusCode}, isErrorByStatus=${isErrorByStatus}, isErrorByEvent=${isErrorByEvent}, isErrorByAttrs=${isErrorByAttrs}`
+        );
+      }
+      if (method && statusNotExplicitlyOK && (isErrorByStatus || isErrorByEvent || isErrorByAttrs)) {
         if (statusCode === void 0 || statusCode === 0 || statusCode === 200) {
           const httpErrorType = attrs["error.type"];
           if (typeof httpErrorType === "string") {
@@ -17628,6 +17663,12 @@ var GlasstraceExporter = class {
           } else {
             extra[ATTR.HTTP_STATUS_CODE] = 500;
           }
+          if (this.verbose) {
+            sdkLog(
+              "info",
+              `[glasstrace] enrichSpan "${name}": inferred status_code=${extra[ATTR.HTTP_STATUS_CODE]} (was ${statusCode}), error.type=${attrs["error.type"]}`
+            );
+          }
         }
       }
       if (span.startTime && span.endTime) {
@@ -17638,19 +17679,39 @@ var GlasstraceExporter = class {
           extra[ATTR.HTTP_DURATION_MS] = durationMs;
         }
       }
+      const eventDetails = statusNotExplicitlyOK ? getExceptionEventDetails(span) : { type: void 0, message: void 0 };
       const errorMessage = attrs["exception.message"];
       if (typeof errorMessage === "string") {
         extra[ATTR.ERROR_MESSAGE] = errorMessage;
+      } else if (eventDetails.message) {
+        extra[ATTR.ERROR_MESSAGE] = eventDetails.message;
       }
       const errorType = attrs["exception.type"];
       if (typeof errorType === "string") {
         extra[ATTR.ERROR_CODE] = errorType;
         extra[ATTR.ERROR_CATEGORY] = deriveErrorCategory(errorType);
+      } else if (eventDetails.type) {
+        extra[ATTR.ERROR_CODE] = eventDetails.type;
+        extra[ATTR.ERROR_CATEGORY] = deriveErrorCategory(eventDetails.type);
+      }
+      if (this.verbose && (extra[ATTR.ERROR_MESSAGE] || extra[ATTR.ERROR_CODE])) {
+        const msgSource = typeof errorMessage === "string" ? "attrs" : eventDetails.message ? "event" : "none";
+        const typeSource = typeof errorType === "string" ? "attrs" : eventDetails.type ? "event" : "none";
+        sdkLog(
+          "info",
+          `[glasstrace] enrichSpan "${name}": error.message source=${msgSource}, error.code source=${typeSource}`
+        );
       }
       const errorField = attrs["error.field"];
       if (typeof errorField === "string") {
         extra[ATTR.ERROR_FIELD] = errorField;
       }
+      if (this.getConfig().errorResponseBodies) {
+        const responseBody = attrs["glasstrace.internal.response_body"];
+        if (typeof responseBody === "string") {
+          extra[ATTR.ERROR_RESPONSE_BODY] = responseBody.slice(0, 500);
+        }
+      }
       const spanAny = span;
       const instrumentationName = spanAny.instrumentationScope?.name ?? spanAny.instrumentationLibrary?.name ?? "";
       const ormProvider = deriveOrmProvider(instrumentationName);
@@ -17768,6 +17829,21 @@ function createEnrichedSpan(span, extra) {
     }
   });
 }
+function hasExceptionEvent(span) {
+  return span.events?.some((e) => e.name === "exception") ?? false;
+}
+function getExceptionEventDetails(span) {
+  const event = span.events?.find((e) => e.name === "exception");
+  if (!event?.attributes) {
+    return { type: void 0, message: void 0 };
+  }
+  const type = event.attributes["exception.type"];
+  const message = event.attributes["exception.message"];
+  return {
+    type: typeof type === "string" ? type : void 0,
+    message: typeof message === "string" ? message : void 0
+  };
+}
 function deriveOrmProvider(instrumentationName) {
   const lower = instrumentationName.toLowerCase();
   if (lower.includes("prisma")) {
@@ -20637,9 +20713,461 @@ var BasicTracerProvider = class {
 // src/otel-config.ts
 init_esm();
 init_console_capture();
+
+// src/lifecycle.ts
+init_cjs_shims();
+var import_node_events = require("events");
+var CoreState = {
+  IDLE: "IDLE",
+  REGISTERING: "REGISTERING",
+  KEY_PENDING: "KEY_PENDING",
+  KEY_RESOLVED: "KEY_RESOLVED",
+  ACTIVE: "ACTIVE",
+  ACTIVE_DEGRADED: "ACTIVE_DEGRADED",
+  SHUTTING_DOWN: "SHUTTING_DOWN",
+  SHUTDOWN: "SHUTDOWN",
+  PRODUCTION_DISABLED: "PRODUCTION_DISABLED",
+  REGISTRATION_FAILED: "REGISTRATION_FAILED"
+};
+var AuthState = {
+  ANONYMOUS: "ANONYMOUS",
+  AUTHENTICATED: "AUTHENTICATED",
+  CLAIMING: "CLAIMING",
+  CLAIMED: "CLAIMED"
+};
+var OtelState = {
+  UNCONFIGURED: "UNCONFIGURED",
+  CONFIGURING: "CONFIGURING",
+  OWNS_PROVIDER: "OWNS_PROVIDER",
+  AUTO_ATTACHED: "AUTO_ATTACHED",
+  PROCESSOR_PRESENT: "PROCESSOR_PRESENT",
+  COEXISTENCE_FAILED: "COEXISTENCE_FAILED"
+};
+var VALID_CORE_TRANSITIONS = {
+  [CoreState.IDLE]: [CoreState.REGISTERING, CoreState.REGISTRATION_FAILED, CoreState.SHUTTING_DOWN],
+  [CoreState.REGISTERING]: [
+    CoreState.KEY_PENDING,
+    CoreState.PRODUCTION_DISABLED,
+    CoreState.REGISTRATION_FAILED,
+    CoreState.SHUTTING_DOWN
+  ],
+  [CoreState.KEY_PENDING]: [
+    CoreState.KEY_RESOLVED,
+    CoreState.REGISTRATION_FAILED,
+    CoreState.SHUTTING_DOWN
+  ],
+  [CoreState.KEY_RESOLVED]: [
+    CoreState.ACTIVE,
+    CoreState.ACTIVE_DEGRADED,
+    CoreState.SHUTTING_DOWN
+  ],
+  [CoreState.ACTIVE]: [
+    CoreState.ACTIVE_DEGRADED,
+    CoreState.SHUTTING_DOWN
+  ],
+  [CoreState.ACTIVE_DEGRADED]: [
+    CoreState.ACTIVE,
+    CoreState.SHUTTING_DOWN
+  ],
+  [CoreState.SHUTTING_DOWN]: [CoreState.SHUTDOWN],
+  [CoreState.SHUTDOWN]: [],
+  [CoreState.PRODUCTION_DISABLED]: [],
+  [CoreState.REGISTRATION_FAILED]: []
+};
+var VALID_AUTH_TRANSITIONS = {
+  [AuthState.ANONYMOUS]: [AuthState.CLAIMING],
+  [AuthState.AUTHENTICATED]: [AuthState.CLAIMING],
+  [AuthState.CLAIMING]: [AuthState.CLAIMED],
+  [AuthState.CLAIMED]: [AuthState.CLAIMING]
+};
+var VALID_OTEL_TRANSITIONS = {
+  [OtelState.UNCONFIGURED]: [OtelState.CONFIGURING],
+  [OtelState.CONFIGURING]: [
+    OtelState.OWNS_PROVIDER,
+    OtelState.AUTO_ATTACHED,
+    OtelState.PROCESSOR_PRESENT,
+    OtelState.COEXISTENCE_FAILED
+  ],
+  [OtelState.OWNS_PROVIDER]: [],
+  [OtelState.AUTO_ATTACHED]: [],
+  [OtelState.PROCESSOR_PRESENT]: [],
+  [OtelState.COEXISTENCE_FAILED]: []
+};
+var _coreState = CoreState.IDLE;
+var _authState = AuthState.ANONYMOUS;
+var _otelState = OtelState.UNCONFIGURED;
+var _emitter = new import_node_events.EventEmitter();
+var _logger = null;
+var _initialized = false;
+var _initWarned = false;
+var _coreReadyEmitted = false;
+var _authInitialized = false;
+var _emitting = false;
+function initLifecycle(options) {
+  if (_initialized) {
+    options.logger("warn", "[glasstrace] initLifecycle() called twice \u2014 ignored.");
+    return;
+  }
+  _logger = options.logger;
+  _initialized = true;
+}
+function warnIfNotInitialized() {
+  if (!_initialized && !_initWarned) {
+    _initWarned = true;
+    console.warn(
+      "[glasstrace] Lifecycle state changed before initLifecycle() was called. Logger not available \u2014 errors will be silent."
+    );
+  }
+}
+function setCoreState(to) {
+  warnIfNotInitialized();
+  const from = _coreState;
+  if (from === to) return;
+  const valid = VALID_CORE_TRANSITIONS[from];
+  if (!valid.includes(to)) {
+    _logger?.(
+      "warn",
+      `[glasstrace] Invalid core state transition: ${from} \u2192 ${to}. Ignored.`
+    );
+    return;
+  }
+  _coreState = to;
+  if (_emitting) return;
+  _emitting = true;
+  try {
+    emitSafe("core:state_changed", { from, to });
+    const current = _coreState;
+    if (!_coreReadyEmitted && (current === CoreState.ACTIVE || current === CoreState.ACTIVE_DEGRADED)) {
+      _coreReadyEmitted = true;
+      emitSafe("core:ready", {});
+    }
+    if (current === CoreState.SHUTTING_DOWN) {
+      emitSafe("core:shutdown_started", {});
+    }
+    if (current === CoreState.SHUTDOWN) {
+      emitSafe("core:shutdown_completed", {});
+    }
+  } finally {
+    _emitting = false;
+  }
+}
+function initAuthState(state) {
+  if (_authInitialized) {
+    _logger?.(
+      "warn",
+      "[glasstrace] initAuthState() called after auth state already initialized. Ignored."
+    );
+    return;
+  }
+  _authInitialized = true;
+  _authState = state;
+}
+function setAuthState(to) {
+  warnIfNotInitialized();
+  const from = _authState;
+  if (from === to) return;
+  const valid = VALID_AUTH_TRANSITIONS[from];
+  if (!valid.includes(to)) {
+    _logger?.(
+      "warn",
+      `[glasstrace] Invalid auth state transition: ${from} \u2192 ${to}. Ignored.`
+    );
+    return;
+  }
+  _authState = to;
+}
+function setOtelState(to) {
+  warnIfNotInitialized();
+  const from = _otelState;
+  if (from === to) return;
+  const valid = VALID_OTEL_TRANSITIONS[from];
+  if (!valid.includes(to)) {
+    _logger?.(
+      "warn",
+      `[glasstrace] Invalid OTel state transition: ${from} \u2192 ${to}. Ignored.`
+    );
+    return;
+  }
+  _otelState = to;
+}
+function getCoreState() {
+  return _coreState;
+}
+function getSdkState() {
+  return {
+    core: _coreState,
+    auth: _authState,
+    otel: _otelState
+  };
+}
+function onLifecycleEvent(event, listener) {
+  _emitter.on(event, listener);
+}
+function emitLifecycleEvent(event, payload) {
+  emitSafe(event, payload);
+}
+function offLifecycleEvent(event, listener) {
+  _emitter.off(event, listener);
+}
+function emitSafe(event, payload) {
+  const listeners = _emitter.listeners(event);
+  for (const listener of listeners) {
+    try {
+      const result = listener(payload);
+      if (result && typeof result.catch === "function") {
+        result.catch((err) => {
+          _logger?.(
+            "error",
+            `[glasstrace] Async error in lifecycle event listener for "${event}": ${err instanceof Error ? err.message : String(err)}`
+          );
+        });
+      }
+    } catch (err) {
+      _logger?.(
+        "error",
+        `[glasstrace] Error in lifecycle event listener for "${event}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+}
+function isReady() {
+  return _coreState === CoreState.ACTIVE || _coreState === CoreState.ACTIVE_DEGRADED;
+}
+function waitForReady(timeoutMs = 3e4) {
+  if (isReady()) {
+    return Promise.resolve();
+  }
+  if (_coreState === CoreState.PRODUCTION_DISABLED || _coreState === CoreState.REGISTRATION_FAILED || _coreState === CoreState.SHUTTING_DOWN || _coreState === CoreState.SHUTDOWN) {
+    return Promise.reject(new Error(`SDK is in terminal state: ${_coreState}`));
+  }
+  return new Promise((resolve3, reject) => {
+    let settled = false;
+    const listener = ({ to }) => {
+      if (settled) return;
+      if (to === CoreState.ACTIVE || to === CoreState.ACTIVE_DEGRADED) {
+        settled = true;
+        offLifecycleEvent("core:state_changed", listener);
+        resolve3();
+      } else if (to === CoreState.PRODUCTION_DISABLED || to === CoreState.REGISTRATION_FAILED || to === CoreState.SHUTTING_DOWN || to === CoreState.SHUTDOWN) {
+        settled = true;
+        offLifecycleEvent("core:state_changed", listener);
+        reject(new Error(`SDK reached terminal state: ${to}`));
+      }
+    };
+    onLifecycleEvent("core:state_changed", listener);
+    if (timeoutMs > 0) {
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        offLifecycleEvent("core:state_changed", listener);
+        reject(new Error(`waitForReady timed out after ${timeoutMs}ms (state: ${_coreState})`));
+      }, timeoutMs);
+      if (typeof timer === "object" && "unref" in timer) {
+        timer.unref();
+      }
+    }
+  });
+}
+function getStatus() {
+  let mode;
+  if (_coreState === CoreState.PRODUCTION_DISABLED) {
+    mode = "disabled";
+  } else if (_authState === AuthState.CLAIMING || _authState === AuthState.CLAIMED) {
+    mode = "claiming";
+  } else if (_authState === AuthState.AUTHENTICATED) {
+    mode = "authenticated";
+  } else {
+    mode = "anonymous";
+  }
+  let tracing;
+  if (_otelState === OtelState.COEXISTENCE_FAILED || _otelState === OtelState.UNCONFIGURED || _otelState === OtelState.CONFIGURING) {
+    tracing = "not-configured";
+  } else if (_coreState === CoreState.ACTIVE_DEGRADED) {
+    tracing = "degraded";
+  } else if (_otelState === OtelState.AUTO_ATTACHED || _otelState === OtelState.PROCESSOR_PRESENT) {
+    tracing = "coexistence";
+  } else {
+    tracing = "active";
+  }
+  return {
+    ready: isReady(),
+    mode,
+    tracing
+  };
+}
+var _shutdownHooks = [];
+var _signalHandlersRegistered = false;
+var _signalHandler = null;
+var _beforeExitRegistered = false;
+var _beforeExitHandler = null;
+var _shutdownExecuted = false;
+function registerShutdownHook(hook) {
+  _shutdownHooks.push(hook);
+  _shutdownHooks.sort((a, b) => a.priority - b.priority);
+}
+async function executeShutdown(timeoutMs = 5e3) {
+  if (_shutdownExecuted) return;
+  _shutdownExecuted = true;
+  setCoreState(CoreState.SHUTTING_DOWN);
+  for (const hook of _shutdownHooks) {
+    try {
+      const hookPromise = hook.fn();
+      hookPromise.catch(() => {
+      });
+      await Promise.race([
+        hookPromise,
+        new Promise((_, reject) => {
+          const timer = setTimeout(() => reject(new Error(`Shutdown hook "${hook.name}" timed out`)), timeoutMs);
+          if (typeof timer === "object" && "unref" in timer) {
+            timer.unref();
+          }
+        })
+      ]);
+    } catch (err) {
+      _logger?.(
+        "warn",
+        `[glasstrace] Shutdown hook "${hook.name}" failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  setCoreState(CoreState.SHUTDOWN);
+}
+function registerSignalHandlers() {
+  if (_signalHandlersRegistered) return;
+  if (typeof process === "undefined" || typeof process.once !== "function") return;
+  _signalHandlersRegistered = true;
+  const handler = (signal) => {
+    void executeShutdown().finally(() => {
+      if (_signalHandler) {
+        process.removeListener("SIGTERM", _signalHandler);
+        process.removeListener("SIGINT", _signalHandler);
+      }
+      process.kill(process.pid, signal);
+    });
+  };
+  _signalHandler = handler;
+  process.once("SIGTERM", handler);
+  process.once("SIGINT", handler);
+}
+function registerBeforeExitTrigger() {
+  if (_beforeExitRegistered) return;
+  if (typeof process === "undefined" || typeof process.once !== "function") return;
+  _beforeExitRegistered = true;
+  const handler = () => {
+    void executeShutdown();
+  };
+  _beforeExitHandler = handler;
+  process.once("beforeExit", handler);
+}
+
+// src/coexistence.ts
+init_cjs_shims();
+init_env_detection();
+init_console_capture();
+function createGlasstraceSpanProcessor(options) {
+  const config2 = resolveConfig(options);
+  const exporterUrl = `${config2.endpoint}/v1/traces`;
+  const createOtlpExporter = (url2, headers) => new OTLPTraceExporter({ url: url2, headers });
+  const exporter = new GlasstraceExporter({
+    getApiKey: getResolvedApiKey,
+    sessionManager: getSessionManager(),
+    getConfig: () => getActiveConfig(),
+    environment: config2.environment,
+    endpointUrl: exporterUrl,
+    createDelegate: createOtlpExporter
+  });
+  registerExporterForKeyNotification(exporter);
+  return new BatchSpanProcessor(exporter, {
+    scheduledDelayMillis: 1e3
+  });
+}
+function emitNudgeMessage() {
+  const isSentry = detectSentry();
+  if (isSentry) {
+    sdkLog(
+      "info",
+      `[glasstrace] Detected existing OTel provider \u2014 auto-attached Glasstrace span processor.
+For a cleaner setup, add Glasstrace to your Sentry config:
+
+  import { createGlasstraceSpanProcessor } from '@glasstrace/sdk';
+
+  Sentry.init({
+    dsn: '...',
+    openTelemetrySpanProcessors: [createGlasstraceSpanProcessor()],
+  });
+
+This message will not appear once Glasstrace is added to your provider config.`
+    );
+  } else {
+    sdkLog(
+      "info",
+      `[glasstrace] Detected existing OTel provider \u2014 auto-attached Glasstrace span processor.
+For a cleaner setup, add Glasstrace to your provider config:
+
+  import { createGlasstraceSpanProcessor } from '@glasstrace/sdk';
+
+  const provider = new BasicTracerProvider({
+    spanProcessors: [
+      // ... your existing processors,
+      createGlasstraceSpanProcessor(),
+    ],
+  });
+
+This message will not appear once Glasstrace is added to your provider config.`
+    );
+  }
+}
+function emitGuidanceMessage() {
+  const isSentry = detectSentry();
+  if (isSentry) {
+    sdkLog(
+      "warn",
+      `[glasstrace] An existing OTel TracerProvider is registered but Glasstrace could not auto-attach its span processor.
+Add Glasstrace to your Sentry config:
+
+  import { createGlasstraceSpanProcessor } from '@glasstrace/sdk';
+
+  Sentry.init({
+    dsn: '...',
+    openTelemetrySpanProcessors: [createGlasstraceSpanProcessor()],
+  });`
+    );
+  } else {
+    sdkLog(
+      "warn",
+      `[glasstrace] An existing OTel TracerProvider is registered but Glasstrace could not auto-attach its span processor.
+Add Glasstrace to your provider configuration:
+
+  import { createGlasstraceSpanProcessor } from '@glasstrace/sdk';
+
+  const provider = new BasicTracerProvider({
+    spanProcessors: [
+      // ... your existing processors,
+      createGlasstraceSpanProcessor(),
+    ],
+  });`
+    );
+  }
+}
+function detectSentry() {
+  try {
+    require.resolve("@sentry/node");
+    return true;
+  } catch {
+    try {
+      require.resolve("@sentry/nextjs");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// src/otel-config.ts
 var _resolvedApiKey = API_KEY_PENDING;
 var _activeExporter = null;
-var _shutdownHandler = null;
+var _additionalExporters = [];
+var _injectedProcessor = null;
 function setResolvedApiKey(key) {
   _resolvedApiKey = key;
 }
@@ -20648,6 +21176,12 @@ function getResolvedApiKey() {
 }
 function notifyApiKeyResolved() {
   _activeExporter?.notifyKeyResolved();
+  for (const exporter of _additionalExporters) {
+    exporter.notifyKeyResolved();
+  }
+}
+function registerExporterForKeyNotification(exporter) {
+  _additionalExporters.push(exporter);
 }
 async function tryImport(moduleId) {
   try {
@@ -20656,34 +21190,65 @@ async function tryImport(moduleId) {
     return null;
   }
 }
-function registerShutdownHooks(provider) {
-  if (typeof process === "undefined" || typeof process.once !== "function") {
-    return;
-  }
-  if (_shutdownHandler) {
-    process.removeListener("SIGTERM", _shutdownHandler);
-    process.removeListener("SIGINT", _shutdownHandler);
+function tryInjectProcessor(tracerProvider, glasstraceExporter) {
+  try {
+    const proxy = tracerProvider;
+    const delegate = typeof proxy.getDelegate === "function" ? proxy.getDelegate() : tracerProvider;
+    const withAdd = delegate;
+    if (typeof withAdd.addSpanProcessor === "function") {
+      if (typeof withAdd.getActiveSpanProcessor === "function") {
+        const active = withAdd.getActiveSpanProcessor();
+        const brand = /* @__PURE__ */ Symbol.for("glasstrace.exporter");
+        const processors = active?._spanProcessors;
+        if (Array.isArray(processors) && processors.some((p) => {
+          const exp = p._exporter;
+          return exp?.[brand] === true;
+        })) {
+          return "already_present";
+        }
+      }
+      const processor2 = new BatchSpanProcessor(glasstraceExporter, {
+        scheduledDelayMillis: 1e3
+      });
+      withAdd.addSpanProcessor(processor2);
+      _injectedProcessor = processor2;
+      return "v1_public";
+    }
+    const provider = delegate;
+    const multiProcessor = provider._activeSpanProcessor;
+    if (!multiProcessor || !Array.isArray(multiProcessor._spanProcessors)) {
+      return null;
+    }
+    const processor = new BatchSpanProcessor(glasstraceExporter, {
+      scheduledDelayMillis: 1e3
+    });
+    multiProcessor._spanProcessors.push(processor);
+    _injectedProcessor = processor;
+    return "v2_private";
+  } catch {
+    return null;
   }
-  let shutdownCalled = false;
-  const shutdown = (signal) => {
-    if (shutdownCalled) return;
-    shutdownCalled = true;
-    void provider.shutdown().catch((err) => {
-      console.warn(
-        `[glasstrace] Error during OTel shutdown: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }).finally(() => {
-      process.removeListener("SIGTERM", _shutdownHandler);
-      process.removeListener("SIGINT", _shutdownHandler);
-      process.kill(process.pid, signal);
+}
+function isGlasstraceProcessorPresent(tracerProvider) {
+  try {
+    const proxy = tracerProvider;
+    const delegate = typeof proxy.getDelegate === "function" ? proxy.getDelegate() : tracerProvider;
+    const provider = delegate;
+    const processors = provider._activeSpanProcessor?._spanProcessors;
+    if (!Array.isArray(processors)) {
+      return false;
+    }
+    const brand = /* @__PURE__ */ Symbol.for("glasstrace.exporter");
+    return processors.some((p) => {
+      const exporter = p._exporter;
+      return exporter?.[brand] === true;
     });
-  };
-  const handler = (signal) => shutdown(signal);
-  _shutdownHandler = handler;
-  process.once("SIGTERM", handler);
-  process.once("SIGINT", handler);
+  } catch {
+    return false;
+  }
 }
 async function configureOtel(config2, sessionManager) {
+  setOtelState(OtelState.CONFIGURING);
   const exporterUrl = `${config2.endpoint}/v1/traces`;
   const createOtlpExporter = (url2, headers) => new OTLPTraceExporter({ url: url2, headers });
   const glasstraceExporter = new GlasstraceExporter({
@@ -20692,32 +21257,91 @@ async function configureOtel(config2, sessionManager) {
     getConfig: () => getActiveConfig(),
     environment: config2.environment,
     endpointUrl: exporterUrl,
-    createDelegate: createOtlpExporter
+    createDelegate: createOtlpExporter,
+    verbose: config2.verbose
   });
   _activeExporter = glasstraceExporter;
+  await new Promise((resolve3) => {
+    if (typeof setImmediate === "function") {
+      setImmediate(resolve3);
+    } else {
+      setTimeout(resolve3, 0);
+    }
+  });
+  const existingProvider = trace.getTracerProvider();
+  const probeTracer = existingProvider.getTracer("glasstrace-probe");
+  const anotherProviderRegistered = probeTracer.constructor.name !== "ProxyTracer";
+  if (anotherProviderRegistered) {
+    if (isGlasstraceProcessorPresent(existingProvider)) {
+      if (config2.verbose) {
+        sdkLog("info", "[glasstrace] Existing provider detected \u2014 Glasstrace processor already present.");
+      }
+      _activeExporter = null;
+      setOtelState(OtelState.PROCESSOR_PRESENT);
+      emitLifecycleEvent("otel:configured", { state: OtelState.PROCESSOR_PRESENT, scenario: "B-clean" });
+      return;
+    }
+    const injectionMethod = tryInjectProcessor(existingProvider, glasstraceExporter);
+    if (injectionMethod === "already_present") {
+      if (config2.verbose) {
+        sdkLog("info", "[glasstrace] Existing provider detected \u2014 Glasstrace processor already present (v1 check).");
+      }
+      _activeExporter = null;
+      setOtelState(OtelState.PROCESSOR_PRESENT);
+      emitLifecycleEvent("otel:configured", { state: OtelState.PROCESSOR_PRESENT, scenario: "B-clean" });
+      return;
+    }
+    if (injectionMethod) {
+      if (config2.verbose) {
+        sdkLog("info", "[glasstrace] Existing provider detected \u2014 auto-attaching Glasstrace processor.");
+      }
+      registerShutdownHook({
+        name: "coexistence-flush",
+        priority: 5,
+        fn: async () => {
+          if (_injectedProcessor) {
+            await _injectedProcessor.forceFlush();
+          }
+        }
+      });
+      registerBeforeExitTrigger();
+      const scenario = injectionMethod === "v1_public" ? "D1" : "B-auto";
+      setOtelState(OtelState.AUTO_ATTACHED);
+      emitLifecycleEvent("otel:configured", { state: OtelState.AUTO_ATTACHED, scenario });
+      emitLifecycleEvent("otel:injection_succeeded", { method: injectionMethod });
+      emitNudgeMessage();
+      return;
+    }
+    if (config2.verbose) {
+      sdkLog("info", "[glasstrace] Existing provider detected \u2014 could not auto-attach.");
+    }
+    emitGuidanceMessage();
+    _activeExporter = null;
+    setOtelState(OtelState.COEXISTENCE_FAILED);
+    emitLifecycleEvent("otel:configured", { state: OtelState.COEXISTENCE_FAILED, scenario: "C/F" });
+    emitLifecycleEvent("otel:injection_failed", { reason: "provider internals inaccessible" });
+    const coreState = getCoreState();
+    if (coreState === CoreState.ACTIVE || coreState === CoreState.KEY_RESOLVED) {
+      setCoreState(CoreState.ACTIVE_DEGRADED);
+    }
+    return;
+  }
   const vercelOtel = await tryImport("@vercel/otel");
   if (vercelOtel && typeof vercelOtel.registerOTel === "function") {
     const otelConfig = {
       serviceName: "glasstrace-sdk",
       traceExporter: glasstraceExporter
     };
-    const prismaModule = await tryImport("@prisma/instrumentation");
-    if (prismaModule) {
-      const PrismaInstrumentation = prismaModule.PrismaInstrumentation;
+    const prismaModule2 = await tryImport("@prisma/instrumentation");
+    if (prismaModule2) {
+      const PrismaInstrumentation = prismaModule2.PrismaInstrumentation;
       if (PrismaInstrumentation) {
         otelConfig.instrumentations = [new PrismaInstrumentation()];
       }
     }
     vercelOtel.registerOTel(otelConfig);
-    return;
-  }
-  const existingProvider = trace.getTracerProvider();
-  const probeTracer = existingProvider.getTracer("glasstrace-probe");
-  if (probeTracer.constructor.name !== "ProxyTracer") {
-    console.warn(
-      "[glasstrace] An existing OpenTelemetry TracerProvider is already registered. Glasstrace will not overwrite it. To use Glasstrace alongside another tracing tool, add GlasstraceExporter as an additional span processor on your existing provider."
-    );
-    _activeExporter = null;
+    setOtelState(OtelState.OWNS_PROVIDER);
+    emitLifecycleEvent("otel:configured", { state: OtelState.OWNS_PROVIDER, scenario: "E" });
     return;
   }
   if (config2.verbose) {
@@ -20739,7 +21363,29 @@ async function configureOtel(config2, sessionManager) {
     spanProcessors: [processor]
   });
   trace.setGlobalTracerProvider(provider);
-  registerShutdownHooks(provider);
+  registerShutdownHook({
+    name: "otel-provider-shutdown",
+    priority: 0,
+    fn: async () => {
+      await provider.shutdown();
+    }
+  });
+  registerSignalHandlers();
+  registerBeforeExitTrigger();
+  const prismaModule = await tryImport("@prisma/instrumentation");
+  if (prismaModule) {
+    const PrismaInstrumentation = prismaModule.PrismaInstrumentation;
+    if (PrismaInstrumentation) {
+      try {
+        const inst = new PrismaInstrumentation();
+        inst.setTracerProvider(provider);
+        inst.enable();
+      } catch {
+      }
+    }
+  }
+  setOtelState(OtelState.OWNS_PROVIDER);
+  emitLifecycleEvent("otel:configured", { state: OtelState.OWNS_PROVIDER, scenario: "A" });
 }
 
 // src/context-manager.ts
@@ -20790,7 +21436,7 @@ var heartbeatGeneration = 0;
 var backoffAttempts = 0;
 var backoffUntil = 0;
 var tickInProgress = false;
-var _shutdownHandler2 = null;
+var _shutdownHandler = null;
 function startHeartbeat(config2, anonKey, sdkVersion, generation, onClaimTransition) {
   if (heartbeatTimer !== null) return;
   heartbeatGeneration = generation;
@@ -20843,7 +21489,7 @@ async function heartbeatTick(config2, anonKey, sdkVersion, generation, onClaimTr
       backoffUntil = 0;
     }
     if (initResult?.claimResult) {
-      onClaimTransition(initResult.claimResult.newApiKey);
+      onClaimTransition(initResult.claimResult.newApiKey, initResult.claimResult.accountId);
     }
     if (config2.verbose) {
       sdkLog("info", "[glasstrace] Heartbeat completed.");
@@ -20871,39 +21517,125 @@ function registerShutdownHandlers(config2, anonKey, sdkVersion) {
       process.kill(process.pid, signal);
     });
   };
-  _shutdownHandler2 = handler;
-  process.once("SIGTERM", _shutdownHandler2);
-  process.once("SIGINT", _shutdownHandler2);
+  _shutdownHandler = handler;
+  process.once("SIGTERM", _shutdownHandler);
+  process.once("SIGINT", _shutdownHandler);
 }
 function removeShutdownHandlers() {
-  if (_shutdownHandler2 && typeof process !== "undefined") {
-    process.removeListener("SIGTERM", _shutdownHandler2);
-    process.removeListener("SIGINT", _shutdownHandler2);
-    _shutdownHandler2 = null;
+  if (_shutdownHandler && typeof process !== "undefined") {
+    process.removeListener("SIGTERM", _shutdownHandler);
+    process.removeListener("SIGINT", _shutdownHandler);
+    _shutdownHandler = null;
+  }
+}
+
+// src/runtime-state.ts
+init_cjs_shims();
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+init_console_capture();
+var _projectRoot = null;
+var _sdkVersion = "unknown";
+var _lastScenario;
+var _debounceTimer = null;
+var _started = false;
+function startRuntimeStateWriter(options) {
+  if (_started) return;
+  _started = true;
+  _projectRoot = options.projectRoot;
+  _sdkVersion = options.sdkVersion;
+  onLifecycleEvent("core:state_changed", ({ to }) => {
+    if (to === CoreState.SHUTDOWN) {
+      writeStateNow();
+    } else {
+      debouncedWrite();
+    }
+  });
+  onLifecycleEvent("otel:configured", ({ scenario }) => {
+    _lastScenario = scenario;
+    debouncedWrite();
+  });
+  onLifecycleEvent("auth:key_resolved", () => debouncedWrite());
+  onLifecycleEvent("auth:claim_started", () => debouncedWrite());
+  onLifecycleEvent("auth:claim_completed", () => debouncedWrite());
+  writeStateNow();
+}
+function debouncedWrite() {
+  if (_debounceTimer) return;
+  _debounceTimer = setTimeout(() => {
+    _debounceTimer = null;
+    writeStateNow();
+  }, 1e3);
+  if (typeof _debounceTimer === "object" && "unref" in _debounceTimer) {
+    _debounceTimer.unref();
+  }
+}
+function writeStateNow() {
+  if (!_projectRoot) return;
+  try {
+    const state = getSdkState();
+    const runtimeState = {
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      pid: process.pid,
+      sdkVersion: _sdkVersion,
+      core: { state: state.core },
+      auth: { state: state.auth },
+      otel: { state: state.otel, scenario: _lastScenario }
+    };
+    const dir = (0, import_node_path.join)(_projectRoot, ".glasstrace");
+    const filePath = (0, import_node_path.join)(dir, "runtime-state.json");
+    const tmpPath = (0, import_node_path.join)(dir, "runtime-state.json.tmp");
+    (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
+    (0, import_node_fs.writeFileSync)(tmpPath, JSON.stringify(runtimeState, null, 2) + "\n", {
+      mode: 384
+    });
+    (0, import_node_fs.renameSync)(tmpPath, filePath);
+  } catch (err) {
+    sdkLog(
+      "warn",
+      `[glasstrace] Failed to write runtime state: ${err instanceof Error ? err.message : String(err)}`
+    );
   }
 }
 
 // src/register.ts
+function maskKey(key) {
+  if (key.length <= 12) return key.slice(0, 4) + "...";
+  return key.slice(0, 8) + "..." + key.slice(-4);
+}
 var consoleCaptureInstalled = false;
 var discoveryHandler = null;
-var isRegistered = false;
 var registrationGeneration = 0;
+var _sessionManager = null;
+function getSessionManager() {
+  if (!_sessionManager) {
+    _sessionManager = new SessionManager();
+  }
+  return _sessionManager;
+}
 function registerGlasstrace(options) {
   try {
-    if (isRegistered) {
+    if (getCoreState() !== CoreState.IDLE) {
       return;
     }
+    initLifecycle({ logger: sdkLog });
     if (typeof process === "undefined" || typeof process.versions?.node !== "string") {
       console.warn(
         "[glasstrace] SDK requires a Node.js runtime. Edge Runtime, browser, and Deno without Node compat are not supported. Glasstrace is disabled in this environment."
       );
       return;
     }
+    setCoreState(CoreState.REGISTERING);
+    startRuntimeStateWriter({
+      projectRoot: process.cwd(),
+      sdkVersion: "0.14.0"
+    });
     const config2 = resolveConfig(options);
     if (config2.verbose) {
       console.info("[glasstrace] Config resolved.");
     }
     if (isProductionDisabled(config2)) {
+      setCoreState(CoreState.PRODUCTION_DISABLED);
       console.warn(
         "[glasstrace] Disabled in production. Set GLASSTRACE_FORCE_ENABLE=true to override."
       );
@@ -20914,8 +21646,13 @@ function registerGlasstrace(options) {
     }
     const anonymous = isAnonymousMode(config2);
     let effectiveKey = config2.apiKey;
+    initAuthState(anonymous ? AuthState.ANONYMOUS : AuthState.AUTHENTICATED);
     if (effectiveKey) {
       setResolvedApiKey(effectiveKey);
+      emitLifecycleEvent("auth:key_resolved", {
+        key: maskKey(effectiveKey),
+        mode: anonymous ? "anonymous" : "dev"
+      });
     }
     if (config2.verbose) {
       console.info(
@@ -20931,11 +21668,11 @@ function registerGlasstrace(options) {
         `[glasstrace] Cached config ${cachedInitResponse ? "loaded and applied" : "not found"}.`
       );
     }
-    const sessionManager = new SessionManager();
+    const sessionManager = getSessionManager();
     if (config2.verbose) {
       console.info("[glasstrace] SessionManager created.");
     }
-    isRegistered = true;
+    setCoreState(CoreState.KEY_PENDING);
     const currentGeneration = registrationGeneration;
     const existingProbe = trace.getTracerProvider().getTracer("glasstrace-probe");
     const anotherProviderRegistered = existingProbe.constructor.name !== "ProxyTracer";
@@ -20988,6 +21725,7 @@ function registerGlasstrace(options) {
             resolvedAnonKey = anonKey;
             setResolvedApiKey(anonKey);
             notifyApiKeyResolved();
+            emitLifecycleEvent("auth:key_resolved", { key: maskKey(anonKey), mode: "anonymous" });
             effectiveKey = anonKey;
             if (currentGeneration !== registrationGeneration) return;
             discoveryHandler = createDiscoveryHandler(
@@ -21009,6 +21747,7 @@ function registerGlasstrace(options) {
             const anonKey = await getOrCreateAnonKey();
             setResolvedApiKey(anonKey);
             notifyApiKeyResolved();
+            emitLifecycleEvent("auth:key_resolved", { key: maskKey(anonKey), mode: "anonymous" });
             effectiveKey = anonKey;
             if (currentGeneration !== registrationGeneration) return;
             await backgroundInit(config2, anonKey, currentGeneration);
@@ -21041,6 +21780,7 @@ function registerGlasstrace(options) {
       console.info("[glasstrace] Import graph building skipped.");
     }
   } catch (err) {
+    setCoreState(CoreState.REGISTRATION_FAILED);
     console.warn(
       `[glasstrace] Registration failed: ${err instanceof Error ? err.message : String(err)}`
     );
@@ -21050,18 +21790,37 @@ async function backgroundInit(config2, anonKeyForInit, generation) {
   if (config2.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("0.13.5");
-  const initResult = await performInit(config2, anonKeyForInit, "0.13.5", healthReport);
+  const healthReport = collectHealthReport("0.14.0");
+  const initResult = await performInit(config2, anonKeyForInit, "0.14.0", healthReport);
   if (generation !== registrationGeneration) return;
+  const currentState = getCoreState();
+  if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
+    return;
+  }
+  if (currentState === CoreState.KEY_PENDING) {
+    setCoreState(CoreState.KEY_RESOLVED);
+  }
+  if (getCoreState() === CoreState.KEY_RESOLVED) {
+    setCoreState(didLastInitSucceed() ? CoreState.ACTIVE : CoreState.ACTIVE_DEGRADED);
+  }
   if (initResult?.claimResult) {
-    setResolvedApiKey(initResult.claimResult.newApiKey);
+    const { newApiKey, accountId } = initResult.claimResult;
+    setAuthState(AuthState.CLAIMING);
+    emitLifecycleEvent("auth:claim_started", { accountId });
+    setResolvedApiKey(newApiKey);
     notifyApiKeyResolved();
+    setAuthState(AuthState.CLAIMED);
+    emitLifecycleEvent("auth:claim_completed", { newKey: maskKey(newApiKey), accountId });
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config2, anonKeyForInit, "0.13.5", generation, (newApiKey) => {
+    startHeartbeat(config2, anonKeyForInit, "0.14.0", generation, (newApiKey, accountId) => {
+      setAuthState(AuthState.CLAIMING);
+      emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);
       notifyApiKeyResolved();
+      setAuthState(AuthState.CLAIMED);
+      emitLifecycleEvent("auth:claim_completed", { newKey: maskKey(newApiKey), accountId });
     });
   }
 }
@@ -21359,6 +22118,7 @@ async function buildImportGraph(projectRoot) {
   collectSourceMaps,
   computeBuildHash,
   createDiscoveryHandler,
+  createGlasstraceSpanProcessor,
   deriveSessionId,
   discoverSourceMapFiles,
   discoverTestFiles,
@@ -21369,8 +22129,10 @@ async function buildImportGraph(projectRoot) {
   getLinkedAccountId,
   getOrCreateAnonKey,
   getOrigin,
+  getStatus,
   isAnonymousMode,
   isProductionDisabled,
+  isReady,
   loadCachedConfig,
   performInit,
   readAnonKey,
@@ -21382,6 +22144,7 @@ async function buildImportGraph(projectRoot) {
   uploadSourceMaps,
   uploadSourceMapsAuto,
   uploadSourceMapsPresigned,
+  waitForReady,
   withGlasstraceConfig
 });
 //# sourceMappingURL=index.cjs.map