@xsai-ext/telemetry 0.4.0-beta.3

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Moeru AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { AttributeValue } from '@opentelemetry/api';
+import { GenerateTextOptions, GenerateTextResult, StreamTextOptions, StreamTextResult } from 'xsai';
+export * from 'xsai';
+
+type TelemetryMetadata = Record<string, AttributeValue>;
+interface TelemetryOptions {
+    metadata?: TelemetryMetadata;
+}
+type WithTelemetry<T> = T & {
+    telemetry?: TelemetryOptions;
+};
+
+/**
+ * @experimental
+ * Generating Text with Telemetry.
+ */
+declare const generateText: (options: WithTelemetry<GenerateTextOptions>) => Promise<GenerateTextResult>;
+
+/**
+ * @experimental
+ * Streaming Text with Telemetry.
+ */
+declare const streamText: (options: WithTelemetry<StreamTextOptions>) => StreamTextResult;
+
+export { type TelemetryMetadata, type TelemetryOptions, type WithTelemetry, generateText, streamText };

package/dist/index.js

@@ -0,0 +1,569 @@
+import { determineStepType, clean, executeTool, trampoline, chat, responseJSON, objCamelToSnake } from 'xsai';
+export * from 'xsai';
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+const metadataAttributes = (metadata = {}) => Object.fromEntries(
+  Object.entries(metadata).map(([key, value]) => [`ai.telemetry.metadata.${key}`, value])
+);
+const idAttributes = () => {
+  const id = crypto.randomUUID();
+  return {
+    "ai.response.id": id,
+    "ai.response.timestamp": (/* @__PURE__ */ new Date()).toISOString(),
+    "gen_ai.response.id": id
+  };
+};
+const commonAttributes = (operationId, model) => ({
+  "ai.model.id": model,
+  // TODO: provider name
+  "ai.model.provider": "xsai",
+  "ai.operationId": operationId,
+  "ai.response.providerMetadata": "{}",
+  "operation.name": operationId
+});
+
+const extractGenerateTextStep = async (options, res) => {
+  const { choices, usage } = res;
+  if (!choices?.length)
+    throw new Error(`No choices returned, response body: ${JSON.stringify(res)}`);
+  const messages = [];
+  const toolCalls = [];
+  const { finish_reason: finishReason, message } = choices[0];
+  const msgToolCalls = message?.tool_calls ?? [];
+  const stepType = determineStepType({
+    finishReason,
+    maxSteps: options.maxSteps ?? 1,
+    stepsLength: options.steps?.length ?? 0,
+    toolCallsLength: msgToolCalls.length
+  });
+  messages.push(clean({
+    ...message,
+    reasoning_content: void 0
+  }));
+  if (finishReason !== "stop" || stepType !== "done") {
+    for (const toolCall of msgToolCalls) {
+      toolCalls.push({
+        args: toolCall.function.arguments,
+        toolCallId: toolCall.id,
+        toolCallType: toolCall.type,
+        toolName: toolCall.function.name
+      });
+    }
+  }
+  return [
+    {
+      finishReason,
+      stepType,
+      text: message.content,
+      toolCalls,
+      usage
+    },
+    {
+      messages,
+      msgToolCalls,
+      reasoningText: message.reasoning_content
+    }
+  ];
+};
+const extractGenerateTextStepPost = async (options, msgToolCalls) => {
+  const inputMessages = structuredClone(options.messages);
+  const outputMessages = [];
+  const toolResults = [];
+  for (const toolCall of msgToolCalls) {
+    const { completionToolResult, message } = await executeTool({
+      abortSignal: options.abortSignal,
+      messages: inputMessages,
+      toolCall,
+      tools: options.tools
+    });
+    toolResults.push(completionToolResult);
+    outputMessages.push(message);
+  }
+  return [
+    toolResults,
+    outputMessages
+  ];
+};
+
+const getTracer = () => trace.getTracer("@xsai-ext/telemetry");
+
+const recordErrorOnSpan = (span, error) => {
+  if (error instanceof Error) {
+    span.recordException({
+      message: error.message,
+      name: error.name,
+      stack: error.stack
+    });
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error.message
+    });
+  } else {
+    span.setStatus({ code: SpanStatusCode.ERROR });
+  }
+};
+const recordSpan = async ({
+  attributes,
+  endWhenDone = true,
+  name,
+  tracer
+}, fn) => tracer.startActiveSpan(name, { attributes }, async (span) => {
+  try {
+    const result = await fn(span);
+    if (endWhenDone)
+      span.end();
+    return result;
+  } catch (error) {
+    try {
+      recordErrorOnSpan(span, error);
+    } finally {
+      span.end();
+    }
+    throw error;
+  }
+});
+const recordSpanSync = ({
+  attributes,
+  endWhenDone = true,
+  name,
+  tracer
+}, fn) => tracer.startActiveSpan(name, { attributes }, (span) => {
+  try {
+    const result = fn(span);
+    if (endWhenDone)
+      span.end();
+    return result;
+  } catch (error) {
+    try {
+      recordErrorOnSpan(span, error);
+    } finally {
+      span.end();
+    }
+    throw error;
+  }
+});
+
+const stringifyTool = ({ function: func, type }) => JSON.stringify({ description: func.description, inputSchema: func.parameters, name: func.name, type });
+
+const wrapTool = (tool, tracer) => ({
+  execute: async (input, options) => recordSpan({
+    attributes: {
+      "ai.operationId": "ai.toolCall",
+      "ai.toolCall.args": JSON.stringify(input),
+      "ai.toolCall.id": options.toolCallId,
+      "ai.toolCall.name": tool.function.name,
+      "operation.name": "ai.toolCall"
+    },
+    name: "ai.toolCall",
+    tracer
+  }, async (span) => {
+    const result = await tool.execute(input, options);
+    span.setAttribute("ai.toolCall.result", JSON.stringify(result));
+    return result;
+  }),
+  function: tool.function,
+  type: tool.type
+});
+
+const generateText = async (options) => {
+  const tracer = getTracer();
+  const rawGenerateText = async (options2) => {
+    const messages = structuredClone(options2.messages);
+    const steps = options2.steps ? structuredClone(options2.steps) : [];
+    const [stepWithoutToolCalls, { messages: msgs1, msgToolCalls, reasoningText }] = await recordSpan({
+      attributes: {
+        ...idAttributes(),
+        ...commonAttributes("ai.generateText.doGenerate", options2.model),
+        ...metadataAttributes(options2.telemetry?.metadata),
+        ...options2.tools != null && options2.tools.length > 0 ? {
+          "ai.prompt.toolChoice": JSON.stringify(options2.toolChoice ?? { type: "auto" }),
+          "ai.prompt.tools": options2.tools.map(stringifyTool)
+        } : {},
+        "ai.prompt.messages": JSON.stringify(messages),
+        "ai.response.model": options2.model,
+        "gen_ai.request.model": options2.model,
+        "gen_ai.response.id": crypto.randomUUID(),
+        "gen_ai.response.model": options2.model,
+        "gen_ai.system": "xsai"
+      },
+      name: "ai.generateText.doGenerate",
+      tracer
+    }, async (span) => {
+      const res = await chat({
+        ...options2,
+        maxSteps: void 0,
+        steps: void 0,
+        stream: false,
+        telemetry: void 0
+      }).then(responseJSON);
+      const [step2, { messages: msgs, msgToolCalls: msgToolCalls2, reasoningText: reasoningText2 }] = await extractGenerateTextStep({
+        ...options2,
+        messages,
+        steps
+      }, res);
+      span.setAttributes({
+        ...step2.text != null && step2.toolCalls.length === 0 ? { "ai.response.text": step2.text } : {},
+        ...step2.toolCalls.length > 0 ? { "ai.response.toolCalls": JSON.stringify(step2.toolCalls) } : {},
+        "ai.response.finishReason": step2.finishReason,
+        "ai.usage.completionTokens": step2.usage.completion_tokens,
+        "ai.usage.promptTokens": step2.usage.prompt_tokens,
+        "gen_ai.response.finish_reasons": [step2.finishReason],
+        "gen_ai.usage.input_tokens": step2.usage.prompt_tokens,
+        "gen_ai.usage.output_tokens": step2.usage.completion_tokens
+      });
+      return [step2, { messages: msgs, msgToolCalls: msgToolCalls2, reasoningText: reasoningText2 }];
+    });
+    const [toolResults, msgs2] = await extractGenerateTextStepPost({
+      ...options2,
+      messages}, msgToolCalls);
+    const step = { ...stepWithoutToolCalls, toolResults };
+    steps.push(step);
+    messages.push(...msgs1, ...msgs2);
+    if (options2.onStepFinish)
+      await options2.onStepFinish(step);
+    if (step.finishReason === "stop" || step.stepType === "done") {
+      return {
+        finishReason: step.finishReason,
+        messages,
+        reasoningText,
+        steps,
+        text: step.text,
+        toolCalls: step.toolCalls,
+        toolResults: step.toolResults,
+        usage: step.usage
+      };
+    } else {
+      return async () => rawGenerateText({
+        ...options2,
+        messages,
+        steps
+      });
+    }
+  };
+  return recordSpan({
+    attributes: {
+      ...commonAttributes("ai.generateText", options.model),
+      ...metadataAttributes(options.telemetry?.metadata),
+      "ai.prompt": JSON.stringify({ messages: options.messages })
+    },
+    name: "ai.generateText",
+    tracer
+  }, async (span) => {
+    const result = await trampoline(async () => rawGenerateText({
+      ...options,
+      tools: options.tools?.map((tool) => wrapTool(tool, tracer))
+    }));
+    span.setAttributes({
+      ...result.toolCalls.length > 0 ? { "ai.response.toolCalls": JSON.stringify(result.toolCalls) } : {},
+      ...result.text != null ? { "ai.response.text": result.text } : {},
+      "ai.response.finishReason": result.finishReason,
+      "ai.usage.completionTokens": result.usage.completion_tokens,
+      "ai.usage.promptTokens": result.usage.prompt_tokens
+    });
+    return result;
+  });
+};
+
+const now = () => globalThis?.performance?.now() ?? Date.now();
+
+const parseChunk = (text) => {
+  if (!text || !text.startsWith("data:"))
+    return [void 0, false];
+  const content = text.slice("data:".length);
+  const data = content.startsWith(" ") ? content.slice(1) : content;
+  if (data === "[DONE]") {
+    return [void 0, true];
+  }
+  if (data.startsWith("{") && data.includes('"error":')) {
+    throw new Error(`Error from server: ${data}`);
+  }
+  const chunk = JSON.parse(data);
+  return [chunk, false];
+};
+const transformChunk = () => {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  return new TransformStream({
+    transform: async (chunk, controller) => {
+      const text = decoder.decode(chunk, { stream: true });
+      buffer += text;
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        try {
+          const [chunk2, isEnd] = parseChunk(line);
+          if (isEnd)
+            break;
+          if (chunk2) {
+            controller.enqueue(chunk2);
+          }
+        } catch (error) {
+          controller.error(error);
+        }
+      }
+    }
+  });
+};
+class DelayedPromise {
+  get promise() {
+    if (this._promise == null) {
+      this._promise = new Promise((resolve, reject) => {
+        if (this.status.type === "resolved") {
+          resolve(this.status.value);
+        } else if (this.status.type === "rejected") {
+          reject(this.status.error);
+        }
+        this._resolve = resolve;
+        this._reject = reject;
+      });
+    }
+    return this._promise;
+  }
+  _promise;
+  _reject;
+  _resolve;
+  status = { type: "pending" };
+  reject(error) {
+    this.status = { error, type: "rejected" };
+    if (this._promise) {
+      this._reject?.(error);
+    }
+  }
+  resolve(value) {
+    this.status = { type: "resolved", value };
+    if (this._promise) {
+      this._resolve?.(value);
+    }
+  }
+}
+
+const streamText = (options) => {
+  const tracer = getTracer();
+  const steps = [];
+  const messages = structuredClone(options.messages);
+  const maxSteps = options.maxSteps ?? 1;
+  let usage;
+  let totalUsage;
+  const resultSteps = new DelayedPromise();
+  const resultMessages = new DelayedPromise();
+  const resultUsage = new DelayedPromise();
+  const resultTotalUsage = new DelayedPromise();
+  let eventCtrl;
+  let textCtrl;
+  const eventStream = new ReadableStream({ start: (controller) => eventCtrl = controller });
+  const textStream = new ReadableStream({ start: (controller) => textCtrl = controller });
+  const pushEvent = (stepEvent) => {
+    eventCtrl?.enqueue(stepEvent);
+    void options.onEvent?.(stepEvent);
+  };
+  const pushStep = (step) => {
+    steps.push(step);
+    void options.onStepFinish?.(step);
+  };
+  const tools = options.tools != null && options.tools.length > 0 ? options.tools.map((tool) => wrapTool(tool, tracer)) : void 0;
+  const doStream = async () => recordSpan({
+    attributes: {
+      ...idAttributes(),
+      ...commonAttributes("ai.streamText.doStream", options.model),
+      ...metadataAttributes(options.telemetry?.metadata),
+      ...tools != null && tools.length > 0 && {
+        "ai.prompt.toolChoice": JSON.stringify(options.toolChoice ?? { type: "auto" }),
+        "ai.prompt.tools": tools.map(stringifyTool)
+      },
+      "ai.prompt.messages": JSON.stringify(options.messages),
+      "ai.response.model": options.model,
+      "gen_ai.request.model": options.model,
+      "gen_ai.response.id": crypto.randomUUID(),
+      "gen_ai.response.model": options.model,
+      "gen_ai.system": "xsai"
+    },
+    name: "ai.streamText.doStream",
+    tracer
+  }, async (span) => {
+    const startMs = now();
+    const { body: stream } = await chat({
+      ...options,
+      maxSteps: void 0,
+      messages,
+      stream: true,
+      streamOptions: options.streamOptions != null ? objCamelToSnake(options.streamOptions) : void 0,
+      tools
+    });
+    const pushUsage = (u) => {
+      usage = u;
+      totalUsage = totalUsage ? {
+        completion_tokens: totalUsage.completion_tokens + u.completion_tokens,
+        prompt_tokens: totalUsage.prompt_tokens + u.prompt_tokens,
+        total_tokens: totalUsage.total_tokens + u.total_tokens
+      } : { ...u };
+    };
+    let text = "";
+    const pushText = (content) => {
+      textCtrl?.enqueue(content);
+      text += content;
+    };
+    const tool_calls = [];
+    const toolCalls = [];
+    const toolResults = [];
+    let finishReason = "other";
+    let firstChunk = true;
+    await stream.pipeThrough(transformChunk()).pipeTo(new WritableStream({
+      abort: (reason) => {
+        eventCtrl?.error(reason);
+        textCtrl?.error(reason);
+      },
+      close: () => {
+      },
+      // eslint-disable-next-line sonarjs/cognitive-complexity
+      write: (chunk) => {
+        if (firstChunk) {
+          const msToFirstChunk = now() - startMs;
+          span.addEvent("ai.stream.firstChunk", {
+            "ai.response.msToFirstChunk": msToFirstChunk
+          });
+          span.setAttributes({
+            "ai.response.msToFirstChunk": msToFirstChunk
+          });
+          firstChunk = false;
+        }
+        if (chunk.usage)
+          pushUsage(chunk.usage);
+        if (chunk.choices == null || chunk.choices.length === 0)
+          return;
+        const choice = chunk.choices[0];
+        if (choice.delta.reasoning_content != null)
+          pushEvent({ text: choice.delta.reasoning_content, type: "reasoning-delta" });
+        if (choice.finish_reason != null)
+          finishReason = choice.finish_reason;
+        if (choice.delta.tool_calls?.length === 0 || choice.delta.tool_calls == null) {
+          if (choice.delta.content != null) {
+            pushEvent({ text: choice.delta.content, type: "text-delta" });
+            pushText(choice.delta.content);
+          } else if (choice.delta.refusal != null) {
+            pushEvent({ error: choice.delta.refusal, type: "error" });
+          } else if (choice.finish_reason != null) {
+            pushEvent({ finishReason: choice.finish_reason, type: "finish", usage });
+          }
+        } else {
+          for (const toolCall of choice.delta.tool_calls) {
+            const { index } = toolCall;
+            if (!tool_calls.at(index)) {
+              tool_calls[index] = toolCall;
+              pushEvent({ toolCallId: toolCall.id, toolName: toolCall.function.name, type: "tool-call-streaming-start" });
+            } else {
+              tool_calls[index].function.arguments += toolCall.function.arguments;
+              pushEvent({ argsTextDelta: toolCall.function.arguments, toolCallId: toolCall.id, toolName: toolCall.function.name, type: "tool-call-delta" });
+            }
+          }
+        }
+      }
+    }));
+    messages.push({ content: text, role: "assistant", tool_calls });
+    if (tool_calls.length !== 0) {
+      for (const toolCall of tool_calls) {
+        const { completionToolCall, completionToolResult, message } = await executeTool({
+          abortSignal: options.abortSignal,
+          messages,
+          toolCall,
+          tools
+        });
+        toolCalls.push(completionToolCall);
+        toolResults.push(completionToolResult);
+        messages.push(message);
+        pushEvent({ ...completionToolCall, type: "tool-call" });
+        pushEvent({ ...completionToolResult, type: "tool-result" });
+      }
+    } else {
+      pushEvent({
+        finishReason,
+        type: "finish",
+        usage
+      });
+    }
+    const step = {
+      finishReason,
+      stepType: determineStepType({ finishReason, maxSteps, stepsLength: steps.length, toolCallsLength: toolCalls.length }),
+      text,
+      toolCalls,
+      toolResults,
+      usage
+    };
+    pushStep(step);
+    const msToFinish = now() - startMs;
+    span.addEvent("ai.stream.finish");
+    span.setAttributes({
+      "ai.response.msToFinish": msToFinish,
+      ...step.toolCalls.length > 0 && { "ai.response.toolCalls": JSON.stringify(step.toolCalls) },
+      "ai.response.finishReason": step.finishReason,
+      "ai.response.text": step.text != null ? step.text : "",
+      "gen_ai.response.finish_reasons": [step.finishReason],
+      ...step.usage && {
+        "ai.response.avgOutputTokensPerSecond": 1e3 * (step.usage.completion_tokens ?? 0) / msToFinish,
+        "ai.usage.inputTokens": step.usage.prompt_tokens,
+        "ai.usage.outputTokens": step.usage.completion_tokens,
+        "ai.usage.totalTokens": step.usage.total_tokens,
+        "gen_ai.usage.input_tokens": step.usage.prompt_tokens,
+        "gen_ai.usage.output_tokens": step.usage.completion_tokens
+      }
+    });
+    if (toolCalls.length !== 0 && steps.length < maxSteps)
+      return async () => doStream();
+  });
+  return recordSpanSync({
+    attributes: {
+      ...commonAttributes("ai.streamText", options.model),
+      ...metadataAttributes(options.telemetry?.metadata),
+      "ai.prompt": JSON.stringify({ messages: options.messages })
+    },
+    endWhenDone: false,
+    name: "ai.streamText",
+    tracer
+  }, (rootSpan) => {
+    void (async () => {
+      try {
+        await trampoline(async () => doStream());
+        eventCtrl?.close();
+        textCtrl?.close();
+      } catch (err) {
+        eventCtrl?.error(err);
+        textCtrl?.error(err);
+        resultSteps.reject(err);
+        resultMessages.reject(err);
+        resultUsage.reject(err);
+        resultTotalUsage.reject(err);
+      } finally {
+        resultSteps.resolve(steps);
+        resultMessages.resolve(messages);
+        resultUsage.resolve(usage);
+        resultTotalUsage.resolve(totalUsage);
+        const finishStep = steps.at(-1);
+        if (finishStep) {
+          rootSpan.setAttributes({
+            ...finishStep.toolCalls.length > 0 && { "ai.response.toolCalls": JSON.stringify(finishStep.toolCalls) },
+            "ai.response.finishReason": finishStep.finishReason,
+            "ai.response.text": finishStep.text != null ? finishStep.text : ""
+          });
+        }
+        if (totalUsage) {
+          rootSpan.setAttributes({
+            "ai.usage.inputTokens": totalUsage.prompt_tokens,
+            "ai.usage.outputTokens": totalUsage.completion_tokens,
+            "ai.usage.totalTokens": totalUsage.total_tokens
+          });
+        }
+        void options.onFinish?.(finishStep);
+        rootSpan.end();
+      }
+    })();
+    return {
+      fullStream: eventStream,
+      messages: resultMessages.promise,
+      steps: resultSteps.promise,
+      textStream,
+      totalUsage: resultTotalUsage.promise,
+      usage: resultUsage.promise
+    };
+  });
+};
+
+export { generateText, streamText };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@xsai-ext/telemetry",
+  "type": "module",
+  "version": "0.4.0-beta.3",
+  "description": "extra-small AI SDK.",
+  "author": "Moeru AI",
+  "license": "MIT",
+  "homepage": "https://xsai.js.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moeru-ai/xsai.git",
+    "directory": "packages-ext/telemetry"
+  },
+  "bugs": "https://github.com/moeru-ai/xsai/issues",
+  "keywords": [
+    "xsai",
+    "openai",
+    "ai"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "xsai": "~0.4.0-beta.3"
+  },
+  "devDependencies": {
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
+    "ai": "^5.0.28",
+    "ollama-ai-provider-v2": "^1.2.1",
+    "zod": "^4.1.5"
+  },
+  "scripts": {
+    "build": "pkgroll",
+    "test": "vitest run --update"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}