Skip to content

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

fix(sdk): preserve span context during deferred stream work (#919)

Rudy Mizrahi Celekli2a70b8797e77
diff --git a/docs/changelog/sdk.mdx b/docs/changelog/sdk.mdx
index 5081d9dc..e7acc64d 100644
--- a/docs/changelog/sdk.mdx
+++ b/docs/changelog/sdk.mdx
@@ -13,6 +13,7 @@ Stay up to date with the latest changes to the Beacon Observe SDK.
- **Observed streams read through their own API keep their span** · An observed function returning a stream that has its own reading API, such as the Anthropic SDK's `client.messages.stream()` read with `finalMessage()` or events, a `ReadableStream` read with `getReader()`, or a Node stream sent through `pipe()`, never exported its span: the SDK replaced the stream with a wrapper that only `for await` went through, which also made `instanceof` checks on it fail. Such streams are now returned unchanged and their span ends when the function returns. Async generators and the Claude Agent SDK's `query()` are still traced until they are read to the end.
- **Observe endpoints keep their query string** · An endpoint with query parameters, such as a gateway URL carrying a tenant or routing parameter, had `/v1/observe` appended after its query, so spans went to the wrong route without any error. The path is now added to the URL's path, and the query and fragment are kept. `Observe.initialize()` now throws for an endpoint that is not an absolute URL, instead of exporting to an unusable address.
+- **Spans from an observed stream nest under it** · Work an observed async generator does as it is read, such as tool or model calls, was recorded under whoever consumed the stream, so those spans appeared beside the stream's span instead of inside it. They are now its children, including work in the stream's cleanup.
- **API key scoped to Beacon Cloud** · `ASYMPTOTE_API_KEY` is now sent only to Beacon Cloud: in hosted mode, or to an explicit OTLP endpoint on the same origin as the base URL. Previously a service with both `ASYMPTOTE_API_KEY` and a generic `OTEL_EXPORTER_OTLP_ENDPOINT` sent the key to that collector on every export. Caller-supplied `headers` are unchanged.
- **HTTPS required for the API key** · `Observe.initialize()` now throws when the key would be sent to a non-loopback `http://` base URL. `http://localhost`, `http://127.0.0.1` and `http://[::1]` remain allowed for local stubs.
diff --git a/packages/asymptote-sdk-js/src/index.ts b/packages/asymptote-sdk-js/src/index.ts
index 530e2941..46642a49 100644
--- a/packages/asymptote-sdk-js/src/index.ts
+++ b/packages/asymptote-sdk-js/src/index.ts
@@ -573,11 +573,23 @@ function finishResult<T>(result: T, span: Span, options?: ObserveOptions): unkno
return: iterator.return.bind(iterator),
throw: iterator.throw.bind(iterator),
};
+ const spanContext = trace.setSpan(context.active(), span);
+ const tracedMethods = {
+ next(...args: [] | [unknown]) {
+ return context.with(spanContext, () => methods.next(...args));
+ },
+ return(value?: unknown) {
+ return context.with(spanContext, () => methods.return(value));
+ },
+ throw(error?: unknown) {
+ return context.with(spanContext, () => methods.throw(error));
+ },
+ };
const controls = new Map<Function, Function>();
const stream: AsyncGenerator<unknown> = new Proxy(iterator, {
get(_target, key) {
if (key === Symbol.asyncIterator) return iteratorForStream;
- if (key === "next" || key === "return" || key === "throw") return methods[key];
+ if (key === "next" || key === "return" || key === "throw") return tracedMethods[key];
const value = Reflect.get(result, key, result);
if (typeof value !== "function" || key === "constructor") return value;
let control = controls.get(value);
diff --git a/packages/asymptote-sdk-js/src/stream-context.test.ts b/packages/asymptote-sdk-js/src/stream-context.test.ts
new file mode 100644
index 00000000..d66ec9ae
--- /dev/null
+++ b/packages/asymptote-sdk-js/src/stream-context.test.ts
@@ -0,0 +1,78 @@
+import { context, trace } from "@opentelemetry/api";
+import { InMemorySpanExporter } from "@opentelemetry/sdk-trace-base";
+import { afterEach, beforeEach, expect, it } from "vitest";
+
+import { flush, initialize, observe, shutdown } from "./index.js";
+
+let exporter: InMemorySpanExporter;
+beforeEach(() => {
+ exporter = new InMemorySpanExporter();
+ initialize({ spanExporter: exporter, disableDefaultExporter: true, disableBatch: true, disableInstrumentations: true });
+});
+afterEach(async () => { await shutdown(); });
+
+const activeId = () => trace.getSpan(context.active())?.spanContext().spanId;
+const child = (name: string) => observe({ name }, () => "fixture")();
+
+it.each(["complete", "return", "throw", "source-error"])("keeps deferred stream work under its span (%s)", async mode => {
+ const failure = new Error("fixture stream failure");
+ const step = observe({ name: "stream.parent" }, async function* () {
+ try {
+ await Promise.resolve();
+ child("stream.body");
+ yield "first";
+ await Promise.resolve();
+ if (mode === "source-error") throw failure;
+ child("stream.resumed");
+ yield "second";
+ } finally {
+ await Promise.resolve();
+ child("stream.cleanup");
+ }
+ });
+ const consumer = observe({ name: "consumer" }, async () => {
+ const consumerId = activeId();
+ const stream = step();
+ expect(activeId()).toBe(consumerId);
+ expect(await stream.next()).toEqual({ value: "first", done: false });
+ expect(activeId()).toBe(consumerId);
+ if (mode === "return") await stream.return(undefined);
+ else if (mode === "throw") await expect(stream.throw(failure)).rejects.toBe(failure);
+ else if (mode === "source-error") await expect(stream.next()).rejects.toBe(failure);
+ else {
+ expect(await stream.next()).toEqual({ value: "second", done: false });
+ expect(activeId()).toBe(consumerId);
+ expect(await stream.next()).toEqual({ value: undefined, done: true });
+ }
+ expect(activeId()).toBe(consumerId);
+ });
+ await consumer();
+ expect(activeId()).toBeUndefined();
+ child("outside");
+ await flush();
+ const spans = exporter.getFinishedSpans();
+ const parent = spans.find(span => span.name === "stream.parent")!;
+ const owner = spans.find(span => span.name === "consumer")!;
+ expect(parent.parentSpanContext?.spanId).toBe(owner.spanContext().spanId);
+ for (const name of ["stream.body", "stream.cleanup", ...(mode === "complete" ? ["stream.resumed"] : [])]) {
+ const span = spans.find(span => span.name === name)!;
+ expect(span.parentSpanContext?.spanId, name).toBe(parent.spanContext().spanId);
+ expect(span.spanContext().traceId, name).toBe(parent.spanContext().traceId);
+ }
+ expect(spans.filter(span => span.name === "stream.parent")).toHaveLength(1);
+ expect(spans.find(span => span.name === "outside")?.parentSpanContext).toBeUndefined();
+});
+
+it("keeps the existing asynchronous scalar context", async () => {
+ const step = observe({ name: "scalar.parent" }, async () => {
+ await Promise.resolve();
+ child("scalar.child");
+ return "result";
+ });
+ expect(await step()).toBe("result");
+ expect(activeId()).toBeUndefined();
+ await flush();
+ const spans = exporter.getFinishedSpans();
+ const parent = spans.find(span => span.name === "scalar.parent")!;
+ expect(spans.find(span => span.name === "scalar.child")?.parentSpanContext?.spanId).toBe(parent.spanContext().spanId);
+});