diff --git a/app/[[...path]]/page.tsx b/app/[[...path]]/page.tsx index 7d3c950ed1d5a..3f254bc477622 100644 --- a/app/[[...path]]/page.tsx +++ b/app/[[...path]]/page.tsx @@ -9,6 +9,7 @@ import {ApiPage} from 'sentry-docs/components/apiPage'; import {DocPage} from 'sentry-docs/components/docPage'; import {Home} from 'sentry-docs/components/home'; import {Include} from 'sentry-docs/components/include'; +import {LinkCard, LinkCardGrid} from 'sentry-docs/components/linkCard'; import {PageLoadMetrics} from 'sentry-docs/components/pageLoadMetrics'; import {PlatformContent} from 'sentry-docs/components/platformContent'; import { @@ -47,19 +48,23 @@ export async function generateStaticParams() { export const dynamicParams = false; export const dynamic = 'force-static'; -const mdxComponentsWithWrapper = mdxComponents( - {Include, PlatformContent}, - ({children, frontMatter, nextPage, previousPage}) => ( - - {children} - - ) -); +const mdxComponentsWithWrapper = { + ...mdxComponents( + {Include, PlatformContent}, + ({children, frontMatter, nextPage, previousPage}) => ( + + {children} + + ) + ), + LinkCard, + LinkCardGrid, +}; function MDXLayoutRenderer({mdxSource, ...rest}) { const MDXLayout = useMemo(() => getMDXComponent(mdxSource), [mdxSource]); diff --git a/docs/ai/agent-skills.mdx b/docs/ai/agent-skills.mdx new file mode 100644 index 0000000000000..a72e3658a340f --- /dev/null +++ b/docs/ai/agent-skills.mdx @@ -0,0 +1,136 @@ +--- +title: Agent Skills +sidebar_order: 10 +description: "Teach your AI coding assistant how to set up and configure Sentry in your projects, and how to use Sentry's AI agents to debug and fix issues, even in your PRs." +keywords: + - agent skills + - Claude Code + - Cursor + - GitHub Copilot + - OpenAI Codex + - AI coding assistant + - vibe coding + - AI setup + - Windsurf + - AmpCode + - OpenCode +--- + +Agent skills are instruction sets that teach AI coding assistants how to perform specific tasks. Sentry's official agent skills give your AI assistant the knowledge to set up and configure Sentry in your projects with no manual configuration required. Use [workflow skills](/ai/agent-skills/#workflow-skills) to debug and fix issues in your projects. + + + +## Available Skills +There are two types of official Sentry agent skills: + +- **Setup skills** - Set up Sentry in your projects with no manual configuration required. +- **Workflow skills** - Debug and fix issues in your projects. + +Check out the latest and full list of skills [here](https://skills.sh/getsentry/sentry-agent-skills). + +## Install + +Run this in your project (or from any directory for user-level install) to add Sentry agent skills. Omit `--skill` to add all skills from the repo. + +```bash +npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-fix-issues +``` + +To add all Sentry skills: + +```bash +npx skills add https://github.com/getsentry/sentry-agent-skills +``` + + + +Agent skills require Cursor Nightly. Enable via: **Cursor Settings > Rules > Import Settings > Agent Skills** + + + +## Quick Reference + +Paths where each client looks for skills: **user-level** (all your projects) and **project-level** (current repository only). + +| Client | User-Level Path | Project-Level Path | +| --------------- | --------------------------- | ------------------ | +| **Claude Code** | `~/.claude/skills/` | `.claude/skills/` | +| **Codex** | `~/.codex/skills/` | `.codex/skills/` | +| **Copilot** | `~/.copilot/skills/` | `.github/skills/` | +| **Cursor** | `~/.cursor/skills/` | `.cursor/skills/` | +| **OpenCode** | `~/.config/opencode/skill/` | `.opencode/skill/` | +| **AmpCode** | `~/.config/agents/skills/` | `.agents/skills/` | + +## Usage + +Once installed, your AI assistant will automatically discover the skills. Simply ask it to perform Sentry-related tasks: + +### Setup + +| What to Say | Skill Used | +| ------------------------------------------ | -------------------------- | +| "Set up Sentry in my Next.js app" | `sentry-nextjs-setup` | +| "Add Sentry to my React app" | `sentry-react-setup` | +| "Set up Sentry in React Native" | `sentry-react-native-setup`| +| "Add Sentry to my Python/Django/Flask app" | `sentry-python-setup` | +| "Set up Sentry in my Ruby/Rails app" | `sentry-ruby-setup` | +| "Add performance monitoring to my app" | `sentry-setup-tracing` | +| "Enable Sentry logging" | `sentry-setup-logging` | +| "Track custom metrics with Sentry" | `sentry-setup-metrics` | +| "Monitor my OpenAI/LangChain calls" | `sentry-setup-ai-monitoring`| + +### Debugging & Workflow + +| What to Say | Skill Used | +| -------------------------------------- | --------------------- | +| "Fix the recent Sentry errors" | `sentry-fix-issues` | +| "Debug the production TypeError" | `sentry-fix-issues` | +| "Work through my Sentry backlog" | `sentry-fix-issues` | +| "Review Sentry comments on PR #123" | `sentry-pr-code-review`| +| "Fix the issues Sentry found in my PR" | `sentry-pr-code-review`| + +The assistant will load the appropriate skill and guide you through the process. + +## Contributing + +Want to contribute a new skill? Skills follow the [Agent Skills specification](https://agentskills.io/specification). Here's what one looks like: + + +Each skill is a folder with a `SKILL.md` file. The file has YAML frontmatter (`name`, `description`) and markdown instructions the AI assistant will use. + +```text +skill-name/ + SKILL.md # Required: YAML frontmatter + markdown instructions +``` + +```markdown +--- +name: skill-name +description: Description of what this skill does and when to use it +--- + +# Skill Title + +Instructions for the AI assistant... +``` + +**Requirements:** + +1. Follow the [Agent Skills specification](https://agentskills.io/specification) +2. Have a valid `name` (lowercase, hyphens, 1-64 characters) +3. Include a clear `description` (1-1024 characters) +4. **Keep skills concise** — use tables over prose, avoid obvious information +5. Include an "Invoke This Skill When" section with trigger phrases +6. Verify technical details against Sentry docs + +### Style Guidelines + +- Prefer tables over paragraphs for reference information +- Use phases/steps for multi-stage workflows +- Include version requirements where applicable +- Add troubleshooting tables for common issues +- Target ~100-200 lines per skill to minimize token usage + +Submit contributions to the [sentry-agent-skills repository](https://github.com/getsentry/sentry-agent-skills). + + diff --git a/docs/product/sentry-mcp/img/mcp-autofix1.png b/docs/ai/img/mcp-autofix1.png similarity index 100% rename from docs/product/sentry-mcp/img/mcp-autofix1.png rename to docs/ai/img/mcp-autofix1.png diff --git a/docs/product/sentry-mcp/img/mcp-light-1.png b/docs/ai/img/mcp-light-1.png similarity index 100% rename from docs/product/sentry-mcp/img/mcp-light-1.png rename to docs/ai/img/mcp-light-1.png diff --git a/docs/product/sentry-mcp/img/mcp-tools.png b/docs/ai/img/mcp-tools.png similarity index 100% rename from docs/product/sentry-mcp/img/mcp-tools.png rename to docs/ai/img/mcp-tools.png diff --git a/docs/product/sentry-mcp/img/mcpdev.png b/docs/ai/img/mcpdev.png similarity index 100% rename from docs/product/sentry-mcp/img/mcpdev.png rename to docs/ai/img/mcpdev.png diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx new file mode 100644 index 0000000000000..2a1589badf5d2 --- /dev/null +++ b/docs/ai/index.mdx @@ -0,0 +1,53 @@ +--- +title: Sentry for AI +sidebar_order: 1 +description: "Connect Sentry to your AI coding assistants and workflows. Install agent skills, use the MCP server, or add monitoring to your AI applications." +new: true +keywords: + - AI + - artificial intelligence + - LLM + - machine learning + - MCP + - Model Context Protocol + - agent skills + - AI monitoring + - vibe coding + - Claude + - Cursor + - Copilot +--- + + + + + + + +## AI In Sentry + +Looking for Sentry's AI-powered debugging features? Sentry uses AI to help you debug faster with automated root cause analysis, fix suggestions, and AI-powered PR reviews. + +**Key features:** +- **[Seer](/product/ai-in-sentry/seer/)** - AI debugging agent with automated root cause analysis and code fixes +- **[AI Code Review](/product/ai-in-sentry/ai-code-review/)** - Get error predictions and code reviews on your pull requests + +[Learn more about AI In Sentry](/product/ai-in-sentry/) diff --git a/docs/product/sentry-mcp/index.mdx b/docs/ai/mcp.mdx similarity index 97% rename from docs/product/sentry-mcp/index.mdx rename to docs/ai/mcp.mdx index 86ed2a857d377..2cd1c42b9e943 100644 --- a/docs/product/sentry-mcp/index.mdx +++ b/docs/ai/mcp.mdx @@ -1,10 +1,21 @@ --- title: Sentry MCP Server -sidebar_order: 120 +sidebar_order: 20 description: >- Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server. -og_image: /og-images/product-sentry-mcp.png +keywords: + - MCP + - Model Context Protocol + - AI integration + - Claude + - Cursor + - debugging + - OAuth + - remote MCP + - Seer + - autofix +og_image: /og-images/ai-mcp.png --- diff --git a/docs/product/insights/ai/agents/costs.mdx b/docs/ai/monitoring/agents/costs.mdx similarity index 95% rename from docs/product/insights/ai/agents/costs.mdx rename to docs/ai/monitoring/agents/costs.mdx index b453f7e2a31b8..930c1f3b807c6 100644 --- a/docs/product/insights/ai/agents/costs.mdx +++ b/docs/ai/monitoring/agents/costs.mdx @@ -4,7 +4,7 @@ sidebar_order: 15 description: Learn how Sentry calculates AI model costs, where pricing data comes from, and what's not covered. --- -The **Model Cost** widget in the [AI Agents Dashboard](/product/insights/ai/agents/dashboard/) Models tab shows estimated costs for your LLM usage. This page explains how those costs are calculated. +The **Model Cost** widget in the [AI Agents Dashboard](/ai/monitoring/agents/dashboard/) Models tab shows estimated costs for your LLM usage. This page explains how those costs are calculated. ## Data Sources diff --git a/docs/product/insights/ai/agents/dashboard.mdx b/docs/ai/monitoring/agents/dashboard.mdx similarity index 87% rename from docs/product/insights/ai/agents/dashboard.mdx rename to docs/ai/monitoring/agents/dashboard.mdx index 717c0667f3340..0284669e19c2b 100644 --- a/docs/product/insights/ai/agents/dashboard.mdx +++ b/docs/ai/monitoring/agents/dashboard.mdx @@ -2,10 +2,17 @@ title: AI Agents Dashboard sidebar_order: 10 description: Learn how to use Sentry's AI Agents Dashboard. -og_image: /og-images/product-insights-ai-agents-dashboard.png +keywords: + - AI dashboard + - agent dashboard + - LLM traces + - token usage + - tool calls + - agent insights +og_image: /og-images/ai-monitoring-agents-dashboard.png --- -The [AI Agents Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/ai/agents/) dashboard provides a comprehensive view of your AI workflows, including executions, model costs and token usage, tool calls, and recent errors. After you've [configured the Sentry SDK](/product/insights/ai/agents/getting-started/) in your project, telemetry data is collected and displayed in the dashboard to support analysis of system behavior and performance. +The [AI Agents Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/ai/agents/) dashboard provides a comprehensive view of your AI workflows, including executions, model costs and token usage, tool calls, and recent errors. Once you've [configured the Sentry SDK](/ai/monitoring/agents/getting-started/) for your AI agent project, telemetry data is collected and displayed in the dashboard to support analysis of system behavior and performance. At the top of the page, you will be able to navigate between the three tabs: [Overview](#overview), [Models](#models) and [Tools](#tools). @@ -37,7 +44,7 @@ The Models tab displays Model Cost, Tokens Used, and Token Types widgets, as wel ![AI Agents Monitoring Models](./img/models-tab.png) -The Model Cost widget shows estimated costs based on token usage and model pricing. For details on how costs are calculated, where pricing data comes from, and what's not covered, see [Model Costs](/product/insights/ai/agents/costs/). +The Model Cost widget shows estimated costs based on token usage and model pricing. For details on how costs are calculated, where pricing data comes from, and what's not covered, see [Model Costs](/ai/monitoring/agents/costs/). ## Tools diff --git a/docs/product/insights/ai/agents/getting-started.mdx b/docs/ai/monitoring/agents/getting-started.mdx similarity index 86% rename from docs/product/insights/ai/agents/getting-started.mdx rename to docs/ai/monitoring/agents/getting-started.mdx index 6179abaf4b9e0..46bdd9137b8ca 100644 --- a/docs/product/insights/ai/agents/getting-started.mdx +++ b/docs/ai/monitoring/agents/getting-started.mdx @@ -2,6 +2,14 @@ title: Set Up sidebar_order: 0 description: "Learn how to set up Sentry AI Agent Monitoring" +keywords: + - AI agent setup + - agent monitoring setup + - OpenAI integration + - Anthropic integration + - LangChain integration + - Python AI + - Node.js AI --- Sentry AI Agent Monitoring helps you track and debug AI agent applications using our supported SDKs and integrations. Monitor your complete agent workflows from user interaction to final response, including tool calls, model interactions, and custom logic. diff --git a/docs/product/insights/ai/agents/img/abbreviated-trace-view-drawer.png b/docs/ai/monitoring/agents/img/abbreviated-trace-view-drawer.png similarity index 100% rename from docs/product/insights/ai/agents/img/abbreviated-trace-view-drawer.png rename to docs/ai/monitoring/agents/img/abbreviated-trace-view-drawer.png diff --git a/docs/ai/monitoring/agents/img/abbreviated-trace-view.png b/docs/ai/monitoring/agents/img/abbreviated-trace-view.png new file mode 100644 index 0000000000000..0dd4332d1fb0f Binary files /dev/null and b/docs/ai/monitoring/agents/img/abbreviated-trace-view.png differ diff --git a/docs/product/insights/ai/agents/img/advanced-scrubbing-rule.png b/docs/ai/monitoring/agents/img/advanced-scrubbing-rule.png similarity index 100% rename from docs/product/insights/ai/agents/img/advanced-scrubbing-rule.png rename to docs/ai/monitoring/agents/img/advanced-scrubbing-rule.png diff --git a/docs/product/insights/ai/agents/img/full-trace-view.png b/docs/ai/monitoring/agents/img/full-trace-view.png similarity index 100% rename from docs/product/insights/ai/agents/img/full-trace-view.png rename to docs/ai/monitoring/agents/img/full-trace-view.png diff --git a/docs/product/insights/ai/agents/img/models-tab.png b/docs/ai/monitoring/agents/img/models-tab.png similarity index 100% rename from docs/product/insights/ai/agents/img/models-tab.png rename to docs/ai/monitoring/agents/img/models-tab.png diff --git a/docs/product/insights/ai/agents/img/overview-tab.png b/docs/ai/monitoring/agents/img/overview-tab.png similarity index 100% rename from docs/product/insights/ai/agents/img/overview-tab.png rename to docs/ai/monitoring/agents/img/overview-tab.png diff --git a/docs/ai/monitoring/agents/img/overview.png b/docs/ai/monitoring/agents/img/overview.png new file mode 100644 index 0000000000000..4985f2b3e1f7b Binary files /dev/null and b/docs/ai/monitoring/agents/img/overview.png differ diff --git a/docs/product/insights/ai/agents/img/tools-tab.png b/docs/ai/monitoring/agents/img/tools-tab.png similarity index 100% rename from docs/product/insights/ai/agents/img/tools-tab.png rename to docs/ai/monitoring/agents/img/tools-tab.png diff --git a/docs/product/insights/ai/agents/img/trace-table-detailed-distribution.png b/docs/ai/monitoring/agents/img/trace-table-detailed-distribution.png similarity index 100% rename from docs/product/insights/ai/agents/img/trace-table-detailed-distribution.png rename to docs/ai/monitoring/agents/img/trace-table-detailed-distribution.png diff --git a/docs/ai/monitoring/agents/img/trace-table.png b/docs/ai/monitoring/agents/img/trace-table.png new file mode 100644 index 0000000000000..4f35744a88194 Binary files /dev/null and b/docs/ai/monitoring/agents/img/trace-table.png differ diff --git a/docs/ai/monitoring/agents/img/trace-view.png b/docs/ai/monitoring/agents/img/trace-view.png new file mode 100644 index 0000000000000..381e2b1f4a163 Binary files /dev/null and b/docs/ai/monitoring/agents/img/trace-view.png differ diff --git a/docs/product/insights/ai/agents/index.mdx b/docs/ai/monitoring/agents/index.mdx similarity index 80% rename from docs/product/insights/ai/agents/index.mdx rename to docs/ai/monitoring/agents/index.mdx index ae0437c2e437e..57f68a4edf45e 100644 --- a/docs/product/insights/ai/agents/index.mdx +++ b/docs/ai/monitoring/agents/index.mdx @@ -4,7 +4,17 @@ sidebar_order: 10 description: >- Learn how to use Sentry's AI Agent monitoring tools to trace and debug your AI agent workflows, including agent runs, tool calls, and model interactions. -og_image: /og-images/product-insights-ai-agents.png +keywords: + - AI agents + - LLM monitoring + - agent monitoring + - tool calls + - OpenAI + - Anthropic + - LangChain + - token usage + - agent tracing +og_image: /og-images/ai-monitoring-agents.png --- Sentry's AI Agent monitoring tools help you understand what's going on with your AI agent workflows. They automatically collect information about agent runs, tool calls, model interactions, and errors across your entire AI pipeline—from user interaction to final response. @@ -21,4 +31,4 @@ To use AI Agent Monitoring, you must have an existing Sentry account and project ![AI Agents Monitoring Overview](./img/overview-tab.png) -Learn how to [set up Sentry for AI Agents](/product/insights/ai/agents/getting-started/). +Learn how to [set up Sentry for AI Agents](/ai/use-ai-in-sentry/monitoring/agents/getting-started/). diff --git a/docs/product/insights/ai/agents/privacy.mdx b/docs/ai/monitoring/agents/privacy.mdx similarity index 91% rename from docs/product/insights/ai/agents/privacy.mdx rename to docs/ai/monitoring/agents/privacy.mdx index 54eb137160b2f..bf3d80e8190c2 100644 --- a/docs/product/insights/ai/agents/privacy.mdx +++ b/docs/ai/monitoring/agents/privacy.mdx @@ -4,7 +4,14 @@ sidebar_order: 20 description: >- Learn how to control data collection and protect sensitive information in AI agent monitoring. -og_image: /og-images/product-insights-ai-agents-privacy.png +keywords: + - AI privacy + - PII + - data scrubbing + - sensitive data + - AI security + - prompt privacy +og_image: /og-images/ai-monitoring-agents-privacy.png --- ## SDK PII Settings diff --git a/docs/ai/monitoring/index.mdx b/docs/ai/monitoring/index.mdx new file mode 100644 index 0000000000000..cadc3fb452f3a --- /dev/null +++ b/docs/ai/monitoring/index.mdx @@ -0,0 +1,32 @@ +--- +title: AI Monitoring +sidebar_order: 30 +description: "Monitor your AI agents and MCP servers in production with Sentry. Track LLM calls, token usage, tool executions, and agent handoffs." +keywords: + - AI monitoring + - LLM monitoring + - agent monitoring + - MCP monitoring + - token usage + - AI observability + - AI tracing +--- + +Sentry provides comprehensive monitoring for your AI implementations. Whether you're building AI agents or MCP servers, Sentry automatically captures performance metrics, errors, and traces across your entire AI pipeline. + + + + + diff --git a/docs/product/insights/ai/mcp/dashboard.mdx b/docs/ai/monitoring/mcp/dashboard.mdx similarity index 79% rename from docs/product/insights/ai/mcp/dashboard.mdx rename to docs/ai/monitoring/mcp/dashboard.mdx index a5173c0d6dd32..067ae53e8ac0e 100644 --- a/docs/product/insights/ai/mcp/dashboard.mdx +++ b/docs/ai/monitoring/mcp/dashboard.mdx @@ -2,10 +2,16 @@ title: MCP Dashboard sidebar_order: 10 description: Learn how to use Sentry's MCP Dashboard. -og_image: /og-images/product-insights-ai-mcp-dashboard.png +keywords: + - MCP dashboard + - MCP insights + - MCP metrics + - tool performance + - resource monitoring +og_image: /og-images/ai-monitoring-mcp-dashboard.png --- -Once you've [configured the Sentry SDK](/product/insights/ai/mcp/getting-started/) for your MCP project, you'll start receiving data in the Sentry [MCP Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/ai/mcp/) dashboard. +Once you've [configured the Sentry SDK](/ai/monitoring/mcp/getting-started/) for your MCP project, you'll start receiving data in the Sentry [MCP Insights](https://sentry.io/orgredirect/organizations/:orgslug/insights/ai/mcp/) dashboard. The main dashboard provides a comprehensive view of all your MCP server activities, performance metrics, and recent tool executions. diff --git a/docs/product/insights/ai/mcp/getting-started.mdx b/docs/ai/monitoring/mcp/getting-started.mdx similarity index 97% rename from docs/product/insights/ai/mcp/getting-started.mdx rename to docs/ai/monitoring/mcp/getting-started.mdx index 676b51343dbda..80d512a1ddda2 100644 --- a/docs/product/insights/ai/mcp/getting-started.mdx +++ b/docs/ai/monitoring/mcp/getting-started.mdx @@ -2,6 +2,14 @@ title: Set Up sidebar_order: 0 description: "Learn how to set up Sentry MCP Monitoring" +keywords: + - MCP setup + - MCP integration + - MCP SDK + - FastMCP + - Python MCP + - JavaScript MCP + - Node.js MCP --- Sentry MCP Observability helps you track and debug Model Context Protocol (MCP) implementations using our supported SDKs and integrations. Monitor your complete MCP workflows from client connections to server responses, including tool executions, resource access, and protocol communications. @@ -180,7 +188,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]: b = arguments.get("b", 0) result = a + b return [TextContent(type="text", text=f"The sum is {result}")] - + return [TextContent(type="text", text=f"Unknown tool: {name}")] # Run the server @@ -196,4 +204,4 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) -``` \ No newline at end of file +``` diff --git a/docs/product/insights/ai/mcp/img/overview-tab.png b/docs/ai/monitoring/mcp/img/overview-tab.png similarity index 100% rename from docs/product/insights/ai/mcp/img/overview-tab.png rename to docs/ai/monitoring/mcp/img/overview-tab.png diff --git a/docs/ai/monitoring/mcp/img/overview.png b/docs/ai/monitoring/mcp/img/overview.png new file mode 100644 index 0000000000000..1cc5e2b7f9714 Binary files /dev/null and b/docs/ai/monitoring/mcp/img/overview.png differ diff --git a/docs/product/insights/ai/mcp/index.mdx b/docs/ai/monitoring/mcp/index.mdx similarity index 82% rename from docs/product/insights/ai/mcp/index.mdx rename to docs/ai/monitoring/mcp/index.mdx index 57d8a3e76019b..3f5f1bc3dbd37 100644 --- a/docs/product/insights/ai/mcp/index.mdx +++ b/docs/ai/monitoring/mcp/index.mdx @@ -1,11 +1,18 @@ --- -title: MCP +title: MCP Servers sidebar_order: 20 description: >- Learn how to use Sentry's MCP monitoring tools to trace and debug your Model Context Protocol implementations, including server connections, resource access, and tool executions. -og_image: /og-images/product-insights-ai-mcp.png +keywords: + - MCP monitoring + - MCP server + - Model Context Protocol + - MCP debugging + - MCP tracing + - tool execution +og_image: /og-images/ai-monitoring-mcp.png --- Sentry's MCP (Model Context Protocol) monitoring tools help you understand what's happening in your MCP implementations. They automatically collect information about MCP server connections, resource access, tool executions, and errors across your entire MCP pipeline—from client requests to server responses. @@ -21,3 +28,5 @@ Sentry's MCP (Model Context Protocol) monitoring tools help you understand what' To use MCP Monitoring, you must have an existing Sentry account and project set up. If you don't have one, [create an account here](https://sentry.io/signup/). ![MCP Monitoring Overview](./img/overview-tab.png) + +Learn how to [set up Sentry for MCP Monitoring](/ai/monitoring/mcp/getting-started/). diff --git a/docs/product/ai-in-sentry/ai-privacy-and-security/index.mdx b/docs/product/ai-in-sentry/ai-privacy-and-security/index.mdx index ed2b312bc0244..d88e51f51a82d 100644 --- a/docs/product/ai-in-sentry/ai-privacy-and-security/index.mdx +++ b/docs/product/ai-in-sentry/ai-privacy-and-security/index.mdx @@ -1,7 +1,13 @@ --- title: AI Privacy Principles -sidebar_order: 40 +sidebar_order: 30 description: "Learn about how Sentry handles your data and protects your privacy when it comes to AI." +keywords: + - AI privacy + - data protection + - AI security + - Seer privacy + - LLM privacy --- Generative AI features in Sentry, including Seer, are designed with your privacy in mind. Here are the core principles that apply to how we handle your data when it comes to our generative AI features. diff --git a/docs/product/ai-in-sentry/index.mdx b/docs/product/ai-in-sentry/index.mdx index be8c5a3d9d6da..cae82721bcfa2 100644 --- a/docs/product/ai-in-sentry/index.mdx +++ b/docs/product/ai-in-sentry/index.mdx @@ -2,6 +2,12 @@ title: AI in Sentry sidebar_order: 25 description: "Learn about Sentry's AI-powered features that help you analyze and debug your code faster." +keywords: + - Seer + - AI debugging + - autofix + - AI code review + - issue summary --- Sentry leverages artificial intelligence (AI) and machine learning (ML) to enhance your debugging and monitoring experience. Our AI-powered features help you understand issues faster, get automated fixes, and gain deeper insights into your application's behavior. @@ -23,7 +29,7 @@ Use Seer to: ### Query Assistant -You can ask Seer to query your traces and spans data via natural language queries and find relevant samples of compute metrics without building the whole query manually +You can ask Seer to query your traces and spans data via natural language queries and find relevant samples of compute metrics without building the whole query manually. ### AI Summaries @@ -36,7 +42,7 @@ Sentry includes strong guarantees for privacy and security of your data. At a gl - Sentry does not train generative AI models using your data by default and without your permission. - AI-generated output is shown only to you and other authorized users in your account. -You can get more details at [AI Privacy and Security](/product/ai-in-sentry/ai-privacy-and-security/). To learn more about all our data privacy practices go to [the security and legal docs](/security-legal-pii/security/ai-ml-policy/#use-of-identifying-data-for-generative-ai-features). +You can get more details at [AI Privacy and Security](/product/ai-in-sentry/ai-privacy-and-security/). To learn more about all our data privacy practices go to [the security and legal docs](/security-legal-pii/security/ai-ml-policy/#use-of-identifying-data-for-generative-ai-features). ## Disabling Generative AI Features diff --git a/docs/product/ai-in-sentry/seer/ai-code-review/index.mdx b/docs/product/ai-in-sentry/seer/ai-code-review/index.mdx index 9029ebef39656..f937a236bbe51 100644 --- a/docs/product/ai-in-sentry/seer/ai-code-review/index.mdx +++ b/docs/product/ai-in-sentry/seer/ai-code-review/index.mdx @@ -1,10 +1,8 @@ --- title: AI Code Review sidebar_order: 30 -description: >- - Get error predictions and code reviews for better code and - coverage. -og_image: /og-images/product-ai-in-sentry-ai-code-review.png +description: Get error predictions and code reviews for better code and coverage. +og_image: /og-images/product-ai-in-sentry-seer-ai-code-review.png --- AI Code Review helps you reviews your code changes, predicting errors and offering suggestions for improvement before merging pull requests. diff --git a/docs/product/insights/ai/index.mdx b/docs/product/insights/ai/index.mdx deleted file mode 100644 index 784dfc985820e..0000000000000 --- a/docs/product/insights/ai/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "AI Performance" -sidebar_order: 50 -description: "Learn how to use Sentry's AI Performance tool to get insights into things that may be affecting your application health, including critical LLM metrics." ---- - -Sentry's AI Performance allows you to see critical metrics for your LLM pipelines, like token usage and duration. In addition to having a dedicated space to monitor AI performance, you can also look view Sentry's Frontend, Backend, and Mobile Insights to understand the performance of the applications running your pipelines. - -## Learn More - - diff --git a/src/components/home.tsx b/src/components/home.tsx index d8ef903fbfb7c..000a2af9f1b3d 100644 --- a/src/components/home.tsx +++ b/src/components/home.tsx @@ -7,6 +7,7 @@ import ChatBubble from 'sentry-docs/imgs/chat-bubble.png'; import TerminalImage from 'sentry-docs/imgs/cli.png'; import ConceptsImage from 'sentry-docs/imgs/concepts-reference.png'; import HeroImage from 'sentry-docs/imgs/home_illustration.png'; +import AiImage from 'sentry-docs/imgs/integrate.png'; import OrganizationImage from 'sentry-docs/imgs/organization.png'; import CalculatorImage from 'sentry-docs/imgs/pricing.png'; import RocketImage from 'sentry-docs/imgs/rocket.png'; @@ -56,7 +57,16 @@ export function Home() { image={RocketImage} imageAlt="Rocket image" title="What is Sentry?" - description="Application monitoring and debugging software considered “not bad” by 4 million developers." + description="Application monitoring and debugging software considered 'not bad' by 4 million developers." + /> + + +
+ {icon} +
+

{title}

+

{description}

+
+
+ + ); +} + +export function LinkCardGrid({children}: {children: React.ReactNode}) { + return
{children}
; +} diff --git a/src/components/sidebar/dynamicNav.tsx b/src/components/sidebar/dynamicNav.tsx index a94c9b6c717d4..19993df49a822 100644 --- a/src/components/sidebar/dynamicNav.tsx +++ b/src/components/sidebar/dynamicNav.tsx @@ -311,8 +311,8 @@ export function DynamicNav({ collapsible={collapsible} isActive={!isPlatformSidebar && unversionedPath === root} topLevel - beta={parentNode.node?.context.beta} - isNew={parentNode.node?.context.new} + beta={parentNode.node?.context.beta ?? entity.node?.context.beta} + isNew={parentNode.node?.context.new ?? entity.node?.context.new} data-sidebar-link /> ); diff --git a/src/components/sidebar/sidebarNavigation.tsx b/src/components/sidebar/sidebarNavigation.tsx index 88de1485506fc..a5bdc7f8cddc8 100644 --- a/src/components/sidebar/sidebarNavigation.tsx +++ b/src/components/sidebar/sidebarNavigation.tsx @@ -12,6 +12,10 @@ import {docNodeToNavNode, getNavNodes} from './utils'; /** a root of `"some-root"` maps to the `/some-root/` url */ // todo: we should probably get rid of this const productSidebarItems = [ + { + title: 'Sentry for AI', + root: 'ai', + }, { title: 'Account Settings', root: 'account', diff --git a/src/lib/trafficClassification.ts b/src/lib/trafficClassification.ts new file mode 100644 index 0000000000000..a326fd38cc0d0 --- /dev/null +++ b/src/lib/trafficClassification.ts @@ -0,0 +1,43 @@ +/** + * Shared traffic classification types and patterns. + * Used by middleware (for classification) and tracesSampler (for metrics). + */ + +/** + * Traffic type classification for metrics and sampling decisions. + */ +export type TrafficType = 'ai_agent' | 'bot' | 'user' | 'unknown'; + +/** + * AI agents we want to track for docs/markdown consumption visibility. + * These fetch markdown content and we need performance data on serving to agentic tools. + * Also used by middleware to decide whether to serve markdown content. + */ +export const AI_AGENT_PATTERN = + /claude|anthropic|gptbot|chatgpt|openai|cursor|codex|copilot|perplexity|cohere|gemini/i; + +/** + * Bots/crawlers to filter out (SEO crawlers, social media, testing tools, monitors). + * Used as fallback when Next.js isBot detection isn't available. + */ +export const BOT_PATTERN = + /googlebot|bingbot|yandexbot|baiduspider|duckduckbot|applebot|ahrefsbot|semrushbot|dotbot|mj12bot|slackbot|twitterbot|linkedinbot|telegrambot|discordbot|facebookexternalhit|whatsapp|crawler|spider|scraper|headless|phantomjs|selenium|puppeteer|playwright|lighthouse|pagespeed|gtmetrix|pingdom|uptimerobot/i; + +/** + * Sample rates by traffic type. + */ +export const SAMPLE_RATES: Record = { + ai_agent: 1, // 100% - full visibility into agentic docs consumption + bot: 0, // 0% - filter out noise + user: 0.3, // 30% - reasonable sample of real users + unknown: 0.3, // 30% - same as users, but tracked separately +}; + +/** + * Checks if the input matches the pattern. + * Returns the matched substring (lowercase), or undefined if no match. + */ +export function matchPattern(input: string, pattern: RegExp): string | undefined { + const match = input.match(pattern); + return match ? match[0].toLowerCase() : undefined; +} diff --git a/src/mdxComponents.ts b/src/mdxComponents.ts index e19489ab36640..81f4736c84572 100644 --- a/src/mdxComponents.ts +++ b/src/mdxComponents.ts @@ -23,6 +23,7 @@ import {GradleUploadInstructions} from './components/gradleUploadInstructions'; import {GuideGrid} from './components/guideGrid'; import {JsBundleList} from './components/jsBundleList'; import {LambdaLayerDetail} from './components/lambdaLayerDetail'; +import {LinkCard, LinkCardGrid} from './components/linkCard'; import {LinkWithPlatformIcon} from './components/linkWithPlatformIcon'; import {LLMSteering} from './components/llmSteering'; import { @@ -125,6 +126,8 @@ export function mdxComponents( a: SmartLink, img: DocImage, ...dynamicComponents, + LinkCard, + LinkCardGrid, wrapper, }; } diff --git a/src/middleware.ts b/src/middleware.ts index 0bcde0c1d3161..6bdd31c0040c4 100644 --- a/src/middleware.ts +++ b/src/middleware.ts @@ -1,6 +1,8 @@ import * as Sentry from '@sentry/nextjs'; import type {NextRequest} from 'next/server'; -import {NextResponse} from 'next/server'; +import {NextResponse, userAgent} from 'next/server'; + +import {AI_AGENT_PATTERN, type TrafficType} from './lib/trafficClassification'; // This env var is set in next.config.js based on the `NEXT_PUBLIC_DEVELOPER_DOCS` env var at build time // a workaround edge middleware not having access to env vars @@ -35,24 +37,56 @@ const redirectStatusCode = process.env.NODE_ENV === 'development' ? 302 : 301; /** * Detects if the user agent belongs to an AI/LLM tool or development environment - * that would benefit from markdown format + * that would benefit from markdown format. + * Uses shared AI_AGENT_PATTERN from trafficClassification.ts. */ -function isAIOrDevTool(userAgent: string): boolean { - const patterns = [ - /claude/i, // Claude Desktop/Code - /cursor/i, // Cursor IDE - /copilot/i, // GitHub Copilot - /chatgpt/i, // ChatGPT - /openai/i, // OpenAI tools - /anthropic/i, // Anthropic tools - /vscode/i, // VS Code extensions - /intellij/i, // IntelliJ plugins - /sublime/i, // Sublime Text plugins - /got/i, // Got HTTP library (sindresorhus/got) - // Add more patterns as needed - ]; +function isAIOrDevTool(userAgentString: string): boolean { + return AI_AGENT_PATTERN.test(userAgentString); +} + +/** + * Traffic classification for metrics tracking. + * Uses Next.js userAgent() for enhanced bot detection plus custom AI agent patterns. + */ +function classifyTraffic(request: NextRequest): { + deviceType: string; + isBot: boolean; + trafficType: TrafficType; +} { + const userAgentString = request.headers.get('user-agent'); + + // No user-agent = unknown traffic + if (!userAgentString) { + return {trafficType: 'unknown', deviceType: 'unknown', isBot: false}; + } - return patterns.some(pattern => pattern.test(userAgent)); + // Use Next.js built-in userAgent() for enhanced parsing + const ua = userAgent(request); + + // Check for AI agents first (higher priority than generic bot detection) + if (AI_AGENT_PATTERN.test(userAgentString)) { + return { + trafficType: 'ai_agent', + deviceType: ua.device.type || 'desktop', + isBot: true, + }; + } + + // Use Next.js isBot detection (covers major search engines, social crawlers, etc.) + if (ua.isBot) { + return { + trafficType: 'bot', + deviceType: ua.device.type || 'crawler', + isBot: true, + }; + } + + // Real user traffic - include device type for richer metrics + return { + trafficType: 'user', + deviceType: ua.device.type || 'desktop', + isBot: false, + }; } /** @@ -70,7 +104,7 @@ function wantsMarkdownViaAccept(acceptHeader: string): boolean { * Detects if client wants markdown via Accept header or user-agent */ function wantsMarkdown(request: NextRequest): boolean { - const userAgent = request.headers.get('user-agent') || ''; + const uaString = request.headers.get('user-agent') || ''; const acceptHeader = request.headers.get('accept') || ''; // Strategy 1: Accept header content negotiation (standards-compliant) @@ -79,14 +113,49 @@ function wantsMarkdown(request: NextRequest): boolean { } // Strategy 2: User-agent detection (fallback for tools that don't set Accept) - return isAIOrDevTool(userAgent); + return isAIOrDevTool(uaString); +} + +/** + * Creates request headers with traffic classification for downstream consumption. + * These headers are added to the REQUEST (not response) so tracesSampler can read them. + * Uses NextResponse.next({ request: { headers } }) pattern to modify the request. + */ +function createClassifiedRequestHeaders(request: NextRequest): Headers { + const classification = classifyTraffic(request); + const headers = new Headers(request.headers); + headers.set('x-traffic-type', classification.trafficType); + headers.set('x-device-type', classification.deviceType); + return headers; +} + +/** + * Creates a pass-through response with traffic classification headers on the request. + */ +function nextWithClassification(request: NextRequest): NextResponse { + return NextResponse.next({ + request: { + headers: createClassifiedRequestHeaders(request), + }, + }); +} + +/** + * Creates a rewrite response with traffic classification headers on the request. + */ +function rewriteWithClassification(request: NextRequest, destination: URL): NextResponse { + return NextResponse.rewrite(destination, { + request: { + headers: createClassifiedRequestHeaders(request), + }, + }); } /** * Handles redirection to markdown versions for AI/LLM clients */ const handleAIClientRedirect = (request: NextRequest) => { - const userAgent = request.headers.get('user-agent') || ''; + const userAgentString = request.headers.get('user-agent') || ''; const acceptHeader = request.headers.get('accept') || ''; const url = request.nextUrl; @@ -99,7 +168,7 @@ const handleAIClientRedirect = (request: NextRequest) => { // Determine detection method for logging const detectionMethod = wantsMarkdownViaAccept(acceptHeader) ? 'Accept header' - : isAIOrDevTool(userAgent) + : isAIOrDevTool(userAgentString) ? 'User-agent' : 'Manual'; @@ -118,12 +187,13 @@ const handleAIClientRedirect = (request: NextRequest) => { }); } - // Skip if already requesting a markdown file + // Skip if already requesting a markdown file - pass through with classification headers if (url.pathname.endsWith('.md')) { - return undefined; + return nextWithClassification(request); } // Skip API routes and static assets (should already be filtered by matcher) + // Pass through with classification headers if ( url.pathname.startsWith('/api/') || url.pathname.startsWith('/_next/') || @@ -131,7 +201,7 @@ const handleAIClientRedirect = (request: NextRequest) => { url.pathname ) ) { - return undefined; + return nextWithClassification(request); } // Check for markdown request (Accept header, user-agent, or manual) @@ -158,10 +228,11 @@ const handleAIClientRedirect = (request: NextRequest) => { // Rewrite to serve markdown inline (same URL, different content) // The next.config.ts rewrite rule maps *.md to /md-exports/*.md - return NextResponse.rewrite(newUrl); + return rewriteWithClassification(request, newUrl); } - return undefined; + // Default: pass through with traffic classification headers + return nextWithClassification(request); }; const handleRedirects = (request: NextRequest) => { diff --git a/src/tracesSampler.ts b/src/tracesSampler.ts index 98521249664ed..f4a53ead9d8c5 100644 --- a/src/tracesSampler.ts +++ b/src/tracesSampler.ts @@ -1,5 +1,13 @@ import * as Sentry from '@sentry/nextjs'; +import { + AI_AGENT_PATTERN, + BOT_PATTERN, + matchPattern, + SAMPLE_RATES, + type TrafficType, +} from './lib/trafficClassification'; + // Sampling context passed to tracesSampler // Using inline type to avoid dependency on internal Sentry types interface SamplingContext { @@ -11,138 +19,129 @@ interface SamplingContext { parentSampled?: boolean; } -// AI agents we want to track for docs/markdown consumption visibility -// These fetch markdown content and we need performance data on serving to agentic tools -const AI_AGENT_PATTERN = new RegExp( - [ - 'claudebot', - 'claude-web', - 'anthropic', - 'gptbot', - 'chatgpt', - 'openai', - 'cursor', - 'codex', - 'copilot', - 'perplexity', - 'cohere', - 'gemini', - ].join('|'), - 'i' -); - -// Bots/crawlers to filter out (SEO crawlers, social media, testing tools, monitors) -// Uses specific bot names where possible, plus generic patterns for common crawler terms -const BOT_PATTERN = new RegExp( - [ - // Search engine crawlers - 'googlebot', - 'bingbot', - 'yandexbot', - 'baiduspider', - 'duckduckbot', - 'applebot', - // SEO tools - 'ahrefsbot', - 'semrushbot', - 'dotbot', - 'mj12bot', - // Social media - 'slackbot', - 'twitterbot', - 'linkedinbot', - 'telegrambot', - 'discordbot', - 'facebookexternalhit', - 'whatsapp', - // Generic patterns - 'crawler', - 'spider', - 'scraper', - 'headless', - // Testing/automation tools - 'phantomjs', - 'selenium', - 'puppeteer', - 'playwright', - // Performance/monitoring tools - 'lighthouse', - 'pagespeed', - 'gtmetrix', - 'pingdom', - 'uptimerobot', - ].join('|'), - 'i' -); +/** + * Gets a header value from headers object, handling case-insensitivity. + * HTTP headers are case-insensitive, but JS objects are case-sensitive. + */ +function getHeaderValue( + headers: Record | undefined, + headerName: string +): string | undefined { + if (!headers) { + return undefined; + } + const lowerName = headerName.toLowerCase(); + const key = Object.keys(headers).find(k => k.toLowerCase() === lowerName); + return key ? headers[key] : undefined; +} -// Default sample rate for real users -const DEFAULT_SAMPLE_RATE = 0.3; +/** + * Valid traffic types for validation of header values. + */ +const VALID_TRAFFIC_TYPES = new Set(['ai_agent', 'bot', 'user', 'unknown']); /** - * Checks if the input matches the pattern. - * Returns the matched substring (lowercase), or undefined if no match. + * Gets middleware traffic classification from headers. + * Validates that traffic type is one of the expected values. */ -function matchPattern(input: string, pattern: RegExp): string | undefined { - const match = input.match(pattern); - return match ? match[0].toLowerCase() : undefined; +function getMiddlewareClassification(headers?: Record): { + deviceType: string | undefined; + trafficType: TrafficType | undefined; +} { + const rawTrafficType = getHeaderValue(headers, 'x-traffic-type'); + return { + deviceType: getHeaderValue(headers, 'x-device-type'), + trafficType: VALID_TRAFFIC_TYPES.has(rawTrafficType as TrafficType) + ? (rawTrafficType as TrafficType) + : undefined, + }; } /** - * Determines trace sample rate based on user agent. - * - AI agents: 100% (we want full visibility into agentic docs consumption) + * Determines trace sample rate based on traffic classification. + * Uses middleware classification headers when available, falls back to user-agent pattern matching. + * + * Sample rates (from shared config): + * - AI agents: 100% (full visibility into agentic docs consumption) * - Bots/crawlers: 0% (filter out noise) * - Real users: 30% + * - Unknown: 30% (tracked separately for visibility) * - * AI agents are checked first, so if something matches both AI and bot patterns, we sample it. + * AI agents are checked first; if something matches both AI and bot patterns, we sample it. */ export function tracesSampler(samplingContext: SamplingContext): number { - // Try to get user agent from normalizedRequest headers (Sentry SDK provides this) - // Falls back to OTel semantic convention attributes if normalizedRequest not available + const headers = samplingContext.normalizedRequest?.headers; + + // Check for middleware classification headers first (most reliable) + const middlewareClassification = getMiddlewareClassification(headers); + + // If middleware provided valid classification, use it + if (middlewareClassification.trafficType) { + const {trafficType, deviceType} = middlewareClassification; + const sampleRate = SAMPLE_RATES[trafficType]; + + Sentry.metrics.count('docs.trace.sampled', 1, { + attributes: { + sample_rate: sampleRate, + traffic_type: trafficType, + device_type: deviceType || 'unknown', + }, + }); + + return sampleRate; + } + + // Fallback to user-agent pattern matching if no middleware classification + // This handles cases where middleware didn't run (API routes, etc.) const userAgent = - samplingContext.normalizedRequest?.headers?.['user-agent'] ?? + getHeaderValue(headers, 'user-agent') ?? (samplingContext.attributes?.['http.user_agent'] as string | undefined) ?? (samplingContext.attributes?.['user_agent.original'] as string | undefined); + // No user-agent = unknown traffic, track it explicitly if (!userAgent) { Sentry.metrics.count('docs.trace.sampled', 1, { attributes: { + sample_rate: SAMPLE_RATES.unknown, traffic_type: 'unknown', - sample_rate: DEFAULT_SAMPLE_RATE, + device_type: 'unknown', }, }); - return DEFAULT_SAMPLE_RATE; + return SAMPLE_RATES.unknown; } + // Check for AI agents first const aiAgent = matchPattern(userAgent, AI_AGENT_PATTERN); if (aiAgent) { Sentry.metrics.count('docs.trace.sampled', 1, { attributes: { + sample_rate: SAMPLE_RATES.ai_agent, traffic_type: 'ai_agent', agent_match: aiAgent, - sample_rate: 1, }, }); - return 1; + return SAMPLE_RATES.ai_agent; } + // Check for bots/crawlers const bot = matchPattern(userAgent, BOT_PATTERN); if (bot) { Sentry.metrics.count('docs.trace.sampled', 1, { attributes: { + sample_rate: SAMPLE_RATES.bot, traffic_type: 'bot', bot_match: bot, - sample_rate: 0, }, }); - return 0; + return SAMPLE_RATES.bot; } // Sample real users at default rate Sentry.metrics.count('docs.trace.sampled', 1, { attributes: { + sample_rate: SAMPLE_RATES.user, traffic_type: 'user', - sample_rate: DEFAULT_SAMPLE_RATE, }, }); - return DEFAULT_SAMPLE_RATE; + return SAMPLE_RATES.user; }