Skip to content

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

Add SDK sessionAttributes helper for token attribution

Claude7611865ec04f
diff --git a/packages/asymptote-sdk-js/README.md b/packages/asymptote-sdk-js/README.md
index 3270d49c..ed91b2eb 100644
--- a/packages/asymptote-sdk-js/README.md
+++ b/packages/asymptote-sdk-js/README.md
@@ -132,6 +132,31 @@ const plan = Observe.observe(
Call `Observe.flush()` before short-lived scripts exit, or
`Observe.shutdown()` when the process owns the provider lifecycle.
+## Token Usage Attribution
+
+The OpenLLMetry instrumentations record `gen_ai.usage.*` token counts on every
+supported model call, and the Beacon collector normalizes them into endpoint
+JSONL for the token usage dashboard and `beacon endpoint tokens` reports. Two
+notes:
+
+- Streaming responses report usage only after the stream is fully consumed;
+ abandoning a stream early can drop the final usage record for that call.
+- `traceContent` only controls prompt/completion text capture. Numeric token
+ usage is always recorded.
+
+To attribute usage to one agent session across spans, attach
+`Observe.sessionAttributes(sessionId)` to your spans or resource attributes:
+
+```typescript
+const handle = Observe.observe(
+ {
+ name: "agent.handle_request",
+ attributes: Observe.sessionAttributes(conversationId),
+ },
+ async (input: string) => runAgent(input),
+);
+```
+
## Beta Support Matrix
- OpenAI SDK: OpenLLMetry instrumentation enabled by default.
diff --git a/packages/asymptote-sdk-js/src/index.test.ts b/packages/asymptote-sdk-js/src/index.test.ts
index bb7f42e4..61428b97 100644
--- a/packages/asymptote-sdk-js/src/index.test.ts
+++ b/packages/asymptote-sdk-js/src/index.test.ts
@@ -18,6 +18,7 @@ import {
isInitialized,
observe,
resolveExporterConfig,
+ sessionAttributes,
shutdown,
wrapClaudeAgentQuery,
} from "./index.js";
@@ -105,6 +106,27 @@ describe("resolveExporterConfig", () => {
});
});
+describe("sessionAttributes", () => {
+ it("builds beacon and gen_ai session identity attributes", () => {
+ expect(sessionAttributes("session-42")).toEqual({
+ "beacon.session.id": "session-42",
+ "gen_ai.conversation.id": "session-42",
+ });
+ });
+
+ it("includes the working directory when provided", () => {
+ expect(sessionAttributes("session-42", "/srv/agent")).toEqual({
+ "beacon.session.id": "session-42",
+ "gen_ai.conversation.id": "session-42",
+ "beacon.session.working_directory": "/srv/agent",
+ });
+ });
+
+ it("is exposed on the Observe facade", () => {
+ expect(Observe.sessionAttributes("session-42")).toEqual(sessionAttributes("session-42"));
+ });
+});
+
describe("Asymptote Observe SDK", () => {
beforeEach(() => {
clearEnv();
diff --git a/packages/asymptote-sdk-js/src/index.ts b/packages/asymptote-sdk-js/src/index.ts
index d780f7fb..f6fa061e 100644
--- a/packages/asymptote-sdk-js/src/index.ts
+++ b/packages/asymptote-sdk-js/src/index.ts
@@ -41,6 +41,8 @@ import {
ATTR_BEACON_HARNESS_NAME,
ATTR_BEACON_ORIGIN,
ATTR_BEACON_PROMPT_TEXT,
+ ATTR_BEACON_SESSION_ID,
+ ATTR_BEACON_SESSION_WORKING_DIRECTORY,
} from "./constants.js";
export * from "./constants.js";
@@ -136,6 +138,10 @@ export class Observe {
patch(modules);
}
+ static sessionAttributes(sessionId: string, workingDirectory?: string): Attributes {
+ return sessionAttributes(sessionId, workingDirectory);
+ }
+
static instrumentations(options: AsymptoteInstrumentationOptions = {}): Instrumentation[] {
return initializeAsymptoteInstrumentations(options);
}
@@ -250,6 +256,24 @@ export function observe<T extends (...args: any[]) => any>(options: ObserveOptio
} as T;
}
+/**
+ * Builds the span or resource attributes that attribute telemetry to one
+ * agent session for Beacon token usage rollups. Pass the result to
+ * `observe({ attributes: ... })`, `startActiveSpan`, or
+ * `initialize({ resourceAttributes: ... })` so every span in the session
+ * carries the same session identity.
+ */
+export function sessionAttributes(sessionId: string, workingDirectory?: string): Attributes {
+ const attributes: Attributes = {
+ [ATTR_BEACON_SESSION_ID]: sessionId,
+ "gen_ai.conversation.id": sessionId,
+ };
+ if (workingDirectory) {
+ attributes[ATTR_BEACON_SESSION_WORKING_DIRECTORY] = workingDirectory;
+ }
+ return attributes;
+}
+
export function patch(modules: InstrumentModules): void {
if (!modules || Object.keys(modules).length === 0) {
throw new Error("Observe.patch requires at least one module");