Manual Instrumentation for Azure Functions (JavaScript)

If your AI library does not have automatic instrumentation, create spans manually with well-defined names and data attributes. This gives Sentry a complete trace of how long the agent and each model or tool call took, where failures happened, and how the agent produced its final response.

This page describes the minimum span structure and attributes Sentry needs, then covers richer data such as messages, streaming metrics, and custom costs.

For conversations and privacy (setConversationId, setUser, dataCollection), see the Agent Tracing guide.

Span Hierarchy

When instrumenting an agent loop, spans nest like this:

── invoke_agent My Agent          (gen_ai.invoke_agent)
   ├── chat gpt-4o                (gen_ai.chat)         ← 1st LLM call
   ├── execute_tool get_weather   (gen_ai.execute_tool)  ← tool run
   ├── chat gpt-4o                (gen_ai.chat)         ← 2nd LLM call
   └── ...

── invoke_agent My Agent          (gen_ai.invoke_agent)
   ├── chat gpt-4o                (gen_ai.chat)         ← 1st LLM call
   ├── execute_tool get_weather   (gen_ai.execute_tool)  ← tool run
   ├── chat gpt-4o                (gen_ai.chat)         ← 2nd LLM call
   └── ...

gen_ai.invoke_agent covers the complete agent run. Create one gen_ai.chat child for every model request and one gen_ai.execute_tool child for every tool execution. Model and tool spans are siblings: end the model span before running a requested tool so model latency does not include tool execution time.

A gen_ai.chat span can also appear without an agent parent for standalone LLM calls.

Common Attributes

Set these attributes when the span starts, before the model or tool call, so head-based sampling can use them:

• gen_ai.operation.name — required; classifies the span (chat, invoke_agent, execute_tool, …)
• gen_ai.provider.name — e.g. openai, anthropic
• gen_ai.request.model — requested model (pass the raw provider string)
• gen_ai.agent.name / gen_ai.tool.name — when applicable

Use the span names shown in the examples: invoke_agent {agent name}, chat {requested model}, and execute_tool {tool name}. Record accurate start and end times. If an operation fails, set the span status to ERROR and set error.type to a low-cardinality error code or exception class.

Run the agent span in the caller's active trace context. For calls between services, follow the Distributed Tracing guide so the agent run stays connected to the rest of the trace.

To group turns into a Conversation, call setConversationId() with the application's existing chat or session ID. Reuse that ID across turns and traces. If there is no conversation ID, omit it instead of deriving one from a trace or request ID.

Complex values (messages, tool definitions, arrays) must be JSON strings — span attributes only accept primitives.

For manual spans, prompt, response, and tool content is whatever you set on the span. Omit those attributes, or gate them yourself, when you do not want to capture content.

AI Request Span

This span represents a request to an LLM model or service that generates a response based on the input prompt.

const messages = [
  { role: "user", parts: [{ type: "text", content: "Tell me a joke" }] },
];
const tools = [
  { name: "get_weather", description: "Get weather for a city" },
];

await Sentry.startSpan(
  {
    op: "gen_ai.chat",
    name: "chat o3-mini",
    attributes: {
      "gen_ai.operation.name": "chat",
      "gen_ai.request.model": "o3-mini",
      "gen_ai.provider.name": "openai",
      "gen_ai.agent.name": "Weather Agent", // when this call is under an agent
      "gen_ai.system_instructions": "You are a helpful assistant.",
      "gen_ai.tool.definitions": JSON.stringify(tools),
      "gen_ai.input.messages": JSON.stringify(messages),
    },
  },
  async (span) => {
    // Call your model provider; map its response into span attributes below
    const result = await yourLLMClient.chat({
      model: "o3-mini",
      messages,
    });

    span.setAttributes({
      "gen_ai.response.model": result.model,
      "gen_ai.response.id": result.id,
      "gen_ai.output.messages": JSON.stringify([
        {
          role: "assistant",
          parts: [{ type: "text", content: result.text }],
        },
      ]),
      "gen_ai.response.finish_reasons": JSON.stringify([
        result.finishReason,
      ]),
      "gen_ai.usage.input_tokens": result.usage.inputTokens,
      "gen_ai.usage.output_tokens": result.usage.outputTokens,
    });
    // If the provider reports cached tokens, record them as a subset of input tokens
    if (result.usage.cachedInputTokens != null) {
      span.setAttribute(
        "gen_ai.usage.cache_read.input_tokens",
        result.usage.cachedInputTokens,
      );
    }
    return result;
  },
);

