Merge branch 'master' into ivana/python/migration-guide-rename-param

Author: sentrivana

develop-docs/integrations/index.mdx

@@ -4,4 +4,70 @@ description: How to setup Sentry integrations. Integrations connect the Sentry s
 sidebar_order: 80
 ---
 
-<PageGrid />
+<PageGrid/>
+
+
+
+## Integration Backup and Restore Scripts
+
+### Overview
+
+When working on integration development locally, your database contains important configuration that makes integrations work properly. If you run `make reset-db` or need to delete your local environment, you lose all this setup and have to configure integrations from scratch.
+There are two scripts that help you backup and restore your local Sentry integration configuration and setup data.
+
+These scripts allow you to:
+- **Backup**: Save your current integration state to a JSON file
+- **Restore**: Load the integration state back into a clean database
+
+### What Data is Backed Up
+
+The scripts handle the following Sentry models in the correct dependency order:
+- `IdentityProvider` - Authentication provider configurations
+- `Integration` - Integration instances and settings  
+- `Identity` - User identity mappings
+- `OrganizationIntegration` - Organization-specific integration configurations
+
+### Prerequisites
+
+- Sentry development environment set up locally
+- Python environment with Sentry dependencies installed
+- Access to your local Sentry database
+
+### Script Files
+
+There are two scripts (exist in `sentry` and `getsentry`):
+
+- `save_integration_data` - Backs up integration data
+- `load_integration_data` - Restores integration data
+
+### Usage Instructions
+
+#### Step 1: Save Your Integration Data
+
+Before running `make reset-db` or making any destructive changes, backup your current integration state:
+
+```bash
+# Navigate to your Sentry project directory
+cd /path/to/sentry # or /path/to/getsentry
+
+# Run the save script
+bin/save_integration_data --output-file integration_backup.json
+```
+
+#### Step 2: Restore Your Integration Data
+
+After your database is reset and ready, restore your integration configuration:
+
+```bash
+# Basic restore (preserves original organization IDs)
+bin/load_integration_data --input-file integration_backup.json
+```
+
+**Or, if you need to change the organization ID:**
+
+```bash
+# Restore and update organization ID for OrganizationIntegration objects
+bin/load_integration_data --input-file integration_backup.json --org-id 123
+```
+
+After restoring, all the previous integration data will be restored and you can start using the integration for local development again.

develop-docs/sdk/data-model/envelope-items.mdx

@@ -400,7 +400,7 @@ _None_
 
 Item type `"log"` contains an array of log payloads encoded as JSON. This allows for multiple log payloads to be sent in a single envelope item.
 
-Only a single log item is allowed per envelope. The `item_count` field in the envelope item header must match the amount of logs sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.log+json`.
+Only a single log container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of logs sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.log+json`.
 
 It's okay to mix logs from different traces into the same log envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header.
 

develop-docs/sdk/expected-features/mcp-instrumentation/errors.mdx

@@ -0,0 +1,100 @@
+---
+title: MCP Server Errors
+sidebar_title: Errors
+---
+
+MCP Server error instrumentation ensures that all errors occurring within the Model Context Protocol (MCP) server are captured and reported to Sentry, **without ever interfering with the operation of the MCP service itself**. 
+
+## Goals and Philosophy
+
+- **Comprehensive context:** Errors are always associated with the active Sentry span, so you get full context (method, tool, arguments, etc.) in Sentry.
+- **Categorized errors:** Errors are tagged by type (e.g., `validation`, `timeout`, `tool_execution`, `resource_operation`, `prompt_execution`, `transport`, etc.) for easy filtering and analysis in Sentry.
+- **Handler wrapping:** All MCP server handlers (`tool`, `resource`, `prompt`) are wrapped to ensure errors are captured and correlated with the correct request span.
+- **Span status tracking:** When errors occur, the active span status is automatically set to error for better trace correlation.
+
+## Safe Error Capture
+
+The core utility is an error capture function:
+
+```ts
+import { getClient } from '../../currentScopes';
+import { captureException } from '../../exports';
+import { SPAN_STATUS_ERROR } from '../../tracing';
+import { getActiveSpan } from '../../utils/spanUtils';
+import type { McpErrorType } from './types';
+
+export function captureError(error: Error, errorType?: McpErrorType, extraData?: Record<string, unknown>): void {
+  try {
+    const client = getClient();
+    if (!client) return;
+
+    const activeSpan = getActiveSpan();
+    if (activeSpan?.isRecording()) {
+      activeSpan.setStatus({
+        code: SPAN_STATUS_ERROR,
+        message: 'internal_error',
+      });
+    }
+
+    captureException(error, {
+      mechanism: {
+        type: 'mcp_server',
+        handled: false,
+        data: {
+          error_type: errorType || 'handler_execution',
+          ...extraData,
+        },
+      },
+    });
+  } catch {
+    // Silently ignore capture errors so it never affects MCP operation
+  }
+}
+```
+
+- **Never throws an exception:** All error capture is wrapped in a try/catch and will never throw an exception.
+- **Mechanism-based categorization:** Error metadata is attached using the `mechanism` object.
+- **Flexible context:** Additional context can be passed via `extraData` and will be included in the mechanism data.
+
+## Handler Wrapping for Error Capture
+
+All MCP server method handlers (`tool`, `resource`, `prompt`) are wrapped to:
+- Correlate handler execution with the correct Sentry span (using request/session data)
+- Capture both synchronous and asynchronous errors
+- Categorize errors by handler type and error nature
+- Set span status to error for failed operations
+
+### Error Categorization
+
+Errors are categorized using the mechanism's data field according to the handler and type of error:
+
+- **Tool handler errors:**
+  - `validation` (e.g., protocol/validation errors)
+  - `timeout` (e.g., server timeouts)
+  - `tool_execution` (all other tool errors)
+- **Resource handler errors:**
+  - `resource_operation`
+- **Prompt handler errors:**
+  - `prompt_execution`
+- **Transport errors:**
+  - `transport`
+- **Protocol errors:**
+  - `protocol`
+
+The mechanism approach ensures that error classification information is available in the Sentry UI for debugging and analysis.
+
+**Note**: this mechanism data is not indexed so it is not searchable.
+
+## Span Correlation
+
+All errors are captured within the context of the active Sentry span, so you can:
+- See which MCP method, tool, or resource caused the error
+- View all arguments and context for the failed request
+- Correlate errors with traces and performance data
+
+## Transport Layer Error Instrumentation
+
+The MCP transport layer is also instrumented to:
+- Create spans for incoming/outgoing messages
+- Capture errors in transport event handlers (e.g., `onerror`)
+- Correlate protocol errors with the correct request/response

develop-docs/sdk/expected-features/mcp-instrumentation/index.mdx

@@ -0,0 +1,10 @@
+---
+title: MCP Instrumentation
+---
+
+The MCP Server module instruments Anthropic's Model Context Protocol (MCP) SDKs. At the moment it only supports the [MCP Typescript SDK](https://github.com/modelcontextprotocol/typescript-sdk/).
+
+## Features
+
+- [Tracing](./tracing)
+- [Errors](./errors)