diff --git a/docs/platforms/javascript/common/ai-agent-monitoring-browser/index.mdx b/docs/platforms/javascript/common/ai-agent-monitoring-browser/index.mdx index d79059a9999cee..133c30a3fd0375 100644 --- a/docs/platforms/javascript/common/ai-agent-monitoring-browser/index.mdx +++ b/docs/platforms/javascript/common/ai-agent-monitoring-browser/index.mdx @@ -55,361 +55,4 @@ Before setting up AI Agent Monitoring, ensure you have OpenAI -- Anthropic -- Google Gen AI SDK -- LangChain -- LangGraph - -Each integration page includes browser-specific examples with options like `recordInputs` and `recordOutputs`. - - - - -```javascript -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!" }], -}); -``` - - - - - -## Manual Span Creation - -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 [AI Agents Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/ai/agents/), spans must have well-defined names and data attributes. - -### Invoke Agent Span - - - - - -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 used -- `gen_ai.response.text` — The agent's final output -- `gen_ai.usage.input_tokens` / `output_tokens` — Total token counts - - - - -```javascript -// 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.response.text", JSON.stringify([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; - } -); -``` - - - - - - - - - -### AI Client Span - - - - - -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.request.messages` — Chat messages sent to the LLM -- `gen_ai.request.max_tokens` — Token limit for the response -- `gen_ai.response.text` — The model's response - - - - -```javascript -// 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", content: "Tell me a joke" }]; - - // set chat request data - span.setAttribute("gen_ai.request.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.response.text", JSON.stringify([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; - } -); -``` - - - - - - - - - -### 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. - -**Key attributes:** -- `gen_ai.tool.name` — The tool's name (e.g., "random_number") -- `gen_ai.tool.description` — Description of what the tool does -- `gen_ai.tool.input` — The arguments passed to the tool -- `gen_ai.tool.output` — The tool's return value - - - - -```javascript -// 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.request.model": myAi.model, - "gen_ai.tool.type": "function", - "gen_ai.tool.name": tool.name, - "gen_ai.tool.description": tool.description, - "gen_ai.tool.input": 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.output", String(toolResult)); - - return toolResult; - } - ); -} -``` - - - - - - - - - -### Handoff Span - - - - - -This span marks the transition of control from one agent to another, typically when the current agent determines another agent is better suited to handle the task. - -**Requirements:** -- `op` must be `"gen_ai.handoff"` -- `name` should follow the pattern `"handoff from {source} to {target}"` -- All [Common Span Attributes](#common-span-attributes) should be set - -The handoff span itself has no body — it just marks the transition point before the target agent starts. - - - - -```javascript -// Example agent implementations for demonstration -const myAgent = { - name: "Weather Agent", - modelProvider: "openai", - model: "gpt-4o-mini", - async run() { - // Agent implementation - return { - handoffTo: "Travel Agent", - output: "I need to handoff to the travel agent for booking recommendations", - }; - }, -}; - -const otherAgent = { - name: "Travel Agent", - modelProvider: "openai", - model: "gpt-4o-mini", - async run() { - // Other agent implementation - return { output: "Here are some travel recommendations..." }; - }, -}; - -// First agent execution -const result = await Sentry.startSpan( - { op: "gen_ai.invoke_agent", name: `invoke_agent ${myAgent.name}` }, - () => myAgent.run() -); - -// Check if we should handoff to another agent -if (result.handoffTo) { - // Create handoff span - await Sentry.startSpan( - { - op: "gen_ai.handoff", - name: `handoff from ${myAgent.name} to ${otherAgent.name}`, - attributes: { - "gen_ai.request.model": myAgent.model, - }, - }, - () => { - // the handoff span just marks the handoff - // no actual work is done here - } - ); - - // Execute the other agent - await Sentry.startSpan( - { op: "gen_ai.invoke_agent", name: `invoke_agent ${otherAgent.name}` }, - () => otherAgent.run() - ); -} -``` - - - - - -## Common Span Attributes - - + diff --git a/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx index 949458f207c8be..96bb6ee0a1cc69 100644 --- a/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx @@ -32,6 +32,7 @@ supported: - javascript.solid - javascript.ember - javascript.gatsby + - javascript.react-native --- diff --git a/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx index 9e1370dbaa3e51..30310619c5832a 100644 --- a/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx @@ -32,6 +32,7 @@ supported: - javascript.solid - javascript.ember - javascript.gatsby + - javascript.react-native --- diff --git a/docs/platforms/javascript/common/configuration/integrations/langchain.mdx b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx index 63903dacca66f1..77a087a2973527 100644 --- a/docs/platforms/javascript/common/configuration/integrations/langchain.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx @@ -32,6 +32,7 @@ supported: - javascript.solid - javascript.ember - javascript.gatsby + - javascript.react-native --- diff --git a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx index 9c8e24665e84ab..1d4503c459689c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx @@ -32,6 +32,7 @@ supported: - javascript.solid - javascript.ember - javascript.gatsby + - javascript.react-native --- diff --git a/docs/platforms/javascript/common/configuration/integrations/openai.mdx b/docs/platforms/javascript/common/configuration/integrations/openai.mdx index 96b64e5ea59f3b..1e20cf9a3ca683 100644 --- a/docs/platforms/javascript/common/configuration/integrations/openai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/openai.mdx @@ -32,6 +32,7 @@ supported: - javascript.solid - javascript.ember - javascript.gatsby + - javascript.react-native --- diff --git a/docs/platforms/react-native/ai-agent-monitoring/index.mdx b/docs/platforms/react-native/ai-agent-monitoring/index.mdx new file mode 100644 index 00000000000000..d3542a5952d901 --- /dev/null +++ b/docs/platforms/react-native/ai-agent-monitoring/index.mdx @@ -0,0 +1,21 @@ +--- +title: AI Agent Monitoring +sidebar_order: 7 +description: "Learn how to manually instrument AI agents in React Native applications." +sidebar_section: features +new: true +--- + +With Sentry AI Agent Monitoring, 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. AI Agent Monitoring data will be fully connected to your other Sentry data like logs, errors, and traces. + +## Prerequisites + +Before setting up AI Agent Monitoring, ensure you have tracing enabled in your Sentry configuration. + + + +**React Native applications require manual instrumentation.** The automatic (OpenTelemetry-based) AI integrations shipped with `@sentry/node` rely on Node.js require-hooks that aren't available on Hermes or JavaScriptCore, so they can't be used from React Native. Use the manual client wrappers described below instead. + + + + diff --git a/includes/ai-agent-monitoring/manual-instrumentation.mdx b/includes/ai-agent-monitoring/manual-instrumentation.mdx new file mode 100644 index 00000000000000..2695dae80e046b --- /dev/null +++ b/includes/ai-agent-monitoring/manual-instrumentation.mdx @@ -0,0 +1,358 @@ +## Using Integration Helpers + + + + + +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:** +- OpenAI +- Anthropic +- Google Gen AI SDK +- LangChain +- LangGraph + +Each integration page includes a manual-instrumentation example with options like `recordInputs` and `recordOutputs`. + + + + +```javascript +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!" }], +}); +``` + + + + + +## Manual Span Creation + +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 [AI Agents Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/ai/agents/), spans must have well-defined names and data attributes. + +### Invoke Agent Span + + + + + +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 used +- `gen_ai.response.text` — The agent's final output +- `gen_ai.usage.input_tokens` / `output_tokens` — Total token counts + + + + +```javascript +// 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.response.text", JSON.stringify([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; + } +); +``` + + + + + + + + + +### AI Client Span + + + + + +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.request.messages` — Chat messages sent to the LLM +- `gen_ai.request.max_tokens` — Token limit for the response +- `gen_ai.response.text` — The model's response + + + + +```javascript +// 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", content: "Tell me a joke" }]; + + // set chat request data + span.setAttribute("gen_ai.request.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.response.text", JSON.stringify([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; + } +); +``` + + + + + + + + + +### 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. + +**Key attributes:** +- `gen_ai.tool.name` — The tool's name (e.g., "random_number") +- `gen_ai.tool.description` — Description of what the tool does +- `gen_ai.tool.input` — The arguments passed to the tool +- `gen_ai.tool.output` — The tool's return value + + + + +```javascript +// 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.request.model": myAi.model, + "gen_ai.tool.type": "function", + "gen_ai.tool.name": tool.name, + "gen_ai.tool.description": tool.description, + "gen_ai.tool.input": 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.output", String(toolResult)); + + return toolResult; + } + ); +} +``` + + + + + + + + + +### Handoff Span + + + + + +This span marks the transition of control from one agent to another, typically when the current agent determines another agent is better suited to handle the task. + +**Requirements:** +- `op` must be `"gen_ai.handoff"` +- `name` should follow the pattern `"handoff from {source} to {target}"` +- All [Common Span Attributes](#common-span-attributes) should be set + +The handoff span itself has no body — it just marks the transition point before the target agent starts. + + + + +```javascript +// Example agent implementations for demonstration +const myAgent = { + name: "Weather Agent", + modelProvider: "openai", + model: "gpt-4o-mini", + async run() { + // Agent implementation + return { + handoffTo: "Travel Agent", + output: "I need to handoff to the travel agent for booking recommendations", + }; + }, +}; + +const otherAgent = { + name: "Travel Agent", + modelProvider: "openai", + model: "gpt-4o-mini", + async run() { + // Other agent implementation + return { output: "Here are some travel recommendations..." }; + }, +}; + +// First agent execution +const result = await Sentry.startSpan( + { op: "gen_ai.invoke_agent", name: `invoke_agent ${myAgent.name}` }, + () => myAgent.run() +); + +// Check if we should handoff to another agent +if (result.handoffTo) { + // Create handoff span + await Sentry.startSpan( + { + op: "gen_ai.handoff", + name: `handoff from ${myAgent.name} to ${otherAgent.name}`, + attributes: { + "gen_ai.request.model": myAgent.model, + }, + }, + () => { + // the handoff span just marks the handoff + // no actual work is done here + } + ); + + // Execute the other agent + await Sentry.startSpan( + { op: "gen_ai.invoke_agent", name: `invoke_agent ${otherAgent.name}` }, + () => otherAgent.run() + ); +} +``` + + + + + +## Common Span Attributes + +