const messages = [
  { role: "user", parts: [{ type: "text", content: "Tell me a joke" }] },
];
const tools = [
  { name: "get_weather", description: "Get weather for a city" },
];

await Sentry.startSpan(
  {
    op: "gen_ai.chat",
    name: "chat o3-mini",
    attributes: {
      "gen_ai.operation.name": "chat",
      "gen_ai.request.model": "o3-mini",
      "gen_ai.provider.name": "openai",
      "gen_ai.agent.name": "Weather Agent", // when this call is under an agent
      "gen_ai.system_instructions": "You are a helpful assistant.",
      "gen_ai.tool.definitions": JSON.stringify(tools),
      "gen_ai.input.messages": JSON.stringify(messages),
    },
  },
  async (span) => {
    // Call your model provider; map its response into span attributes below
    const result = await yourLLMClient.chat({
      model: "o3-mini",
      messages,
    });

    span.setAttributes({
      "gen_ai.response.model": result.model,
      "gen_ai.response.id": result.id,
      "gen_ai.output.messages": JSON.stringify([
        {
          role: "assistant",
          parts: [{ type: "text", content: result.text }],
        },
      ]),
      "gen_ai.response.finish_reasons": JSON.stringify([
        result.finishReason,
      ]),
      "gen_ai.usage.input_tokens": result.usage.inputTokens,
      "gen_ai.usage.output_tokens": result.usage.outputTokens,
    });
    // If the provider reports cached tokens, record them as a subset of input tokens
    if (result.usage.cachedInputTokens != null) {
      span.setAttribute(
        "gen_ai.usage.cache_read.input_tokens",
        result.usage.cachedInputTokens,
      );
    }
    return result;
  },
);

Keep system prompts in gen_ai.system_instructions, not inside gen_ai.input.messages. Conversation titles are derived from the first user message in the input messages.

gen_ai.usage.input_tokens is the total input token count, including cache-read and cache-write tokens. gen_ai.usage.output_tokens includes reasoning tokens. Cache and reasoning attributes are subsets of those totals, so don't add them to the totals again. Sentry uses the model identifiers and token totals to calculate model costs.

Message parts

Messages use {role, parts} where each part has a type. Common types:

• text — user-visible content
• reasoning — internal thinking shown as a collapsible row in the conversation detail
• tool_call / tool_call_response — tool invocations linked by a shared id

Unknown part types aren't shown prominently in the conversation detail. They remain available only in the raw span attribute values.

Thinking / reasoning

