Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

fix(sdk): restore owned global tracers across restarts (#981)

Divyam Talwar825ee7ad8c5e
diff --git a/packages/asymptote-sdk-js/README.md b/packages/asymptote-sdk-js/README.md
index 86b2cd42..fc68bf82 100644
--- a/packages/asymptote-sdk-js/README.md
+++ b/packages/asymptote-sdk-js/README.md
@@ -146,6 +146,9 @@ const plan = Observe.observe(
Call `Observe.flush()` before short-lived scripts exit, or
`Observe.shutdown()` when the process owns the provider lifecycle.
+After shutdown and reinitialization, get new tracers: tracers obtained before
+shutdown stay bound to the stopped provider.
+
## Token Usage Attribution
The OpenLLMetry instrumentations record `gen_ai.usage.*` token counts on every
diff --git a/packages/asymptote-sdk-js/src/global-lifecycle.test.ts b/packages/asymptote-sdk-js/src/global-lifecycle.test.ts
new file mode 100644
index 00000000..a2c70cdf
--- /dev/null
+++ b/packages/asymptote-sdk-js/src/global-lifecycle.test.ts
@@ -0,0 +1,237 @@
+import {
+ ROOT_CONTEXT,
+ context,
+ createContextKey,
+ propagation,
+ trace,
+ type Context,
+ type ContextManager,
+ type TextMapPropagator,
+} from "@opentelemetry/api";
+import { InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { afterEach, beforeEach, expect, it } from "vitest";
+import * as sdk from "./index.js";
+
+const hostProviders: NodeTracerProvider[] = [];
+const hostKey = createContextKey("host-context-control");
+
+beforeEach(() => {
+ trace.disable();
+ context.disable();
+ propagation.disable();
+});
+
+afterEach(async () => {
+ await sdk.shutdown().catch(() => {});
+ await Promise.all(hostProviders.splice(0).map(provider => provider.shutdown()));
+ trace.disable();
+ context.disable();
+ propagation.disable();
+});
+
+function initialize(serviceName: string, exporter = new InMemorySpanExporter()): InMemorySpanExporter {
+ sdk.initialize({ serviceName, spanExporter: exporter, disableBatch: true, disableInstrumentations: true });
+ return exporter;
+}
+
+function emitGlobalAndLocal(): void {
+ trace.getTracer("global-control").startSpan("global-control").end();
+ sdk.getTracer().startSpan("local-control").end();
+}
+
+function expectGeneration(exporter: InMemorySpanExporter, serviceName: string): void {
+ const spans = exporter.getFinishedSpans();
+ expect(spans.map(span => span.name)).toEqual(["global-control", "local-control"]);
+ expect(spans.every(span => span.resource.attributes["service.name"] === serviceName)).toBe(true);
+}
+
+function registerHost(): { provider: NodeTracerProvider; exporter: InMemorySpanExporter } {
+ const exporter = new InMemorySpanExporter();
+ const provider = new NodeTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] });
+ hostProviders.push(provider);
+ provider.register({ contextManager: new HostContextManager(), propagator: hostPropagator });
+ return { provider, exporter };
+}
+
+function expectHostGlobals(): void {
+ context.with(ROOT_CONTEXT.setValue(hostKey, "host-value"), () => {
+ expect(context.active().getValue(hostKey)).toBe("host-value");
+ const carrier: Record<string, string> = {};
+ propagation.inject(context.active(), carrier);
+ expect(carrier).toEqual({ "host-propagator": "host-value" });
+ });
+}
+
+class HostContextManager implements ContextManager {
+ private current = ROOT_CONTEXT;
+
+ active(): Context { return this.current; }
+ with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(ctx: Context, fn: F, thisArg?: ThisParameterType<F>, ...args: A): ReturnType<F> {
+ const previous = this.current;
+ this.current = ctx;
+ try { return fn.apply(thisArg, args); } finally { this.current = previous; }
+ }
+ bind<T>(_: Context, target: T): T { return target; }
+ enable(): this { return this; }
+ disable(): this { return this; }
+}
+
+const hostPropagator: TextMapPropagator = {
+ inject(ctx, carrier, setter) { setter.set(carrier, "host-propagator", String(ctx.getValue(hostKey))); },
+ extract(ctx) { return ctx; },
+ fields() { return ["host-propagator"]; },
+};
+
+it("routes fresh global and local tracers to each owned generation", async () => {
+ for (const serviceName of ["first-generation", "second-generation"]) {
+ const exporter = initialize(serviceName);
+ emitGlobalAndLocal();
+ await sdk.flush();
+ expectGeneration(exporter, serviceName);
+ await sdk.shutdown();
+ }
+});
+
+it("preserves a host replacement installed while the SDK is active", async () => {
+ initialize("sdk-generation");
+ trace.disable();
+ context.disable();
+ propagation.disable();
+ const host = registerHost();
+ await sdk.shutdown();
+ initialize("next-sdk-generation");
+ await sdk.shutdown();
+ expectHostGlobals();
+ trace.getTracer("host-replacement").startSpan("host-replacement").end();
+ await host.provider.forceFlush();
+ expect(host.exporter.getFinishedSpans().map(span => span.name)).toEqual(["host-replacement"]);
+});
+
+it.each(["context", "propagation", "both"])("preserves pre-existing %s registrations through owned tracer restarts", async resource => {
+ if (resource !== "propagation") context.setGlobalContextManager(new HostContextManager());
+ if (resource !== "context") propagation.setGlobalPropagator(hostPropagator);
+ initialize("first-generation");
+ await sdk.shutdown();
+ const replacement = initialize("second-generation");
+ emitGlobalAndLocal();
+ await sdk.flush();
+ expectGeneration(replacement, "second-generation");
+ context.with(ROOT_CONTEXT.setValue(hostKey, "host-value"), () => {
+ expect(context.active().getValue(hostKey)).toBe("host-value");
+ if (resource !== "context") {
+ const carrier: Record<string, string> = {};
+ propagation.inject(context.active(), carrier);
+ expect(carrier).toEqual({ "host-propagator": "host-value" });
+ }
+ });
+});
+
+it("recovers global routing after a module patch fails during initialization", async () => {
+ expect(() => sdk.initialize({
+ spanExporter: new InMemorySpanExporter(), disableBatch: true, disableInstrumentations: true, instrumentModules: {},
+ })).toThrow("Observe.patch requires at least one module");
+ expect(sdk.isInitialized()).toBe(false);
+ const replacement = initialize("recovered-generation");
+ emitGlobalAndLocal();
+ await sdk.flush();
+ expectGeneration(replacement, "recovered-generation");
+});
+
+it("preserves a host replacement when initialization fails partway through patching", async () => {
+ let host: ReturnType<typeof registerHost> | undefined;
+ const modules = {
+ get claudeAgentSDK(): never {
+ trace.disable();
+ context.disable();
+ propagation.disable();
+ host = registerHost();
+ throw new Error("synthetic module patch failure");
+ },
+ };
+ expect(() => sdk.initialize({
+ spanExporter: new InMemorySpanExporter(), disableBatch: true, disableInstrumentations: true, instrumentModules: modules,
+ })).toThrow("synthetic module patch failure");
+ expect(sdk.isInitialized()).toBe(false);
+ expectHostGlobals();
+ trace.getTracer("host-after-failure").startSpan("host-after-failure").end();
+ await host!.provider.forceFlush();
+ expect(host!.exporter.getFinishedSpans().map(span => span.name)).toEqual(["host-after-failure"]);
+});
+
+it("recovers global routing after an exporter rejects shutdown", async () => {
+ class RejectingExporter extends InMemorySpanExporter {
+ override async shutdown(): Promise<void> { throw new Error("synthetic shutdown failure"); }
+ }
+ initialize("failing-generation", new RejectingExporter());
+ await expect(sdk.shutdown()).rejects.toThrow("synthetic shutdown failure");
+ expect(sdk.isInitialized()).toBe(false);
+ const replacement = initialize("recovered-generation");
+ emitGlobalAndLocal();
+ await sdk.flush();
+ expectGeneration(replacement, "recovered-generation");
+});
+
+it("does not let concurrent old shutdown completions detach a new generation", async () => {
+ let release!: () => void;
+ let started!: () => void;
+ const shutdownStarted = new Promise<void>(resolve => { started = resolve; });
+ class DeferredExporter extends InMemorySpanExporter {
+ override async shutdown(): Promise<void> {
+ started();
+ await new Promise<void>(resolve => { release = resolve; });
+ await super.shutdown();
+ }
+ }
+ initialize("first-generation", new DeferredExporter());
+ const firstShutdown = sdk.shutdown();
+ const concurrentShutdown = sdk.shutdown();
+ await shutdownStarted;
+ expect(() => initialize("too-early-generation")).toThrow("already initialized");
+ release();
+ await firstShutdown;
+ const replacement = initialize("second-generation");
+ await concurrentShutdown;
+ emitGlobalAndLocal();
+ await sdk.flush();
+ expectGeneration(replacement, "second-generation");
+});
+
+it("preserves a host replacement installed while exporter shutdown is pending", async () => {
+ let release!: () => void;
+ let started!: () => void;
+ const shutdownStarted = new Promise<void>(resolve => { started = resolve; });
+ class DeferredExporter extends InMemorySpanExporter {
+ override async shutdown(): Promise<void> {
+ started();
+ await new Promise<void>(resolve => { release = resolve; });
+ await super.shutdown();
+ }
+ }
+ initialize("sdk-generation", new DeferredExporter());
+ const pendingShutdown = sdk.shutdown();
+ await shutdownStarted;
+ trace.disable();
+ context.disable();
+ propagation.disable();
+ const host = registerHost();
+ release();
+ await pendingShutdown;
+ expectHostGlobals();
+ trace.getTracer("host-during-shutdown").startSpan("host-during-shutdown").end();
+ await host.provider.forceFlush();
+ expect(host.exporter.getFinishedSpans().map(span => span.name)).toEqual(["host-during-shutdown"]);
+});
+
+it("requires new tracers after shutdown instead of promising cached tracer rebinding", async () => {
+ initialize("first-generation");
+ const cachedGlobalTracer = trace.getTracer("cached-global");
+ const cachedLocalTracer = sdk.getTracer("cached-local");
+ await sdk.shutdown();
+ const replacement = initialize("second-generation");
+ cachedGlobalTracer.startSpan("cached-old-global").end();
+ cachedLocalTracer.startSpan("cached-old-local").end();
+ emitGlobalAndLocal();
+ await sdk.flush();
+ expectGeneration(replacement, "second-generation");
+});
diff --git a/packages/asymptote-sdk-js/src/index.ts b/packages/asymptote-sdk-js/src/index.ts
index 6f8f6e0b..2fcb7aef 100644
--- a/packages/asymptote-sdk-js/src/index.ts
+++ b/packages/asymptote-sdk-js/src/index.ts
@@ -1,4 +1,5 @@
import {
+ ProxyTracerProvider,
SpanKind,
SpanStatusCode,
context,
@@ -228,12 +229,19 @@ export function initialize(options: InitializeOptions = {}): void {
} catch (error) {
instrumentations.forEach(i => i.disable());
provider.shutdown().catch(() => {});
+ releaseGlobalTracer(provider);
state = undefined;
throw error;
}
}
}
+// trace.disable() lets the next provider register globally; a host's provider is left alone.
+function releaseGlobalTracer(provider: NodeTracerProvider): void {
+ const global = trace.getTracerProvider();
+ if (global instanceof ProxyTracerProvider && global.getDelegate() === provider) trace.disable();
+}
+
// changedOptions names the options in next, other than instrumentModules, that differ from the
// active configuration's. Repeating the same options, as the integration guides do in each module
// they set up, is not a change. Plain objects (headers, resource attributes) compare by value;
@@ -393,6 +401,7 @@ export async function shutdown(): Promise<void> {
try {
await current.provider.shutdown();
} finally {
+ releaseGlobalTracer(current.provider);
// A stopped provider cannot resume exporting, even when its exporter rejects.
if (state === current) state = undefined;
}