@buildanagent/sdk 0.1.0-alpha.6 → 0.1.0-alpha.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +61 -0
- package/dist/errors.d.ts +3 -1
- package/dist/errors.js +2 -0
- package/dist/errors.js.map +1 -1
- package/dist/events.d.ts +10 -1
- package/dist/events.js +1 -0
- package/dist/events.js.map +1 -1
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/loop.d.ts +3 -0
- package/dist/loop.js +46 -3
- package/dist/loop.js.map +1 -1
- package/dist/otel/attributes.d.ts +43 -0
- package/dist/otel/attributes.js +50 -0
- package/dist/otel/attributes.js.map +1 -0
- package/dist/otel/content.d.ts +17 -0
- package/dist/otel/content.js +48 -0
- package/dist/otel/content.js.map +1 -0
- package/dist/otel/index.d.ts +6 -2
- package/dist/otel/index.js +6 -2
- package/dist/otel/index.js.map +1 -1
- package/dist/otel/observer.d.ts +82 -0
- package/dist/otel/observer.js +286 -0
- package/dist/otel/observer.js.map +1 -0
- package/dist/run.d.ts +18 -0
- package/dist/run.js +10 -1
- package/dist/run.js.map +1 -1
- package/dist/steering.d.ts +52 -0
- package/dist/steering.js +104 -0
- package/dist/steering.js.map +1 -0
- package/package.json +4 -2
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The OpenTelemetry GenAI names the observer writes, in one place. The GenAI semantic conventions are at Development
|
|
3
|
+
* stability, so a rename upstream is a one-line change here, and the harness's log projection imports the same names.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* The commit of `open-telemetry/semantic-conventions-genai` whose attribute and span names this module follows. A
|
|
7
|
+
* harness that exports spans can stamp it on its resource, so a reader knows which revision of the conventions the
|
|
8
|
+
* names come from.
|
|
9
|
+
*/
|
|
10
|
+
export declare const SEMCONV_GENAI_COMMIT: "d28355d";
|
|
11
|
+
/** The `gen_ai.*` and `error.*` attribute names the observer writes, keyed by what each holds. */
|
|
12
|
+
export declare const GEN_AI_ATTRIBUTES: Readonly<{
|
|
13
|
+
readonly operationName: "gen_ai.operation.name";
|
|
14
|
+
readonly providerName: "gen_ai.provider.name";
|
|
15
|
+
readonly agentName: "gen_ai.agent.name";
|
|
16
|
+
readonly requestModel: "gen_ai.request.model";
|
|
17
|
+
readonly requestMaxTokens: "gen_ai.request.max_tokens";
|
|
18
|
+
readonly requestTemperature: "gen_ai.request.temperature";
|
|
19
|
+
readonly responseFinishReasons: "gen_ai.response.finish_reasons";
|
|
20
|
+
readonly usageInputTokens: "gen_ai.usage.input_tokens";
|
|
21
|
+
readonly usageOutputTokens: "gen_ai.usage.output_tokens";
|
|
22
|
+
readonly usageCacheReadInputTokens: "gen_ai.usage.cache_read.input_tokens";
|
|
23
|
+
readonly usageCacheWriteInputTokens: "gen_ai.usage.cache_write.input_tokens";
|
|
24
|
+
readonly usageReasoningOutputTokens: "gen_ai.usage.reasoning.output_tokens";
|
|
25
|
+
readonly toolName: "gen_ai.tool.name";
|
|
26
|
+
readonly toolType: "gen_ai.tool.type";
|
|
27
|
+
readonly toolCallId: "gen_ai.tool.call.id";
|
|
28
|
+
readonly errorType: "error.type";
|
|
29
|
+
/** Content: written only when `captureContent` is on. */
|
|
30
|
+
readonly systemInstructions: "gen_ai.system_instructions";
|
|
31
|
+
readonly inputMessages: "gen_ai.input.messages";
|
|
32
|
+
readonly outputMessages: "gen_ai.output.messages";
|
|
33
|
+
readonly toolCallArguments: "gen_ai.tool.call.arguments";
|
|
34
|
+
readonly toolCallResult: "gen_ai.tool.call.result";
|
|
35
|
+
}>;
|
|
36
|
+
/** The names of the attributes that hold content: what the model and the tools read and wrote. */
|
|
37
|
+
export declare const GEN_AI_CONTENT_ATTRIBUTES: readonly string[];
|
|
38
|
+
/** The `gen_ai.operation.name` values the observer writes. */
|
|
39
|
+
export declare const GEN_AI_OPERATIONS: Readonly<{
|
|
40
|
+
readonly invokeAgent: "invoke_agent";
|
|
41
|
+
readonly chat: "chat";
|
|
42
|
+
readonly executeTool: "execute_tool";
|
|
43
|
+
}>;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The OpenTelemetry GenAI names the observer writes, in one place. The GenAI semantic conventions are at Development
|
|
3
|
+
* stability, so a rename upstream is a one-line change here, and the harness's log projection imports the same names.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* The commit of `open-telemetry/semantic-conventions-genai` whose attribute and span names this module follows. A
|
|
7
|
+
* harness that exports spans can stamp it on its resource, so a reader knows which revision of the conventions the
|
|
8
|
+
* names come from.
|
|
9
|
+
*/
|
|
10
|
+
export const SEMCONV_GENAI_COMMIT = "d28355d";
|
|
11
|
+
/** The `gen_ai.*` and `error.*` attribute names the observer writes, keyed by what each holds. */
|
|
12
|
+
export const GEN_AI_ATTRIBUTES = Object.freeze({
|
|
13
|
+
operationName: "gen_ai.operation.name",
|
|
14
|
+
providerName: "gen_ai.provider.name",
|
|
15
|
+
agentName: "gen_ai.agent.name",
|
|
16
|
+
requestModel: "gen_ai.request.model",
|
|
17
|
+
requestMaxTokens: "gen_ai.request.max_tokens",
|
|
18
|
+
requestTemperature: "gen_ai.request.temperature",
|
|
19
|
+
responseFinishReasons: "gen_ai.response.finish_reasons",
|
|
20
|
+
usageInputTokens: "gen_ai.usage.input_tokens",
|
|
21
|
+
usageOutputTokens: "gen_ai.usage.output_tokens",
|
|
22
|
+
usageCacheReadInputTokens: "gen_ai.usage.cache_read.input_tokens",
|
|
23
|
+
usageCacheWriteInputTokens: "gen_ai.usage.cache_write.input_tokens",
|
|
24
|
+
usageReasoningOutputTokens: "gen_ai.usage.reasoning.output_tokens",
|
|
25
|
+
toolName: "gen_ai.tool.name",
|
|
26
|
+
toolType: "gen_ai.tool.type",
|
|
27
|
+
toolCallId: "gen_ai.tool.call.id",
|
|
28
|
+
errorType: "error.type",
|
|
29
|
+
/** Content: written only when `captureContent` is on. */
|
|
30
|
+
systemInstructions: "gen_ai.system_instructions",
|
|
31
|
+
inputMessages: "gen_ai.input.messages",
|
|
32
|
+
outputMessages: "gen_ai.output.messages",
|
|
33
|
+
toolCallArguments: "gen_ai.tool.call.arguments",
|
|
34
|
+
toolCallResult: "gen_ai.tool.call.result",
|
|
35
|
+
});
|
|
36
|
+
/** The names of the attributes that hold content: what the model and the tools read and wrote. */
|
|
37
|
+
export const GEN_AI_CONTENT_ATTRIBUTES = Object.freeze([
|
|
38
|
+
GEN_AI_ATTRIBUTES.systemInstructions,
|
|
39
|
+
GEN_AI_ATTRIBUTES.inputMessages,
|
|
40
|
+
GEN_AI_ATTRIBUTES.outputMessages,
|
|
41
|
+
GEN_AI_ATTRIBUTES.toolCallArguments,
|
|
42
|
+
GEN_AI_ATTRIBUTES.toolCallResult,
|
|
43
|
+
]);
|
|
44
|
+
/** The `gen_ai.operation.name` values the observer writes. */
|
|
45
|
+
export const GEN_AI_OPERATIONS = Object.freeze({
|
|
46
|
+
invokeAgent: "invoke_agent",
|
|
47
|
+
chat: "chat",
|
|
48
|
+
executeTool: "execute_tool",
|
|
49
|
+
});
|
|
50
|
+
//# sourceMappingURL=attributes.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../src/otel/attributes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAkB,CAAC;AAEvD,kGAAkG;AAClG,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7C,aAAa,EAAE,uBAAuB;IACtC,YAAY,EAAE,sBAAsB;IACpC,SAAS,EAAE,mBAAmB;IAC9B,YAAY,EAAE,sBAAsB;IACpC,gBAAgB,EAAE,2BAA2B;IAC7C,kBAAkB,EAAE,4BAA4B;IAChD,qBAAqB,EAAE,gCAAgC;IACvD,gBAAgB,EAAE,2BAA2B;IAC7C,iBAAiB,EAAE,4BAA4B;IAC/C,yBAAyB,EAAE,sCAAsC;IACjE,0BAA0B,EAAE,uCAAuC;IACnE,0BAA0B,EAAE,sCAAsC;IAClE,QAAQ,EAAE,kBAAkB;IAC5B,QAAQ,EAAE,kBAAkB;IAC5B,UAAU,EAAE,qBAAqB;IACjC,SAAS,EAAE,YAAY;IACvB,yDAAyD;IACzD,kBAAkB,EAAE,4BAA4B;IAChD,aAAa,EAAE,uBAAuB;IACtC,cAAc,EAAE,wBAAwB;IACxC,iBAAiB,EAAE,4BAA4B;IAC/C,cAAc,EAAE,yBAAyB;CACjC,CAAC,CAAC;AAEZ,kGAAkG;AAClG,MAAM,CAAC,MAAM,yBAAyB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACxE,iBAAiB,CAAC,kBAAkB;IACpC,iBAAiB,CAAC,aAAa;IAC/B,iBAAiB,CAAC,cAAc;IAChC,iBAAiB,CAAC,iBAAiB;IACnC,iBAAiB,CAAC,cAAc;CACjC,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7C,WAAW,EAAE,cAAc;IAC3B,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,cAAc;CACnB,CAAC,CAAC","sourcesContent":["/**\n * The OpenTelemetry GenAI names the observer writes, in one place. The GenAI semantic conventions are at Development\n * stability, so a rename upstream is a one-line change here, and the harness's log projection imports the same names.\n */\n\n/**\n * The commit of `open-telemetry/semantic-conventions-genai` whose attribute and span names this module follows. A\n * harness that exports spans can stamp it on its resource, so a reader knows which revision of the conventions the\n * names come from.\n */\nexport const SEMCONV_GENAI_COMMIT = \"d28355d\" as const;\n\n/** The `gen_ai.*` and `error.*` attribute names the observer writes, keyed by what each holds. */\nexport const GEN_AI_ATTRIBUTES = Object.freeze({\n operationName: \"gen_ai.operation.name\",\n providerName: \"gen_ai.provider.name\",\n agentName: \"gen_ai.agent.name\",\n requestModel: \"gen_ai.request.model\",\n requestMaxTokens: \"gen_ai.request.max_tokens\",\n requestTemperature: \"gen_ai.request.temperature\",\n responseFinishReasons: \"gen_ai.response.finish_reasons\",\n usageInputTokens: \"gen_ai.usage.input_tokens\",\n usageOutputTokens: \"gen_ai.usage.output_tokens\",\n usageCacheReadInputTokens: \"gen_ai.usage.cache_read.input_tokens\",\n usageCacheWriteInputTokens: \"gen_ai.usage.cache_write.input_tokens\",\n usageReasoningOutputTokens: \"gen_ai.usage.reasoning.output_tokens\",\n toolName: \"gen_ai.tool.name\",\n toolType: \"gen_ai.tool.type\",\n toolCallId: \"gen_ai.tool.call.id\",\n errorType: \"error.type\",\n /** Content: written only when `captureContent` is on. */\n systemInstructions: \"gen_ai.system_instructions\",\n inputMessages: \"gen_ai.input.messages\",\n outputMessages: \"gen_ai.output.messages\",\n toolCallArguments: \"gen_ai.tool.call.arguments\",\n toolCallResult: \"gen_ai.tool.call.result\",\n} as const);\n\n/** The names of the attributes that hold content: what the model and the tools read and wrote. */\nexport const GEN_AI_CONTENT_ATTRIBUTES: readonly string[] = Object.freeze([\n GEN_AI_ATTRIBUTES.systemInstructions,\n GEN_AI_ATTRIBUTES.inputMessages,\n GEN_AI_ATTRIBUTES.outputMessages,\n GEN_AI_ATTRIBUTES.toolCallArguments,\n GEN_AI_ATTRIBUTES.toolCallResult,\n]);\n\n/** The `gen_ai.operation.name` values the observer writes. */\nexport const GEN_AI_OPERATIONS = Object.freeze({\n invokeAgent: \"invoke_agent\",\n chat: \"chat\",\n executeTool: \"execute_tool\",\n} as const);\n"]}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Turns the SDK's transcript into the JSON the GenAI conventions describe for content attributes: messages with
|
|
3
|
+
* typed `parts`. Only the observer reads this, and only when `captureContent` is on.
|
|
4
|
+
*/
|
|
5
|
+
import type { ContentBlock, Message, ModelContent } from "@buildanagent/gateway";
|
|
6
|
+
type Part = Readonly<Record<string, unknown>>;
|
|
7
|
+
/** The parts of a result's content, as the conventions' `gen_ai.tool.call.result` or a tool message holds them. */
|
|
8
|
+
export declare function resultParts(content: readonly ModelContent[]): readonly Part[];
|
|
9
|
+
/** `gen_ai.input.messages` for a call's messages, as a JSON string. */
|
|
10
|
+
export declare function inputMessagesJson(messages: readonly Message[]): string;
|
|
11
|
+
/** `gen_ai.output.messages` for the model's answer, as a JSON string. */
|
|
12
|
+
export declare function outputMessagesJson(content: readonly ContentBlock[]): string;
|
|
13
|
+
/** `gen_ai.system_instructions`: the system prompt as one text part. */
|
|
14
|
+
export declare function systemInstructionsJson(system: string): string;
|
|
15
|
+
/** A tool's arguments or result as a JSON string; a value JSON cannot hold becomes its string form. */
|
|
16
|
+
export declare function jsonValue(value: unknown): string;
|
|
17
|
+
export {};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
function blockPart(block) {
|
|
2
|
+
switch (block.type) {
|
|
3
|
+
case "text":
|
|
4
|
+
return { type: "text", content: block.text };
|
|
5
|
+
case "reasoning":
|
|
6
|
+
return { type: "reasoning", content: block.text };
|
|
7
|
+
case "image":
|
|
8
|
+
// The bytes would swamp a span, so the part keeps the type and drops the data.
|
|
9
|
+
return { type: "blob", modality: "image", mime_type: block.mediaType };
|
|
10
|
+
case "tool_call":
|
|
11
|
+
return { type: "tool_call", id: block.callId, name: block.name, arguments: block.input };
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
/** The parts of a result's content, as the conventions' `gen_ai.tool.call.result` or a tool message holds them. */
|
|
15
|
+
export function resultParts(content) {
|
|
16
|
+
return content.map(blockPart);
|
|
17
|
+
}
|
|
18
|
+
function messageOf(message) {
|
|
19
|
+
if (message.role === "tool") {
|
|
20
|
+
return {
|
|
21
|
+
role: "tool",
|
|
22
|
+
parts: [{ type: "tool_call_response", id: message.callId, response: resultParts(message.content) }],
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
return { role: message.role, parts: message.content.map(blockPart) };
|
|
26
|
+
}
|
|
27
|
+
/** `gen_ai.input.messages` for a call's messages, as a JSON string. */
|
|
28
|
+
export function inputMessagesJson(messages) {
|
|
29
|
+
return JSON.stringify(messages.map(messageOf));
|
|
30
|
+
}
|
|
31
|
+
/** `gen_ai.output.messages` for the model's answer, as a JSON string. */
|
|
32
|
+
export function outputMessagesJson(content) {
|
|
33
|
+
return JSON.stringify([{ role: "assistant", parts: content.map(blockPart) }]);
|
|
34
|
+
}
|
|
35
|
+
/** `gen_ai.system_instructions`: the system prompt as one text part. */
|
|
36
|
+
export function systemInstructionsJson(system) {
|
|
37
|
+
return JSON.stringify([{ type: "text", content: system }]);
|
|
38
|
+
}
|
|
39
|
+
/** A tool's arguments or result as a JSON string; a value JSON cannot hold becomes its string form. */
|
|
40
|
+
export function jsonValue(value) {
|
|
41
|
+
try {
|
|
42
|
+
return JSON.stringify(value) ?? String(value);
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
return String(value);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
//# sourceMappingURL=content.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/otel/content.ts"],"names":[],"mappings":"AAQA,SAAS,SAAS,CAAC,KAAmB;IACpC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QAC/C,KAAK,WAAW;YACd,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QACpD,KAAK,OAAO;YACV,+EAA+E;YAC/E,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;QACzE,KAAK,WAAW;YACd,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAC7F,CAAC;AACH,CAAC;AAED,mHAAmH;AACnH,MAAM,UAAU,WAAW,CAAC,OAAgC;IAC1D,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,SAAS,CAAC,OAAgB;IACjC,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;SACpG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;AACvE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,QAA4B;IAC5D,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,kBAAkB,CAAC,OAAgC;IACjE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC","sourcesContent":["/**\n * Turns the SDK's transcript into the JSON the GenAI conventions describe for content attributes: messages with\n * typed `parts`. Only the observer reads this, and only when `captureContent` is on.\n */\nimport type { ContentBlock, Message, ModelContent } from \"@buildanagent/gateway\";\n\ntype Part = Readonly<Record<string, unknown>>;\n\nfunction blockPart(block: ContentBlock): Part {\n switch (block.type) {\n case \"text\":\n return { type: \"text\", content: block.text };\n case \"reasoning\":\n return { type: \"reasoning\", content: block.text };\n case \"image\":\n // The bytes would swamp a span, so the part keeps the type and drops the data.\n return { type: \"blob\", modality: \"image\", mime_type: block.mediaType };\n case \"tool_call\":\n return { type: \"tool_call\", id: block.callId, name: block.name, arguments: block.input };\n }\n}\n\n/** The parts of a result's content, as the conventions' `gen_ai.tool.call.result` or a tool message holds them. */\nexport function resultParts(content: readonly ModelContent[]): readonly Part[] {\n return content.map(blockPart);\n}\n\nfunction messageOf(message: Message): { readonly role: string; readonly parts: readonly Part[] } {\n if (message.role === \"tool\") {\n return {\n role: \"tool\",\n parts: [{ type: \"tool_call_response\", id: message.callId, response: resultParts(message.content) }],\n };\n }\n return { role: message.role, parts: message.content.map(blockPart) };\n}\n\n/** `gen_ai.input.messages` for a call's messages, as a JSON string. */\nexport function inputMessagesJson(messages: readonly Message[]): string {\n return JSON.stringify(messages.map(messageOf));\n}\n\n/** `gen_ai.output.messages` for the model's answer, as a JSON string. */\nexport function outputMessagesJson(content: readonly ContentBlock[]): string {\n return JSON.stringify([{ role: \"assistant\", parts: content.map(blockPart) }]);\n}\n\n/** `gen_ai.system_instructions`: the system prompt as one text part. */\nexport function systemInstructionsJson(system: string): string {\n return JSON.stringify([{ type: \"text\", content: system }]);\n}\n\n/** A tool's arguments or result as a JSON string; a value JSON cannot hold becomes its string form. */\nexport function jsonValue(value: unknown): string {\n try {\n return JSON.stringify(value) ?? String(value);\n } catch {\n return String(value);\n }\n}\n"]}
|
package/dist/otel/index.d.ts
CHANGED
|
@@ -1,2 +1,6 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/sdk/otel`: the OpenTelemetry observer. `otelObserver()` projects a run's events onto `gen_ai.*`
|
|
3
|
+
* spans, with content off unless the caller turns it on, and exports only to the tracer the caller passes.
|
|
4
|
+
*/
|
|
5
|
+
export { GEN_AI_ATTRIBUTES, GEN_AI_CONTENT_ATTRIBUTES, GEN_AI_OPERATIONS, SEMCONV_GENAI_COMMIT, } from "./attributes.js";
|
|
6
|
+
export { type AttributeValueLike, type OtelObserver, type OtelObserverOptions, otelObserver, type SpanLike, type SpanOptionsLike, type TracerLike, } from "./observer.js";
|
package/dist/otel/index.js
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/sdk/otel`: the OpenTelemetry observer. `otelObserver()` projects a run's events onto `gen_ai.*`
|
|
3
|
+
* spans, with content off unless the caller turns it on, and exports only to the tracer the caller passes.
|
|
4
|
+
*/
|
|
5
|
+
export { GEN_AI_ATTRIBUTES, GEN_AI_CONTENT_ATTRIBUTES, GEN_AI_OPERATIONS, SEMCONV_GENAI_COMMIT, } from "./attributes.js";
|
|
6
|
+
export { otelObserver, } from "./observer.js";
|
|
3
7
|
//# sourceMappingURL=index.js.map
|
package/dist/otel/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/otel/index.ts"],"names":[],"mappings":"AAAA,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/otel/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAIL,YAAY,GAIb,MAAM,eAAe,CAAC","sourcesContent":["/**\n * `@buildanagent/sdk/otel`: the OpenTelemetry observer. `otelObserver()` projects a run's events onto `gen_ai.*`\n * spans, with content off unless the caller turns it on, and exports only to the tracer the caller passes.\n */\nexport {\n GEN_AI_ATTRIBUTES,\n GEN_AI_CONTENT_ATTRIBUTES,\n GEN_AI_OPERATIONS,\n SEMCONV_GENAI_COMMIT,\n} from \"./attributes.js\";\nexport {\n type AttributeValueLike,\n type OtelObserver,\n type OtelObserverOptions,\n otelObserver,\n type SpanLike,\n type SpanOptionsLike,\n type TracerLike,\n} from \"./observer.js\";\n"]}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import type { Observer } from "../hooks.js";
|
|
2
|
+
/** An attribute value a span accepts. */
|
|
3
|
+
export type AttributeValueLike = string | number | boolean | string[];
|
|
4
|
+
/** What `startSpan` takes: the fields of `@opentelemetry/api`'s `SpanOptions` that the observer sets. */
|
|
5
|
+
export interface SpanOptionsLike {
|
|
6
|
+
/** An OpenTelemetry `SpanKind` number: 0 is internal and 2 is client. */
|
|
7
|
+
readonly kind?: number;
|
|
8
|
+
readonly attributes?: Readonly<Record<string, AttributeValueLike>>;
|
|
9
|
+
/** Start time in milliseconds since the Unix epoch. */
|
|
10
|
+
readonly startTime?: number;
|
|
11
|
+
}
|
|
12
|
+
/** The span methods the observer calls. An OpenTelemetry `Span` has all of them. */
|
|
13
|
+
export interface SpanLike {
|
|
14
|
+
setAttribute(name: string, value: AttributeValueLike): unknown;
|
|
15
|
+
/** `code` 2 is `SpanStatusCode.ERROR`. */
|
|
16
|
+
setStatus?(status: {
|
|
17
|
+
readonly code: number;
|
|
18
|
+
readonly message?: string;
|
|
19
|
+
}): unknown;
|
|
20
|
+
/** `endTime` is in milliseconds since the Unix epoch. */
|
|
21
|
+
end(endTime?: number): void;
|
|
22
|
+
}
|
|
23
|
+
/** The tracer method the observer calls. An OpenTelemetry `Tracer` has it, so a real tracer fits without a wrapper. */
|
|
24
|
+
export interface TracerLike {
|
|
25
|
+
startSpan(name: string, options?: SpanOptionsLike, context?: unknown): SpanLike;
|
|
26
|
+
}
|
|
27
|
+
/** Options for `otelObserver()`. */
|
|
28
|
+
export interface OtelObserverOptions {
|
|
29
|
+
/** The tracer that receives the spans. The observer exports nowhere else. */
|
|
30
|
+
readonly tracer: TracerLike;
|
|
31
|
+
/**
|
|
32
|
+
* Whether to record content: the system prompt, the messages of each call, each tool's arguments and result, and
|
|
33
|
+
* the message of each error as its span's status description. Off by default, because content can hold secrets
|
|
34
|
+
* and personal data that a trace backend should not receive. An error's message can quote any of them, so with
|
|
35
|
+
* content off a failed span gets only its error status and `error.type`.
|
|
36
|
+
*/
|
|
37
|
+
readonly captureContent?: boolean;
|
|
38
|
+
/** The agent's name: it names the `invoke_agent` span and sets `gen_ai.agent.name`. */
|
|
39
|
+
readonly agentName?: string;
|
|
40
|
+
/**
|
|
41
|
+
* The context the run's span starts in, passed to the tracer as `startSpan`'s third argument: the caller's own
|
|
42
|
+
* span, such as an incoming request's. Every run the observer serves starts in this one context, so when it
|
|
43
|
+
* belongs to one request, create one observer for each request. Left out, the run's span starts in whatever the
|
|
44
|
+
* tracer treats as its default, which for an OpenTelemetry tracer is the active context. A run that a tool starts
|
|
45
|
+
* is another run to the observer, with the same `parentContext`: its span is not a child of the calling tool's
|
|
46
|
+
* span, because events carry no parent run id.
|
|
47
|
+
*/
|
|
48
|
+
readonly parentContext?: unknown;
|
|
49
|
+
/**
|
|
50
|
+
* Makes the context a child span starts in from the run's span, so the spans of model and tool calls are children
|
|
51
|
+
* of the run's span in its trace. With OpenTelemetry's API, pass
|
|
52
|
+
* `(span) => trace.setSpan(context.active(), span as Span)`. It is required because the observer imports nothing
|
|
53
|
+
* from OpenTelemetry and so cannot build a context itself.
|
|
54
|
+
*/
|
|
55
|
+
readonly childContext: (parent: SpanLike) => unknown;
|
|
56
|
+
/**
|
|
57
|
+
* Flushes the exporter behind the tracer, such as `() => provider.forceFlush()`. `flush()` on the observer calls
|
|
58
|
+
* it, so a Worker can pass `observer.flush()` to `waitUntil` and keep its spans from dying with the request.
|
|
59
|
+
*/
|
|
60
|
+
readonly forceFlush?: () => Promise<unknown>;
|
|
61
|
+
}
|
|
62
|
+
/** The observer `otelObserver()` returns: an `Observer` that can also flush its exporter and end a run that threw. */
|
|
63
|
+
export type OtelObserver = Observer & {
|
|
64
|
+
/** Resolves once the exporter behind the tracer has flushed, or at once when `forceFlush` was not passed. */
|
|
65
|
+
flush(): Promise<void>;
|
|
66
|
+
/**
|
|
67
|
+
* Ends the open spans of a run whose `result` rejected, as failed, and forgets the run. A run that throws, for a
|
|
68
|
+
* programmer error such as a tool that returns a malformed result, sends no `run_end`, so without this call its
|
|
69
|
+
* spans are never exported. `error.type` is the error's `code` when it has one, such as an `SdkError`'s, and its
|
|
70
|
+
* `name` otherwise. It ends every span, then rethrows the first error a tracer threw. An unknown run id, or a run
|
|
71
|
+
* that already ended, does nothing.
|
|
72
|
+
*/
|
|
73
|
+
endRun(runId: string, error?: unknown): void;
|
|
74
|
+
};
|
|
75
|
+
/**
|
|
76
|
+
* Creates an observer that projects a run's events onto OpenTelemetry GenAI spans. Pass it in `run()`'s
|
|
77
|
+
* `observers`: an observer added later with `run.on()` misses `run_start`, so it records nothing for that run. One
|
|
78
|
+
* observer can serve many runs, because it keeps each run's spans apart by run id.
|
|
79
|
+
*
|
|
80
|
+
* Without `captureContent`, no span holds a prompt, a message, a tool argument, a tool result or an error message.
|
|
81
|
+
*/
|
|
82
|
+
export declare function otelObserver(options: OtelObserverOptions): OtelObserver;
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The OpenTelemetry observer: projects a run's events onto GenAI spans. One `invoke_agent` span covers the run, a
|
|
3
|
+
* `chat` span covers each model call and an `execute_tool` span covers each tool call, both children of the run's
|
|
4
|
+
* span. The observer only watches, like every observer: a tracer that throws is reported as a `hook_error` event
|
|
5
|
+
* and never touches the run, and the run's own spans are still ended and forgotten.
|
|
6
|
+
*
|
|
7
|
+
* The observer writes to the tracer the caller passes and nowhere else. It imports nothing from OpenTelemetry, so
|
|
8
|
+
* `@opentelemetry/api` is the caller's dependency, and the trace context it needs comes in as options, not from an
|
|
9
|
+
* ambient context that Workers and other runtimes may not carry across `await`.
|
|
10
|
+
*/
|
|
11
|
+
import { totalInput } from "@buildanagent/gateway";
|
|
12
|
+
import { GEN_AI_ATTRIBUTES as A, GEN_AI_OPERATIONS } from "./attributes.js";
|
|
13
|
+
import { inputMessagesJson, jsonValue, outputMessagesJson, resultParts, systemInstructionsJson } from "./content.js";
|
|
14
|
+
/** The `SpanKind` numbers of `@opentelemetry/api`. */
|
|
15
|
+
const SPAN_KIND_INTERNAL = 0;
|
|
16
|
+
const SPAN_KIND_CLIENT = 2;
|
|
17
|
+
/** `SpanStatusCode.ERROR` of `@opentelemetry/api`. */
|
|
18
|
+
const STATUS_ERROR = 2;
|
|
19
|
+
function millis(timestamp) {
|
|
20
|
+
const value = Date.parse(timestamp);
|
|
21
|
+
return Number.isNaN(value) ? undefined : value;
|
|
22
|
+
}
|
|
23
|
+
/** Marks a span failed. `message` is free text, so it goes in only when `withMessage`, which content capture sets. */
|
|
24
|
+
function failed(span, message, withMessage, errorType) {
|
|
25
|
+
if (errorType !== undefined)
|
|
26
|
+
span.setAttribute(A.errorType, errorType);
|
|
27
|
+
span.setStatus?.(withMessage ? { code: STATUS_ERROR, message } : { code: STATUS_ERROR });
|
|
28
|
+
}
|
|
29
|
+
/** The low-cardinality `error.type` of a thrown value: its `code`, then its `name`, then the conventions' `_OTHER`. */
|
|
30
|
+
function errorTypeOf(error) {
|
|
31
|
+
if (typeof error === "object" && error !== null) {
|
|
32
|
+
const { code, name } = error;
|
|
33
|
+
if (typeof code === "string" && code !== "")
|
|
34
|
+
return code;
|
|
35
|
+
if (typeof name === "string" && name !== "")
|
|
36
|
+
return name;
|
|
37
|
+
}
|
|
38
|
+
return "_OTHER";
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Writes the usage attributes of one call or one run. Input counts every class, because the conventions' input
|
|
42
|
+
* tokens include cached tokens (D3). A usage the provider did not report writes nothing, since its counts are
|
|
43
|
+
* incomplete and zero would read as a measurement.
|
|
44
|
+
*/
|
|
45
|
+
function setUsage(span, usage) {
|
|
46
|
+
if (usage.unreported === true)
|
|
47
|
+
return;
|
|
48
|
+
span.setAttribute(A.usageInputTokens, totalInput(usage));
|
|
49
|
+
span.setAttribute(A.usageOutputTokens, usage.output);
|
|
50
|
+
if (usage.cacheRead > 0)
|
|
51
|
+
span.setAttribute(A.usageCacheReadInputTokens, usage.cacheRead);
|
|
52
|
+
const cacheWrite = usage.cacheWrite["5m"] + usage.cacheWrite["1h"];
|
|
53
|
+
if (cacheWrite > 0)
|
|
54
|
+
span.setAttribute(A.usageCacheWriteInputTokens, cacheWrite);
|
|
55
|
+
if (usage.reasoning > 0)
|
|
56
|
+
span.setAttribute(A.usageReasoningOutputTokens, usage.reasoning);
|
|
57
|
+
}
|
|
58
|
+
/** The finish reason each stop reason of a model call reports; an aborted call is `interrupted`. */
|
|
59
|
+
const FINISH_REASONS = {
|
|
60
|
+
stop: "stop",
|
|
61
|
+
length: "length",
|
|
62
|
+
tool_calls: "tool_calls",
|
|
63
|
+
error: "error",
|
|
64
|
+
aborted: "interrupted",
|
|
65
|
+
};
|
|
66
|
+
/** Holds the open spans of each run and turns one event at a time into span calls. */
|
|
67
|
+
class Projection {
|
|
68
|
+
#options;
|
|
69
|
+
#tracer;
|
|
70
|
+
#captureContent;
|
|
71
|
+
#runs = new Map();
|
|
72
|
+
constructor(options) {
|
|
73
|
+
this.#options = options;
|
|
74
|
+
this.#tracer = options.tracer;
|
|
75
|
+
this.#captureContent = options.captureContent ?? false;
|
|
76
|
+
}
|
|
77
|
+
handle(event) {
|
|
78
|
+
if (event.type === "run_start") {
|
|
79
|
+
this.#startAgent(event);
|
|
80
|
+
return;
|
|
81
|
+
}
|
|
82
|
+
const spans = this.#runs.get(event.runId);
|
|
83
|
+
if (spans === undefined)
|
|
84
|
+
return;
|
|
85
|
+
switch (event.type) {
|
|
86
|
+
case "model_call_start":
|
|
87
|
+
this.#startModelCall(event, spans);
|
|
88
|
+
break;
|
|
89
|
+
case "model_call_end":
|
|
90
|
+
this.#endModelCall(event, spans);
|
|
91
|
+
break;
|
|
92
|
+
case "tool_call_start":
|
|
93
|
+
this.#startTool(event, spans);
|
|
94
|
+
break;
|
|
95
|
+
case "tool_call_end":
|
|
96
|
+
this.#endTool(event, spans);
|
|
97
|
+
break;
|
|
98
|
+
case "run_end":
|
|
99
|
+
this.#endRun(event, spans);
|
|
100
|
+
break;
|
|
101
|
+
default:
|
|
102
|
+
break;
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
#startAgent(event) {
|
|
106
|
+
const name = this.#options.agentName;
|
|
107
|
+
const agent = this.#tracer.startSpan(name === undefined ? GEN_AI_OPERATIONS.invokeAgent : `${GEN_AI_OPERATIONS.invokeAgent} ${name}`, {
|
|
108
|
+
kind: SPAN_KIND_INTERNAL,
|
|
109
|
+
attributes: {
|
|
110
|
+
[A.operationName]: GEN_AI_OPERATIONS.invokeAgent,
|
|
111
|
+
[A.providerName]: event.model.provider,
|
|
112
|
+
[A.requestModel]: event.model.id,
|
|
113
|
+
...(name === undefined ? {} : { [A.agentName]: name }),
|
|
114
|
+
},
|
|
115
|
+
...startTime(event),
|
|
116
|
+
}, this.#options.parentContext);
|
|
117
|
+
let childContext;
|
|
118
|
+
try {
|
|
119
|
+
childContext = this.#options.childContext(agent);
|
|
120
|
+
}
|
|
121
|
+
catch (error) {
|
|
122
|
+
// The run's span would otherwise stay open for ever, since the run is never registered to end it.
|
|
123
|
+
agent.end(millis(event.timestamp));
|
|
124
|
+
throw error;
|
|
125
|
+
}
|
|
126
|
+
this.#runs.set(event.runId, { agent, childContext, model: undefined, tools: new Map() });
|
|
127
|
+
}
|
|
128
|
+
#startModelCall(event, spans) {
|
|
129
|
+
const { model, context, options } = event.request;
|
|
130
|
+
const span = this.#tracer.startSpan(`${GEN_AI_OPERATIONS.chat} ${model.id}`, {
|
|
131
|
+
kind: SPAN_KIND_CLIENT,
|
|
132
|
+
attributes: {
|
|
133
|
+
[A.operationName]: GEN_AI_OPERATIONS.chat,
|
|
134
|
+
[A.providerName]: model.provider,
|
|
135
|
+
[A.requestModel]: model.id,
|
|
136
|
+
...(options.maxOutputTokens === undefined ? {} : { [A.requestMaxTokens]: options.maxOutputTokens }),
|
|
137
|
+
...(options.temperature === undefined ? {} : { [A.requestTemperature]: options.temperature }),
|
|
138
|
+
},
|
|
139
|
+
...startTime(event),
|
|
140
|
+
}, spans.childContext);
|
|
141
|
+
// Registered before any content is written, so a throw below leaves a span the run's end can still close.
|
|
142
|
+
this.#replace(spans.model, event);
|
|
143
|
+
spans.model = span;
|
|
144
|
+
if (this.#captureContent) {
|
|
145
|
+
span.setAttribute(A.systemInstructions, systemInstructionsJson(context.system));
|
|
146
|
+
span.setAttribute(A.inputMessages, inputMessagesJson(context.messages));
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
#endModelCall(event, spans) {
|
|
150
|
+
const span = spans.model;
|
|
151
|
+
if (span === undefined)
|
|
152
|
+
return;
|
|
153
|
+
spans.model = undefined;
|
|
154
|
+
const { message } = event;
|
|
155
|
+
// No `gen_ai.response.model`: `message.model` is the model the request named, not the one the provider says
|
|
156
|
+
// answered, so writing it would claim a measurement the gateway does not make.
|
|
157
|
+
try {
|
|
158
|
+
span.setAttribute(A.responseFinishReasons, [FINISH_REASONS[message.stopReason]]);
|
|
159
|
+
setUsage(span, message.usage);
|
|
160
|
+
if (message.error !== undefined) {
|
|
161
|
+
const { kind, status } = message.error;
|
|
162
|
+
failed(span, message.error.message, this.#captureContent, status === undefined ? kind : String(status));
|
|
163
|
+
}
|
|
164
|
+
if (this.#captureContent)
|
|
165
|
+
span.setAttribute(A.outputMessages, outputMessagesJson(message.content));
|
|
166
|
+
}
|
|
167
|
+
finally {
|
|
168
|
+
span.end(millis(event.timestamp));
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
#startTool(event, spans) {
|
|
172
|
+
const span = this.#tracer.startSpan(`${GEN_AI_OPERATIONS.executeTool} ${event.tool}`, {
|
|
173
|
+
kind: SPAN_KIND_INTERNAL,
|
|
174
|
+
attributes: {
|
|
175
|
+
[A.operationName]: GEN_AI_OPERATIONS.executeTool,
|
|
176
|
+
[A.toolName]: event.tool,
|
|
177
|
+
[A.toolCallId]: event.callId,
|
|
178
|
+
[A.toolType]: "function",
|
|
179
|
+
},
|
|
180
|
+
...startTime(event),
|
|
181
|
+
}, spans.childContext);
|
|
182
|
+
this.#replace(spans.tools.get(event.callId), event);
|
|
183
|
+
spans.tools.set(event.callId, span);
|
|
184
|
+
if (this.#captureContent)
|
|
185
|
+
span.setAttribute(A.toolCallArguments, jsonValue(event.input));
|
|
186
|
+
}
|
|
187
|
+
#endTool(event, spans) {
|
|
188
|
+
const span = spans.tools.get(event.callId);
|
|
189
|
+
if (span === undefined)
|
|
190
|
+
return;
|
|
191
|
+
spans.tools.delete(event.callId);
|
|
192
|
+
try {
|
|
193
|
+
if (event.result.isError === true)
|
|
194
|
+
failed(span, "the tool returned an error", true, "tool_error");
|
|
195
|
+
if (this.#captureContent) {
|
|
196
|
+
// A `beforeToolCall` gate may have replaced the model's input; the span records what the tool ran with.
|
|
197
|
+
if ("input" in event)
|
|
198
|
+
span.setAttribute(A.toolCallArguments, jsonValue(event.input));
|
|
199
|
+
span.setAttribute(A.toolCallResult, jsonValue(resultParts(event.result.content)));
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
finally {
|
|
203
|
+
span.end(millis(event.timestamp));
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
/** Ends a span that a new call with the same key is about to displace, so it is exported and not lost. */
|
|
207
|
+
#replace(open, event) {
|
|
208
|
+
if (open !== undefined)
|
|
209
|
+
this.#abort(open, "a new call started before this one finished", millis(event.timestamp));
|
|
210
|
+
}
|
|
211
|
+
/** Marks an unfinished span failed and ends it, even when marking it throws. */
|
|
212
|
+
#abort(span, message, end) {
|
|
213
|
+
try {
|
|
214
|
+
failed(span, message, true);
|
|
215
|
+
}
|
|
216
|
+
finally {
|
|
217
|
+
span.end(end);
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
#endRun(event, spans) {
|
|
221
|
+
const { result } = event;
|
|
222
|
+
this.#close(event.runId, spans, millis(event.timestamp), () => {
|
|
223
|
+
setUsage(spans.agent, result.usage);
|
|
224
|
+
if (result.stopReason === "error") {
|
|
225
|
+
failed(spans.agent, result.error.message, this.#captureContent, result.error.kind);
|
|
226
|
+
}
|
|
227
|
+
});
|
|
228
|
+
}
|
|
229
|
+
/** Ends a run that threw, as `OtelObserver.endRun` describes. */
|
|
230
|
+
abandon(runId, error) {
|
|
231
|
+
const spans = this.#runs.get(runId);
|
|
232
|
+
if (spans === undefined)
|
|
233
|
+
return;
|
|
234
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
235
|
+
this.#close(runId, spans, undefined, () => {
|
|
236
|
+
failed(spans.agent, message, this.#captureContent, errorTypeOf(error));
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* Ends a run's open call spans as failed, marks its own span with `mark`, ends it and forgets the run. The run is
|
|
241
|
+
* forgotten and every span ended even when the tracer throws partway, so a failing tracer leaks nothing. The first
|
|
242
|
+
* error is rethrown after all of them have been tried.
|
|
243
|
+
*/
|
|
244
|
+
#close(runId, spans, end, mark) {
|
|
245
|
+
this.#runs.delete(runId);
|
|
246
|
+
const open = [...(spans.model === undefined ? [] : [spans.model]), ...spans.tools.values()];
|
|
247
|
+
const errors = [];
|
|
248
|
+
const attempt = (step) => {
|
|
249
|
+
try {
|
|
250
|
+
step();
|
|
251
|
+
}
|
|
252
|
+
catch (error) {
|
|
253
|
+
errors.push(error);
|
|
254
|
+
}
|
|
255
|
+
};
|
|
256
|
+
for (const span of open)
|
|
257
|
+
attempt(() => this.#abort(span, "the run ended before this call finished", end));
|
|
258
|
+
attempt(mark);
|
|
259
|
+
attempt(() => spans.agent.end(end));
|
|
260
|
+
if (errors.length > 0)
|
|
261
|
+
throw errors[0];
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* Creates an observer that projects a run's events onto OpenTelemetry GenAI spans. Pass it in `run()`'s
|
|
266
|
+
* `observers`: an observer added later with `run.on()` misses `run_start`, so it records nothing for that run. One
|
|
267
|
+
* observer can serve many runs, because it keeps each run's spans apart by run id.
|
|
268
|
+
*
|
|
269
|
+
* Without `captureContent`, no span holds a prompt, a message, a tool argument, a tool result or an error message.
|
|
270
|
+
*/
|
|
271
|
+
export function otelObserver(options) {
|
|
272
|
+
const projection = new Projection(options);
|
|
273
|
+
return Object.assign((event) => projection.handle(event), {
|
|
274
|
+
async flush() {
|
|
275
|
+
await options.forceFlush?.();
|
|
276
|
+
},
|
|
277
|
+
endRun(runId, error) {
|
|
278
|
+
projection.abandon(runId, error);
|
|
279
|
+
},
|
|
280
|
+
});
|
|
281
|
+
}
|
|
282
|
+
function startTime(event) {
|
|
283
|
+
const time = millis(event.timestamp);
|
|
284
|
+
return time === undefined ? {} : { startTime: time };
|
|
285
|
+
}
|
|
286
|
+
//# sourceMappingURL=observer.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../src/otel/observer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The OpenTelemetry observer: projects a run's events onto GenAI spans. One `invoke_agent` span covers the run, a\n * `chat` span covers each model call and an `execute_tool` span covers each tool call, both children of the run's\n * span. The observer only watches, like every observer: a tracer that throws is reported as a `hook_error` event\n * and never touches the run, and the run's own spans are still ended and forgotten.\n *\n * The observer writes to the tracer the caller passes and nowhere else. It imports nothing from OpenTelemetry, so\n * `@opentelemetry/api` is the caller's dependency, and the trace context it needs comes in as options, not from an\n * ambient context that Workers and other runtimes may not carry across `await`.\n */\nimport { type AssistantMessage, totalInput, type Usage } from \"@buildanagent/gateway\";\nimport type { AgentEvent } from \"../events.js\";\nimport type { Observer } from \"../hooks.js\";\nimport { GEN_AI_ATTRIBUTES as A, GEN_AI_OPERATIONS } from \"./attributes.js\";\nimport { inputMessagesJson, jsonValue, outputMessagesJson, resultParts, systemInstructionsJson } from \"./content.js\";\n\n/** An attribute value a span accepts. */\nexport type AttributeValueLike = string | number | boolean | string[];\n\n/** The `SpanKind` numbers of `@opentelemetry/api`. */\nconst SPAN_KIND_INTERNAL = 0;\nconst SPAN_KIND_CLIENT = 2;\n/** `SpanStatusCode.ERROR` of `@opentelemetry/api`. */\nconst STATUS_ERROR = 2;\n\n/** What `startSpan` takes: the fields of `@opentelemetry/api`'s `SpanOptions` that the observer sets. */\nexport interface SpanOptionsLike {\n /** An OpenTelemetry `SpanKind` number: 0 is internal and 2 is client. */\n readonly kind?: number;\n readonly attributes?: Readonly<Record<string, AttributeValueLike>>;\n /** Start time in milliseconds since the Unix epoch. */\n readonly startTime?: number;\n}\n\n/** The span methods the observer calls. An OpenTelemetry `Span` has all of them. */\nexport interface SpanLike {\n setAttribute(name: string, value: AttributeValueLike): unknown;\n /** `code` 2 is `SpanStatusCode.ERROR`. */\n setStatus?(status: { readonly code: number; readonly message?: string }): unknown;\n /** `endTime` is in milliseconds since the Unix epoch. */\n end(endTime?: number): void;\n}\n\n/** The tracer method the observer calls. An OpenTelemetry `Tracer` has it, so a real tracer fits without a wrapper. */\nexport interface TracerLike {\n startSpan(name: string, options?: SpanOptionsLike, context?: unknown): SpanLike;\n}\n\n/** Options for `otelObserver()`. */\nexport interface OtelObserverOptions {\n /** The tracer that receives the spans. The observer exports nowhere else. */\n readonly tracer: TracerLike;\n /**\n * Whether to record content: the system prompt, the messages of each call, each tool's arguments and result, and\n * the message of each error as its span's status description. Off by default, because content can hold secrets\n * and personal data that a trace backend should not receive. An error's message can quote any of them, so with\n * content off a failed span gets only its error status and `error.type`.\n */\n readonly captureContent?: boolean;\n /** The agent's name: it names the `invoke_agent` span and sets `gen_ai.agent.name`. */\n readonly agentName?: string;\n /**\n * The context the run's span starts in, passed to the tracer as `startSpan`'s third argument: the caller's own\n * span, such as an incoming request's. Every run the observer serves starts in this one context, so when it\n * belongs to one request, create one observer for each request. Left out, the run's span starts in whatever the\n * tracer treats as its default, which for an OpenTelemetry tracer is the active context. A run that a tool starts\n * is another run to the observer, with the same `parentContext`: its span is not a child of the calling tool's\n * span, because events carry no parent run id.\n */\n readonly parentContext?: unknown;\n /**\n * Makes the context a child span starts in from the run's span, so the spans of model and tool calls are children\n * of the run's span in its trace. With OpenTelemetry's API, pass\n * `(span) => trace.setSpan(context.active(), span as Span)`. It is required because the observer imports nothing\n * from OpenTelemetry and so cannot build a context itself.\n */\n readonly childContext: (parent: SpanLike) => unknown;\n /**\n * Flushes the exporter behind the tracer, such as `() => provider.forceFlush()`. `flush()` on the observer calls\n * it, so a Worker can pass `observer.flush()` to `waitUntil` and keep its spans from dying with the request.\n */\n readonly forceFlush?: () => Promise<unknown>;\n}\n\n/** The observer `otelObserver()` returns: an `Observer` that can also flush its exporter and end a run that threw. */\nexport type OtelObserver = Observer & {\n /** Resolves once the exporter behind the tracer has flushed, or at once when `forceFlush` was not passed. */\n flush(): Promise<void>;\n /**\n * Ends the open spans of a run whose `result` rejected, as failed, and forgets the run. A run that throws, for a\n * programmer error such as a tool that returns a malformed result, sends no `run_end`, so without this call its\n * spans are never exported. `error.type` is the error's `code` when it has one, such as an `SdkError`'s, and its\n * `name` otherwise. It ends every span, then rethrows the first error a tracer threw. An unknown run id, or a run\n * that already ended, does nothing.\n */\n endRun(runId: string, error?: unknown): void;\n};\n\ninterface RunSpans {\n readonly agent: SpanLike;\n readonly childContext: unknown;\n model: SpanLike | undefined;\n readonly tools: Map<string, SpanLike>;\n}\n\nfunction millis(timestamp: string): number | undefined {\n const value = Date.parse(timestamp);\n return Number.isNaN(value) ? undefined : value;\n}\n\n/** Marks a span failed. `message` is free text, so it goes in only when `withMessage`, which content capture sets. */\nfunction failed(span: SpanLike, message: string, withMessage: boolean, errorType?: string): void {\n if (errorType !== undefined) span.setAttribute(A.errorType, errorType);\n span.setStatus?.(withMessage ? { code: STATUS_ERROR, message } : { code: STATUS_ERROR });\n}\n\n/** The low-cardinality `error.type` of a thrown value: its `code`, then its `name`, then the conventions' `_OTHER`. */\nfunction errorTypeOf(error: unknown): string {\n if (typeof error === \"object\" && error !== null) {\n const { code, name } = error as { code?: unknown; name?: unknown };\n if (typeof code === \"string\" && code !== \"\") return code;\n if (typeof name === \"string\" && name !== \"\") return name;\n }\n return \"_OTHER\";\n}\n\n/**\n * Writes the usage attributes of one call or one run. Input counts every class, because the conventions' input\n * tokens include cached tokens (D3). A usage the provider did not report writes nothing, since its counts are\n * incomplete and zero would read as a measurement.\n */\nfunction setUsage(span: SpanLike, usage: Usage): void {\n if (usage.unreported === true) return;\n span.setAttribute(A.usageInputTokens, totalInput(usage));\n span.setAttribute(A.usageOutputTokens, usage.output);\n if (usage.cacheRead > 0) span.setAttribute(A.usageCacheReadInputTokens, usage.cacheRead);\n const cacheWrite = usage.cacheWrite[\"5m\"] + usage.cacheWrite[\"1h\"];\n if (cacheWrite > 0) span.setAttribute(A.usageCacheWriteInputTokens, cacheWrite);\n if (usage.reasoning > 0) span.setAttribute(A.usageReasoningOutputTokens, usage.reasoning);\n}\n\n/** The finish reason each stop reason of a model call reports; an aborted call is `interrupted`. */\nconst FINISH_REASONS: Readonly<Record<AssistantMessage[\"stopReason\"], string>> = {\n stop: \"stop\",\n length: \"length\",\n tool_calls: \"tool_calls\",\n error: \"error\",\n aborted: \"interrupted\",\n};\n\n/** Holds the open spans of each run and turns one event at a time into span calls. */\nclass Projection {\n readonly #options: OtelObserverOptions;\n readonly #tracer: TracerLike;\n readonly #captureContent: boolean;\n readonly #runs = new Map<string, RunSpans>();\n\n constructor(options: OtelObserverOptions) {\n this.#options = options;\n this.#tracer = options.tracer;\n this.#captureContent = options.captureContent ?? false;\n }\n\n handle(event: AgentEvent): void {\n if (event.type === \"run_start\") {\n this.#startAgent(event);\n return;\n }\n const spans = this.#runs.get(event.runId);\n if (spans === undefined) return;\n switch (event.type) {\n case \"model_call_start\":\n this.#startModelCall(event, spans);\n break;\n case \"model_call_end\":\n this.#endModelCall(event, spans);\n break;\n case \"tool_call_start\":\n this.#startTool(event, spans);\n break;\n case \"tool_call_end\":\n this.#endTool(event, spans);\n break;\n case \"run_end\":\n this.#endRun(event, spans);\n break;\n default:\n break;\n }\n }\n\n #startAgent(event: Extract<AgentEvent, { type: \"run_start\" }>): void {\n const name = this.#options.agentName;\n const agent = this.#tracer.startSpan(\n name === undefined ? GEN_AI_OPERATIONS.invokeAgent : `${GEN_AI_OPERATIONS.invokeAgent} ${name}`,\n {\n kind: SPAN_KIND_INTERNAL,\n attributes: {\n [A.operationName]: GEN_AI_OPERATIONS.invokeAgent,\n [A.providerName]: event.model.provider,\n [A.requestModel]: event.model.id,\n ...(name === undefined ? {} : { [A.agentName]: name }),\n },\n ...startTime(event),\n },\n this.#options.parentContext,\n );\n let childContext: unknown;\n try {\n childContext = this.#options.childContext(agent);\n } catch (error) {\n // The run's span would otherwise stay open for ever, since the run is never registered to end it.\n agent.end(millis(event.timestamp));\n throw error;\n }\n this.#runs.set(event.runId, { agent, childContext, model: undefined, tools: new Map() });\n }\n\n #startModelCall(event: Extract<AgentEvent, { type: \"model_call_start\" }>, spans: RunSpans): void {\n const { model, context, options } = event.request;\n const span = this.#tracer.startSpan(\n `${GEN_AI_OPERATIONS.chat} ${model.id}`,\n {\n kind: SPAN_KIND_CLIENT,\n attributes: {\n [A.operationName]: GEN_AI_OPERATIONS.chat,\n [A.providerName]: model.provider,\n [A.requestModel]: model.id,\n ...(options.maxOutputTokens === undefined ? {} : { [A.requestMaxTokens]: options.maxOutputTokens }),\n ...(options.temperature === undefined ? {} : { [A.requestTemperature]: options.temperature }),\n },\n ...startTime(event),\n },\n spans.childContext,\n );\n // Registered before any content is written, so a throw below leaves a span the run's end can still close.\n this.#replace(spans.model, event);\n spans.model = span;\n if (this.#captureContent) {\n span.setAttribute(A.systemInstructions, systemInstructionsJson(context.system));\n span.setAttribute(A.inputMessages, inputMessagesJson(context.messages));\n }\n }\n\n #endModelCall(event: Extract<AgentEvent, { type: \"model_call_end\" }>, spans: RunSpans): void {\n const span = spans.model;\n if (span === undefined) return;\n spans.model = undefined;\n const { message } = event;\n // No `gen_ai.response.model`: `message.model` is the model the request named, not the one the provider says\n // answered, so writing it would claim a measurement the gateway does not make.\n try {\n span.setAttribute(A.responseFinishReasons, [FINISH_REASONS[message.stopReason]]);\n setUsage(span, message.usage);\n if (message.error !== undefined) {\n const { kind, status } = message.error;\n failed(span, message.error.message, this.#captureContent, status === undefined ? kind : String(status));\n }\n if (this.#captureContent) span.setAttribute(A.outputMessages, outputMessagesJson(message.content));\n } finally {\n span.end(millis(event.timestamp));\n }\n }\n\n #startTool(event: Extract<AgentEvent, { type: \"tool_call_start\" }>, spans: RunSpans): void {\n const span = this.#tracer.startSpan(\n `${GEN_AI_OPERATIONS.executeTool} ${event.tool}`,\n {\n kind: SPAN_KIND_INTERNAL,\n attributes: {\n [A.operationName]: GEN_AI_OPERATIONS.executeTool,\n [A.toolName]: event.tool,\n [A.toolCallId]: event.callId,\n [A.toolType]: \"function\",\n },\n ...startTime(event),\n },\n spans.childContext,\n );\n this.#replace(spans.tools.get(event.callId), event);\n spans.tools.set(event.callId, span);\n if (this.#captureContent) span.setAttribute(A.toolCallArguments, jsonValue(event.input));\n }\n\n #endTool(event: Extract<AgentEvent, { type: \"tool_call_end\" }>, spans: RunSpans): void {\n const span = spans.tools.get(event.callId);\n if (span === undefined) return;\n spans.tools.delete(event.callId);\n try {\n if (event.result.isError === true) failed(span, \"the tool returned an error\", true, \"tool_error\");\n if (this.#captureContent) {\n // A `beforeToolCall` gate may have replaced the model's input; the span records what the tool ran with.\n if (\"input\" in event) span.setAttribute(A.toolCallArguments, jsonValue(event.input));\n span.setAttribute(A.toolCallResult, jsonValue(resultParts(event.result.content)));\n }\n } finally {\n span.end(millis(event.timestamp));\n }\n }\n\n /** Ends a span that a new call with the same key is about to displace, so it is exported and not lost. */\n #replace(open: SpanLike | undefined, event: AgentEvent): void {\n if (open !== undefined) this.#abort(open, \"a new call started before this one finished\", millis(event.timestamp));\n }\n\n /** Marks an unfinished span failed and ends it, even when marking it throws. */\n #abort(span: SpanLike, message: string, end: number | undefined): void {\n try {\n failed(span, message, true);\n } finally {\n span.end(end);\n }\n }\n\n #endRun(event: Extract<AgentEvent, { type: \"run_end\" }>, spans: RunSpans): void {\n const { result } = event;\n this.#close(event.runId, spans, millis(event.timestamp), () => {\n setUsage(spans.agent, result.usage);\n if (result.stopReason === \"error\") {\n failed(spans.agent, result.error.message, this.#captureContent, result.error.kind);\n }\n });\n }\n\n /** Ends a run that threw, as `OtelObserver.endRun` describes. */\n abandon(runId: string, error: unknown): void {\n const spans = this.#runs.get(runId);\n if (spans === undefined) return;\n const message = error instanceof Error ? error.message : String(error);\n this.#close(runId, spans, undefined, () => {\n failed(spans.agent, message, this.#captureContent, errorTypeOf(error));\n });\n }\n\n /**\n * Ends a run's open call spans as failed, marks its own span with `mark`, ends it and forgets the run. The run is\n * forgotten and every span ended even when the tracer throws partway, so a failing tracer leaks nothing. The first\n * error is rethrown after all of them have been tried.\n */\n #close(runId: string, spans: RunSpans, end: number | undefined, mark: () => void): void {\n this.#runs.delete(runId);\n const open = [...(spans.model === undefined ? [] : [spans.model]), ...spans.tools.values()];\n const errors: unknown[] = [];\n const attempt = (step: () => void): void => {\n try {\n step();\n } catch (error) {\n errors.push(error);\n }\n };\n for (const span of open) attempt(() => this.#abort(span, \"the run ended before this call finished\", end));\n attempt(mark);\n attempt(() => spans.agent.end(end));\n if (errors.length > 0) throw errors[0];\n }\n}\n\n/**\n * Creates an observer that projects a run's events onto OpenTelemetry GenAI spans. Pass it in `run()`'s\n * `observers`: an observer added later with `run.on()` misses `run_start`, so it records nothing for that run. One\n * observer can serve many runs, because it keeps each run's spans apart by run id.\n *\n * Without `captureContent`, no span holds a prompt, a message, a tool argument, a tool result or an error message.\n */\nexport function otelObserver(options: OtelObserverOptions): OtelObserver {\n const projection = new Projection(options);\n return Object.assign((event: AgentEvent) => projection.handle(event), {\n async flush(): Promise<void> {\n await options.forceFlush?.();\n },\n endRun(runId: string, error?: unknown): void {\n projection.abandon(runId, error);\n },\n });\n}\n\nfunction startTime(event: AgentEvent): { readonly startTime?: number } {\n const time = millis(event.timestamp);\n return time === undefined ? {} : { startTime: time };\n}\n"]}
|