Browser AI Tracing
Learn how to manually instrument AI agents in browser applications.
With Sentry Agent Tracing, you can monitor and debug your AI systems with full-stack context. You'll be able to track key insights like token usage, latency, tool usage, and error rates. Agent Tracing data will be fully connected to your other Sentry data like logs, errors, and traces.
Before setting up Agent Tracing, ensure you have tracing enabled in your Sentry configuration.
Browser applications require manual instrumentation. Unlike Node.js applications, the JavaScript SDK does not provide automatic instrumentation for AI libraries in the browser.
For supported AI libraries, Sentry provides manual instrumentation helpers that simplify span creation. These helpers handle the complexity of creating properly structured spans with the correct attributes.
Supported libraries:
Each integration page includes a manual-instrumentation example with options like recordInputs and recordOutputs.
import * as Sentry from "___SDK_PACKAGE___";
import OpenAI from "openai";
const client = Sentry.instrumentOpenAiClient(
new OpenAI({ apiKey: "...", dangerouslyAllowBrowser: true }),
{
recordInputs: true,
recordOutputs: true,
},
);
// All calls are now instrumented
const response = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello!" }],
});
import * as Sentry from "___SDK_PACKAGE___";
import OpenAI from "openai";
const client = Sentry.instrumentOpenAiClient(
new OpenAI({ apiKey: "...", dangerouslyAllowBrowser: true }),
{
recordInputs: true,
recordOutputs: true,
},
);
// All calls are now instrumented
const response = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello!" }],
});
If you're using a library that Sentry doesn't provide helpers for, you can manually create spans. For your data to show up in the AI Agents Dashboards, spans must have well-defined names and data attributes.
This span represents the execution of an AI agent, capturing the full lifecycle from receiving a task to producing a final response.
Key attributes:
gen_ai.agent.name— The agent's name (e.g., "Weather Agent")gen_ai.request.model— The underlying model usedgen_ai.output.messages— The agent's final outputgen_ai.usage.input_tokens/output_tokens— Total token counts
// Example agent implementation for demonstration
const myAgent = {
name: "Weather Agent",
modelProvider: "openai",
model: "gpt-4o-mini",
async run() {
// Agent implementation
return {
output: "The weather in Paris is sunny",
usage: {
inputTokens: 15,
outputTokens: 8,
},
};
},
};
Sentry.startSpan(
{
op: "gen_ai.invoke_agent",
name: `invoke_agent ${myAgent.name}`,
attributes: {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.request.model": myAgent.model,
"gen_ai.agent.name": myAgent.name,
},
},
async (span) => {
// run the agent
const result = await myAgent.run();
// set agent response
span.setAttribute(
"gen_ai.output.messages",
JSON.stringify([
{
role: "assistant",
parts: [{ type: "text", content: result.output }],
},
]),
);
// set token usage
span.setAttribute(
"gen_ai.usage.input_tokens",
result.usage.inputTokens,
);
span.setAttribute(
"gen_ai.usage.output_tokens",
result.usage.outputTokens,
);
return result;
},
);
// Example agent implementation for demonstration
const myAgent = {
name: "Weather Agent",
modelProvider: "openai",
model: "gpt-4o-mini",
async run() {
// Agent implementation
return {
output: "The weather in Paris is sunny",
usage: {
inputTokens: 15,
outputTokens: 8,
},
};
},
};
Sentry.startSpan(
{
op: "gen_ai.invoke_agent",
name: `invoke_agent ${myAgent.name}`,
attributes: {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.request.model": myAgent.model,
"gen_ai.agent.name": myAgent.name,
},
},
async (span) => {
// run the agent
const result = await myAgent.run();
// set agent response
span.setAttribute(
"gen_ai.output.messages",
JSON.stringify([
{
role: "assistant",
parts: [{ type: "text", content: result.output }],
},
]),
);
// set token usage
span.setAttribute(
"gen_ai.usage.input_tokens",
result.usage.inputTokens,
);
span.setAttribute(
"gen_ai.usage.output_tokens",
result.usage.outputTokens,
);
return result;
},
);
This span represents a chat or completion request to an LLM, capturing the messages, model configuration, and response.
Key attributes:
gen_ai.request.model— The model name (required)gen_ai.input.messages— Chat messages sent to the LLMgen_ai.request.max_tokens— Token limit for the responsegen_ai.output.messages— The model's response
// Example AI implementation for demonstration
const myAi = {
modelProvider: "openai",
model: "gpt-4o-mini",
modelConfig: {
temperature: 0.1,
presencePenalty: 0.5,
},
async createMessage(messages, maxTokens) {
// AI implementation
return {
output:
"Here's a joke: Why don't scientists trust atoms? Because they make up everything!",
usage: {
inputTokens: 12,
outputTokens: 24,
},
};
},
};
Sentry.startSpan(
{
op: "gen_ai.chat",
name: `chat ${myAi.model}`,
attributes: {
"gen_ai.operation.name": "chat",
"gen_ai.request.model": myAi.model,
},
},
async (span) => {
// set up messages for LLM
const maxTokens = 1024;
const messages = [
{
role: "user",
parts: [{ type: "text", content: "Tell me a joke" }],
},
];
// set chat request data
span.setAttribute("gen_ai.input.messages", JSON.stringify(messages));
span.setAttribute("gen_ai.request.max_tokens", maxTokens);
span.setAttribute(
"gen_ai.request.temperature",
myAi.modelConfig.temperature,
);
// ask the LLM
const result = await myAi.createMessage(messages, maxTokens);
// set response
span.setAttribute(
"gen_ai.output.messages",
JSON.stringify([
{
role: "assistant",
parts: [{ type: "text", content: result.output }],
},
]),
);
// set token usage
span.setAttribute(
"gen_ai.usage.input_tokens",
result.usage.inputTokens,
);
span.setAttribute(
"gen_ai.usage.output_tokens",
result.usage.outputTokens,
);
return result;
},
);
// Example AI implementation for demonstration
const myAi = {
modelProvider: "openai",
model: "gpt-4o-mini",
modelConfig: {
temperature: 0.1,
presencePenalty: 0.5,
},
async createMessage(messages, maxTokens) {
// AI implementation
return {
output:
"Here's a joke: Why don't scientists trust atoms? Because they make up everything!",
usage: {
inputTokens: 12,
outputTokens: 24,
},
};
},
};
Sentry.startSpan(
{
op: "gen_ai.chat",
name: `chat ${myAi.model}`,
attributes: {
"gen_ai.operation.name": "chat",
"gen_ai.request.model": myAi.model,
},
},
async (span) => {
// set up messages for LLM
const maxTokens = 1024;
const messages = [
{
role: "user",
parts: [{ type: "text", content: "Tell me a joke" }],
},
];
// set chat request data
span.setAttribute("gen_ai.input.messages", JSON.stringify(messages));
span.setAttribute("gen_ai.request.max_tokens", maxTokens);
span.setAttribute(
"gen_ai.request.temperature",
myAi.modelConfig.temperature,
);
// ask the LLM
const result = await myAi.createMessage(messages, maxTokens);
// set response
span.setAttribute(
"gen_ai.output.messages",
JSON.stringify([
{
role: "assistant",
parts: [{ type: "text", content: result.output }],
},
]),
);
// set token usage
span.setAttribute(
"gen_ai.usage.input_tokens",
result.usage.inputTokens,
);
span.setAttribute(
"gen_ai.usage.output_tokens",
result.usage.outputTokens,
);
return result;
},
);
This span represents the execution of a tool or function that was requested by an AI model, including the input arguments and resulting output.
Key attributes:
gen_ai.tool.name— The tool's name (e.g., "random_number")gen_ai.tool.description— Description of what the tool doesgen_ai.tool.call.arguments— The arguments passed to the toolgen_ai.tool.call.result— The tool's return value
// Example AI implementation for demonstration
const myAi = {
modelProvider: "openai",
model: "gpt-4o-mini",
async createMessage(messages, maxTokens) {
// AI implementation that returns tool calls
return {
toolCalls: [
{
name: "random_number",
description: "Generate a random number",
arguments: { max: 10 },
},
],
};
},
};
const messages = [
{ role: "user", content: "Generate a random number between 0 and 10" },
];
// First, make the AI call
const result = await Sentry.startSpan(
{ op: "gen_ai.chat", name: `chat ${myAi.model}` },
() => myAi.createMessage(messages, 1024),
);
// Check if we should call a tool
if (result.toolCalls && result.toolCalls.length > 0) {
const tool = result.toolCalls[0];
await Sentry.startSpan(
{
op: "gen_ai.execute_tool",
name: `execute_tool ${tool.name}`,
attributes: {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.type": "function",
"gen_ai.tool.name": tool.name,
"gen_ai.tool.description": tool.description,
"gen_ai.tool.call.arguments": JSON.stringify(tool.arguments),
},
},
async (span) => {
// run tool (example implementation)
const toolResult = Math.floor(Math.random() * tool.arguments.max);
// set tool result
span.setAttribute("gen_ai.tool.call.result", String(toolResult));
return toolResult;
},
);
}
// Example AI implementation for demonstration
const myAi = {
modelProvider: "openai",
model: "gpt-4o-mini",
async createMessage(messages, maxTokens) {
// AI implementation that returns tool calls
return {
toolCalls: [
{
name: "random_number",
description: "Generate a random number",
arguments: { max: 10 },
},
],
};
},
};
const messages = [
{ role: "user", content: "Generate a random number between 0 and 10" },
];
// First, make the AI call
const result = await Sentry.startSpan(
{ op: "gen_ai.chat", name: `chat ${myAi.model}` },
() => myAi.createMessage(messages, 1024),
);
// Check if we should call a tool
if (result.toolCalls && result.toolCalls.length > 0) {
const tool = result.toolCalls[0];
await Sentry.startSpan(
{
op: "gen_ai.execute_tool",
name: `execute_tool ${tool.name}`,
attributes: {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.type": "function",
"gen_ai.tool.name": tool.name,
"gen_ai.tool.description": tool.description,
"gen_ai.tool.call.arguments": JSON.stringify(tool.arguments),
},
},
async (span) => {
// run tool (example implementation)
const toolResult = Math.floor(Math.random() * tool.arguments.max);
// set tool result
span.setAttribute("gen_ai.tool.call.result", String(toolResult));
return toolResult;
},
);
}
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").