Models with extended thinking (such as Anthropic's thinking blocks, Gemini's thought, or DeepSeek's reasoning_content) produce internal reasoning that isn't part of the user-visible reply. Represent this as a reasoning part alongside the user-facing text part — don't fold thinking into text.

span.setAttribute(
  "gen_ai.output.messages",
  JSON.stringify([
    {
      role: "assistant",
      parts: [
        { type: "reasoning", content: "6 times 7 is 42." },
        { type: "text", content: "The answer is 42." },
      ],
    },
  ]),
);
span.setAttribute("gen_ai.usage.output_tokens", result.usage.outputTokens);
// Reasoning tokens are a subset of output tokens
span.setAttribute(
  "gen_ai.usage.reasoning.output_tokens",
  result.usage.reasoningTokens,
);

span.setAttribute(
  "gen_ai.output.messages",
  JSON.stringify([
    {
      role: "assistant",
      parts: [
        { type: "reasoning", content: "6 times 7 is 42." },
        { type: "text", content: "The answer is 42." },
      ],
    },
  ]),
);
span.setAttribute("gen_ai.usage.output_tokens", result.usage.outputTokens);
// Reasoning tokens are a subset of output tokens
span.setAttribute(
  "gen_ai.usage.reasoning.output_tokens",
  result.usage.reasoningTokens,
);

When previous thinking is fed back into a multi-turn request, include the same reasoning parts in assistant messages within gen_ai.input.messages.

Tool calls in messages

Link a tool request to its result with the same id:

// Model asked to call a tool
span.setAttribute(
  "gen_ai.output.messages",
  JSON.stringify([
    {
      role: "assistant",
      parts: [
        {
          type: "tool_call",
          id: "call_abc",
          name: "get_weather",
          arguments: { location: "Paris" },
        },
      ],
    },
  ]),
);

// Later chat span: tool result fed back to the model
const inputWithTool = [
  {
    role: "user",
    parts: [{ type: "text", content: "Weather in Paris?" }],
  },
  {
    role: "assistant",
    parts: [
      {
        type: "tool_call",
        id: "call_abc",
        name: "get_weather",
        arguments: { location: "Paris" },
      },
    ],
  },
  {
    role: "tool",
    parts: [
      {
        type: "tool_call_response",
        id: "call_abc",
        name: "get_weather",
        content: '{"temp_c": 18}',
      },
    ],
  },
];
span.setAttribute("gen_ai.input.messages", JSON.stringify(inputWithTool));

// Model asked to call a tool
span.setAttribute(
  "gen_ai.output.messages",
  JSON.stringify([
    {
      role: "assistant",
      parts: [
        {
          type: "tool_call",
          id: "call_abc",
          name: "get_weather",
          arguments: { location: "Paris" },
        },
      ],
    },
  ]),
);

// Later chat span: tool result fed back to the model
const inputWithTool = [
  {
    role: "user",
    parts: [{ type: "text", content: "Weather in Paris?" }],
  },
  {
    role: "assistant",
    parts: [
      {
        type: "tool_call",
        id: "call_abc",
        name: "get_weather",
        arguments: { location: "Paris" },
      },
    ],
  },
  {
    role: "tool",
    parts: [
      {
        type: "tool_call_response",
        id: "call_abc",
        name: "get_weather",
        content: '{"temp_c": 18}',
      },
    ],
  },
];
span.setAttribute("gen_ai.input.messages", JSON.stringify(inputWithTool));

Invoke Agent Span

This span represents the execution of an agent, capturing the full lifecycle from receiving a task to producing a final response.

const inputMessages = [
  {
    role: "user",
    parts: [{ type: "text", content: "What's the weather in Paris?" }],
  },
];

await Sentry.startSpan(
  {
    op: "gen_ai.invoke_agent",
    name: "invoke_agent Weather Agent",
    attributes: {
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.name": "Weather Agent",
      "gen_ai.input.messages": JSON.stringify(inputMessages),
    },
  },
  async (span) => {
    // Model and tool spans created here become children of the agent span.
    const result = await myAgent.run();

    span.setAttribute(
      "gen_ai.output.messages",
      JSON.stringify([
        {
          role: "assistant",
          parts: [{ type: "text", content: String(result.output) }],
        },
      ]),
    );
    return result;
  },
);

const inputMessages = [
  {
    role: "user",
    parts: [{ type: "text", content: "What's the weather in Paris?" }],
  },
];

await Sentry.startSpan(
  {
    op: "gen_ai.invoke_agent",
    name: "invoke_agent Weather Agent",
    attributes: {
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.name": "Weather Agent",
      "gen_ai.input.messages": JSON.stringify(inputMessages),
    },
  },
  async (span) => {
    // Model and tool spans created here become children of the agent span.
    const result = await myAgent.run();

    span.setAttribute(
      "gen_ai.output.messages",
      JSON.stringify([
        {
          role: "assistant",
          parts: [{ type: "text", content: String(result.output) }],
        },
      ]),
    );
    return result;
  },
);

Child gen_ai.chat and gen_ai.execute_tool spans should also set gen_ai.agent.name so model and tool usage can be attributed per agent.

Execute Tool Span

This span represents the execution of a tool or function that was requested by an AI model, including the input arguments and resulting output.

await Sentry.startSpan(
  {
    op: "gen_ai.execute_tool",
    name: "execute_tool get_weather",
    attributes: {
      "gen_ai.operation.name": "execute_tool",
      "gen_ai.agent.name": "Weather Agent",
      "gen_ai.tool.name": "get_weather",
      "gen_ai.tool.description": "Get weather for a city",
      "gen_ai.tool.call.arguments": JSON.stringify({ location: "Paris" }),
    },
  },
  async (span) => {
    try {
      const result = await getWeather({ location: "Paris" });
      span.setAttribute("gen_ai.tool.call.result", JSON.stringify(result));
      return result;
    } catch (error) {
      span.setStatus({ code: 2, message: "internal_error" });
      span.setAttribute(
        "error.type",
        error instanceof Error ? error.constructor.name : "Error",
      );
      throw error;
    }
  },
);

await Sentry.startSpan(
  {
    op: "gen_ai.execute_tool",
    name: "execute_tool get_weather",
    attributes: {
      "gen_ai.operation.name": "execute_tool",
      "gen_ai.agent.name": "Weather Agent",
      "gen_ai.tool.name": "get_weather",
      "gen_ai.tool.description": "Get weather for a city",
      "gen_ai.tool.call.arguments": JSON.stringify({ location: "Paris" }),
    },
  },
  async (span) => {
    try {
      const result = await getWeather({ location: "Paris" });
      span.setAttribute("gen_ai.tool.call.result", JSON.stringify(result));
      return result;
    } catch (error) {
      span.setStatus({ code: 2, message: "internal_error" });
      span.setAttribute(
        "error.type",
        error instanceof Error ? error.constructor.name : "Error",
      );
      throw error;
    }
  },
);

Marking failed tools with an error status populates the Tool Errors widget.

Decision Span

This span represents a decision on generated content against a set of questions, such as grading a model's reply for accuracy or tone. Models like TypeSafe Jev produce these spans.

Sentry identifies a decision by gen_ai.operation.name: "decide". Decisions share the ai_client operation type with ordinary LLM calls, so the operation name is what sets them apart.

const questions = {
  resolves_issue: {
    type: "boolean",
    instructions: "Does the reply resolve the customer's issue?",
  },
  accuracy: {
    type: "score",
    instructions: "Does the reply correctly answer the user's question?",
    // For a score question, criteria is an ordered array; the index is the score.
    criteria: ["incorrect", "partially correct", "correct"],
  },
  tone: {
    type: "choice",
    instructions: "Classify the tone of the reply.",
    // For a choice question, criteria maps each label to its description.
    criteria: {
      friendly: "Warm and helpful",
      neutral: "Plain and factual",
      rude: "Dismissive or hostile",
    },
  },
};

const evaluationInput = [
  {
    type: "evaluation",
    state: "Your refund has been processed and will arrive in 3-5 days.",
    questions,
  },
];

await Sentry.startSpan(
  {
    op: "gen_ai.decide",
    name: "decide typesafe/jev-1.13",
    attributes: {
      "gen_ai.operation.name": "decide",
      "gen_ai.request.model": "typesafe/jev-1.13",
      "gen_ai.provider.name": "typesafe",
      "gen_ai.agent.name": "Support Agent", // when this evaluation runs under an agent
      "gen_ai.input.messages": JSON.stringify(evaluationInput),
    },
  },
  async (span) => {
    // Call your evaluator; map its response into span attributes below
    const result = await yourEvaluator.evaluate({
      state: evaluationInput[0].state,
      questions,
    });

    span.setAttributes({
      "gen_ai.response.model": result.model, // e.g. "typesafe/jev-1.13-20260917"
      "gen_ai.output.messages": JSON.stringify([
        {
          type: "evaluation",
          answers: {
            resolves_issue: { type: "boolean", probability: 0.98 },
            accuracy: { type: "score", score: 2, confidence: 0.91 },
            tone: {
              type: "choice",
              choice: "friendly",
              probabilities: { friendly: 0.87, neutral: 0.1, rude: 0.03 },
              confidence: 0.87,
            },
          },
        },
      ]),
      "gen_ai.usage.input_tokens": result.usage.inputTokens,
      "gen_ai.usage.output_tokens": result.usage.outputTokens,
    });
    return result;
  },
);

const questions = {
  resolves_issue: {
    type: "boolean",
    instructions: "Does the reply resolve the customer's issue?",
  },
  accuracy: {
    type: "score",
    instructions: "Does the reply correctly answer the user's question?",
    // For a score question, criteria is an ordered array; the index is the score.
    criteria: ["incorrect", "partially correct", "correct"],
  },
  tone: {
    type: "choice",
    instructions: "Classify the tone of the reply.",
    // For a choice question, criteria maps each label to its description.
    criteria: {
      friendly: "Warm and helpful",
      neutral: "Plain and factual",
      rude: "Dismissive or hostile",
    },
  },
};

const evaluationInput = [
  {
    type: "evaluation",
    state: "Your refund has been processed and will arrive in 3-5 days.",
    questions,
  },
];

await Sentry.startSpan(
  {
    op: "gen_ai.decide",
    name: "decide typesafe/jev-1.13",
    attributes: {
      "gen_ai.operation.name": "decide",
      "gen_ai.request.model": "typesafe/jev-1.13",
      "gen_ai.provider.name": "typesafe",
      "gen_ai.agent.name": "Support Agent", // when this evaluation runs under an agent
      "gen_ai.input.messages": JSON.stringify(evaluationInput),
    },
  },
  async (span) => {
    // Call your evaluator; map its response into span attributes below
    const result = await yourEvaluator.evaluate({
      state: evaluationInput[0].state,
      questions,
    });

    span.setAttributes({
      "gen_ai.response.model": result.model, // e.g. "typesafe/jev-1.13-20260917"
      "gen_ai.output.messages": JSON.stringify([
        {
          type: "evaluation",
          answers: {
            resolves_issue: { type: "boolean", probability: 0.98 },
            accuracy: { type: "score", score: 2, confidence: 0.91 },
            tone: {
              type: "choice",
              choice: "friendly",
              probabilities: { friendly: 0.87, neutral: 0.1, rude: 0.03 },
              confidence: 0.87,
            },
          },
        },
      ]),
      "gen_ai.usage.input_tokens": result.usage.inputTokens,
      "gen_ai.usage.output_tokens": result.usage.outputTokens,
    });
    return result;
  },
);

The input is a single {type: "evaluation", state, questions} object. state is the text being evaluated, and each entry in questions describes one question. The output is a single {type: "evaluation", answers} object keyed by those same question names. Answers come in a few types (boolean, noul, score, and choice), each with its own fields. See the attributes below for the full shape.

Pass the raw provider model string in gen_ai.request.model (and gen_ai.response.model) so Sentry can resolve the model icon and any model costs.

Memory Span

This span represents a read from, write to, or management operation against an agent's persistent memory store, such as retrieving relevant memories before a model call or saving new ones after it.

Sentry identifies a memory operation by the gen_ai.memory.client span op. The specific action goes in gen_ai.operation.name, and the span name matches it.

const query = "user dietary preferences";

await Sentry.startSpan(
  {
    op: "gen_ai.memory.client",
    name: "search_memory",
    attributes: {
      "gen_ai.operation.name": "search_memory",
      "gen_ai.memory.store.id": "user-preferences-store",
      "gen_ai.agent.name": "Support Agent", // when the operation runs under an agent
      "gen_ai.memory.query.text": query, // opt-in; may contain sensitive data
    },
  },
  async (span) => {
    const records = await memoryStore.search(query);

    span.setAttributes({
      "gen_ai.memory.record.count": records.length,
      // opt-in; may contain sensitive data
      "gen_ai.memory.records": JSON.stringify(
        records.map((record) => ({
          id: record.id,
          content: record.content,
          score: record.score,
        })),
      ),
    });
    return records;
  },
);

const query = "user dietary preferences";

await Sentry.startSpan(
  {
    op: "gen_ai.memory.client",
    name: "search_memory",
    attributes: {
      "gen_ai.operation.name": "search_memory",
      "gen_ai.memory.store.id": "user-preferences-store",
      "gen_ai.agent.name": "Support Agent", // when the operation runs under an agent
      "gen_ai.memory.query.text": query, // opt-in; may contain sensitive data
    },
  },
  async (span) => {
    const records = await memoryStore.search(query);

    span.setAttributes({
      "gen_ai.memory.record.count": records.length,
      // opt-in; may contain sensitive data
      "gen_ai.memory.records": JSON.stringify(
        records.map((record) => ({
          id: record.id,
          content: record.content,
          score: record.score,
        })),
      ),
    });
    return records;
  },
);

Set gen_ai.operation.name to the action: search_memory to retrieve records, create_memory / update_memory / upsert_memory to write them, delete_memory to remove them, and create_memory_store / delete_memory_store to manage the store itself.

gen_ai.memory.query.text applies only to search_memory. When an operation targets a single record, set gen_ai.memory.record.id; on delete_memory, omitting it can mean every record in the store is removed. gen_ai.memory.record.count is the number of records returned, written, or deleted.

gen_ai.memory.query.text and gen_ai.memory.records can carry user data and PII, so they are opt-in. Omit them, or gate them yourself, when you don't want that content in Sentry.

Streaming Responses

When the model streams tokens, keep the span open until the stream finishes (including when you yield chunks to the client). Set response attributes when you have the final usage and text:

• gen_ai.response.streaming — true
• gen_ai.response.time_to_first_chunk — seconds until the first chunk
• gen_ai.response.tokens_per_second — output throughput, if you can measure it
• gen_ai.output.messages, token usage, and gen_ai.response.model — same as a non-streaming call, once the stream completes

Use Sentry.startInactiveSpan if the span outlives the function that starts the stream, and Sentry.withActiveSpan when work within the stream needs the model span as its parent. End the span when the stream completes or fails. See Streamed Spans for span lifecycle patterns.

Token Usage and Cost Gotchas

When manually setting token attributes, be aware of how Sentry uses them to calculate model costs.

Cached and reasoning tokens are subsets, not separate counts. gen_ai.usage.input_tokens is the total input token count that already includes any cached tokens. Similarly, gen_ai.usage.output_tokens already includes reasoning tokens. Sentry subtracts the cached/reasoning counts from the totals to compute the "raw" portion, so reporting them incorrectly can produce wrong or negative costs.

For example, say your LLM call uses 100 input tokens total, 90 of which were served from cache. Using a standard rate of $0.01 per token and a cached rate of $0.001 per token:

Correct — input_tokens is the total (includes cached):

• gen_ai.usage.input_tokens = 100
• gen_ai.usage.cache_read.input_tokens = 90
• Sentry calculates: (100 - 90) × $0.01 + 90 × $0.001 = $0.10 + $0.09 = $0.19 ✓

Wrong — input_tokens set to only the non-cached tokens, making cached larger than total:

• gen_ai.usage.input_tokens = 10
• gen_ai.usage.cache_read.input_tokens = 90
• Sentry calculates: (10 - 90) × $0.01 + 90 × $0.001 = −$0.80 + $0.09 = −$0.71

Because gen_ai.usage.cache_read.input_tokens (90) is larger than gen_ai.usage.input_tokens (10), the subtraction goes negative, resulting in a negative total cost.

The same applies to gen_ai.usage.output_tokens and gen_ai.usage.reasoning.output_tokens.

By default, Sentry derives model cost from the model name and token counts. Pass the raw provider model string unchanged so pricing can resolve. If your provider reports costs or you use custom pricing, see Send Custom Costs.