Traces

The browser knows when a response started, reached its first token, and settled. The server knows the model steps, tool work, and usage inside that response. Assistant Cloud accepts OpenTelemetry spans from the server and joins them with the browser run report when both carry the same trace id.

Server spans also stand on their own. A trace can create a run, price its model work, and appear in Runs and Models even when no browser report exists.

Set up the AI SDK exporter

npm i assistant-cloud @vercel/otel @ai-sdk/otel @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http

import { registerOTel } from "@vercel/otel";
import {
  createAssistantCloudSpanProcessor,
  createAssistantCloudTraceExporter,
} from "assistant-cloud/telemetry";

export function register() {
  registerOTel({
    serviceName: "my-app",
    spanProcessors: [
      "auto",
      createAssistantCloudSpanProcessor(
        createAssistantCloudTraceExporter({
          apiKey: process.env.ASSISTANT_API_KEY!,
        }),
      ),
    ],
  });
}

import { OpenTelemetry } from "@ai-sdk/otel";
import { openai } from "@ai-sdk/openai";
import { convertToModelMessages, streamText } from "ai";
import { withAssistantCloudTraceMetadata } from "assistant-cloud/telemetry";

export async function POST(request: Request) {
  const { messages } = await request.json();
  const result = streamText({
    model: openai("gpt-6-luna"),
    messages: await convertToModelMessages(messages),
    telemetry: { integrations: [new OpenTelemetry()] },
  });

  return result.toUIMessageStreamResponse({
    messageMetadata: withAssistantCloudTraceMetadata(),
  });
}

The trace receiver

POST /v1/traces is an OTLP over HTTP receiver. It requires a project API key. A request with a browser token returns { "error": "This endpoint requires an API key" }; a missing authorization header returns 401.

An all accepted export returns {}. An export with rejected spans still returns 200 and identifies the partial success:

{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "<joined receiver errors>"
  }
}

When the receiver has no individual error text, errorMessage is "<n> spans were rejected". Check partialSuccess in the response: a 200 does not mean every span became a run.

How spans become runs

The receiver recognizes a span when gen_ai.operation.name, or the first word of its name, is chat, text_completion, embeddings, execute_tool, invoke_agent, or create_agent. All other spans are rejected. A trace can contain at most 500 accepted spans; each later span is rejected with Trace <trace id> exceeds the 500 span limit in partialSuccess.

Attributes the receiver reads

The receiver reads these OpenTelemetry resource and span attributes. Unmapped attributes are retained on the span and run instead of being discarded.

An error status on a root span makes the run an error. If gen_ai.conversation.id does not name a project thread, the receiver keeps the submitted id in attributes["gen_ai.conversation.id"] instead of linking the run. Every OTLP created run also carries attributes["telemetry.source"] = "otlp".

Run and span attributes are each capped at 16,384 bytes. When they exceed that cap, the receiver drops the largest entries first and adds truncated: true. This cap is independent of the 500 span trace cap.

Stable ids and reexports

A trace root's id is deterministic: run_<first 24 hexadecimal characters of sha256(projectId + traceId + rootSpanId)>. Exporting the same root again updates that run instead of creating a second run. Each span is also upserted by its trace id and span id, so the new export replaces its stored span fields.

The receiver negates and reapplies the affected daily rollup after an update, so a reexport changes aggregates rather than adding a duplicate.

Merge a server trace with a client report

The report and trace must have the same valid W3C trace id in one project. Either order works.

The result is one run with a trace waterfall. Open it from the Runs page to inspect the model steps, tools, sampling calls, timing, usage, and the selected span's arguments or prompt.

Track sub agent model work

A tool that calls another model is a sampling call. With server tracing enabled, a chat span nested under a tool span is attached automatically. Without server tracing, collect calls while the tool runs and send them through message metadata.

import { convertToModelMessages, streamText, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import {
  createSamplingCollector,
  type SamplingCallData,
} from "assistant-cloud";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const samplingCalls: Record<string, SamplingCallData[]> = {};

  const result = streamText({
    model: openai("gpt-6-luna"),
    messages: await convertToModelMessages(messages),
    tools: {
      delegate: tool({
        inputSchema: z.object({ task: z.string() }),
        execute: async ({ task }, { toolCallId }) => {
          const collector = createSamplingCollector();
          const answer = await runSubAgent(task, {
            onSamplingCall: collector.collect,
          });
          samplingCalls[toolCallId] = collector.getCalls();
          return answer;
        },
      }),
    },
  });

  return result.toUIMessageStreamResponse({
    messageMetadata: ({ part }) => {
      if (part.type === "finish") {
        return { usage: part.totalUsage, samplingCalls };
      }
      return undefined;
    },
  });
}

SamplingCallData accepts optional model_id, input_tokens, output_tokens, reasoning_tokens, cached_input_tokens, and duration_ms. The AI SDK extractor uses samplingCalls[toolCallId] for the matching tool call. For an MCP sampling handler, wrap it with wrapSamplingHandler(handler, collector.collect). The wrapper measures duration, reads current and legacy usage names, resolves the model from the response or model preference hint, and does not let a failing collection callback break the sampling request.

Connect an external trace viewer

Settings › Telemetry accepts an optional trace link template of up to 512 characters. Leave it empty, or include the literal {trace_id}, for example https://cloud.langfuse.com/project/abc/traces/{trace_id}. The dashboard substitutes the trace id in the run detail view. A template without {trace_id} cannot be saved.

The docs chat as a working pattern

The documentation chat registers a service named assistant-ui-docs. When a project API key is available, it creates the Assistant Cloud exporter with that key and an optional backend URL, then includes an Assistant Cloud span processor alongside the automatic processor and its other telemetry exporters. It uses a local AI span filter rather than the package default.

Its chat route wraps its existing metadata callback with withAssistantCloudTraceMetadata. It returns modelId when a step finishes and usage when the response finishes. That pair supplies the browser report, while the exporter supplies the server span tree.

Configure another producer

Any OpenTelemetry producer can export to the receiver. Send its OTLP HTTP export to https://backend.assistant-api.com/v1/traces with the project API key, emit recognized GenAI spans, and add gen_ai.conversation.id when the work belongs to a cloud thread.

exporters:
  otlphttp/assistant-cloud:
    endpoint: https://backend.assistant-api.com
    headers:
      Authorization: "Bearer ${env:ASSISTANT_API_KEY}"

The collector configuration supplies the exporter destination and credentials. The producer still needs the recognized operation, model, provider, usage, thread, user, and deployment attributes described above.

Troubleshooting