@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/docs/observability/tracing/exporters/sentry.md

@@ -0,0 +1,208 @@
+# Sentry Exporter
+
+[Sentry](https://sentry.io/) is an application monitoring platform with AI-specific tracing capabilities. The Sentry exporter sends your traces to Sentry using OpenTelemetry semantic conventions, providing insights into model performance, token usage, and tool executions.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/sentry@beta
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/sentry@beta
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/sentry@beta
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/sentry@beta
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Sentry Account**: Sign up at [sentry.io](https://sentry.io/)
+2. **DSN**: Get your [Data Source Name](https://docs.sentry.io/concepts/key-terms/dsn-explainer/) from Project Settings → Client Keys
+3. **Environment Variables**: Set your configuration
+
+```bash
+SENTRY_DSN=https://...@...sentry.io/...
+
+# Optional
+SENTRY_ENVIRONMENT=production
+SENTRY_RELEASE=1.0.0
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { SentryExporter } from '@mastra/sentry'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      sentry: {
+        serviceName: 'my-service',
+        exporters: [new SentryExporter()],
+      },
+    },
+  }),
+})
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { SentryExporter } from '@mastra/sentry'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      sentry: {
+        serviceName: 'my-service',
+        exporters: [
+          new SentryExporter({
+            dsn: process.env.SENTRY_DSN!,
+            environment: 'production',
+            tracesSampleRate: 1.0, // Send 100% of transactions to Sentry
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new SentryExporter({
+  // Required settings
+  dsn: process.env.SENTRY_DSN!, // Data Source Name - tells the SDK where to send events
+
+  // Optional settings
+  environment: 'production', // Deployment environment (enables filtering issues and alerts by environment)
+  tracesSampleRate: 1.0, // Percentage of transactions sent to Sentry (0.0 = 0%, 1.0 = 100%)
+  release: '1.0.0', // Version of your code deployed (helps identify regressions and track deployments)
+
+  // Advanced Sentry options
+  options: {
+    // Any additional Sentry.NodeOptions
+    integrations: [],
+    beforeSend: event => event,
+    // ... other Sentry SDK options
+  },
+
+  // Diagnostic logging
+  logLevel: 'info', // debug | info | warn | error
+})
+```
+
+### Sampling Configuration
+
+Control the percentage of transactions sent to Sentry. This is useful for high-volume applications:
+
+```typescript
+new SentryExporter({
+  dsn: process.env.SENTRY_DSN!,
+  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
+})
+```
+
+> **Tip:** Set to `1.0` (100%) for development and `0.1` to `0.2` (10-20%) for production high-load applications. To disable tracing entirely, don't set `tracesSampleRate` at all rather than setting it to `0`.
+
+## Span Type Mapping
+
+Mastra span types are automatically mapped to Sentry operations:
+
+| Mastra SpanType             | Sentry Operation       | Notes                                             |
+| --------------------------- | ---------------------- | ------------------------------------------------- |
+| `AGENT_RUN`                 | `gen_ai.invoke_agent`  | Contains tokens from child MODEL\_GENERATION span |
+| `MODEL_GENERATION`          | `gen_ai.chat`          | Includes usage stats, streaming data              |
+| `MODEL_STEP`                | _(skipped)_            | Skipped to simplify trace hierarchy               |
+| `MODEL_CHUNK`               | _(skipped)_            | Data aggregated in MODEL\_GENERATION              |
+| `TOOL_CALL`                 | `gen_ai.execute_tool`  | Tool execution with input/output                  |
+| `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  | MCP tool execution                                |
+| `WORKFLOW_RUN`              | `workflow.run`         |                                                   |
+| `WORKFLOW_STEP`             | `workflow.step`        |                                                   |
+| `WORKFLOW_CONDITIONAL`      | `workflow.conditional` |                                                   |
+| `WORKFLOW_CONDITIONAL_EVAL` | `workflow.conditional` |                                                   |
+| `WORKFLOW_PARALLEL`         | `workflow.parallel`    |                                                   |
+| `WORKFLOW_LOOP`             | `workflow.loop`        |                                                   |
+| `WORKFLOW_SLEEP`            | `workflow.sleep`       |                                                   |
+| `WORKFLOW_WAIT_EVENT`       | `workflow.wait`        |                                                   |
+| `PROCESSOR_RUN`             | `ai.processor`         |                                                   |
+| `GENERIC`                   | `ai.span`              |                                                   |
+
+## OpenTelemetry Semantic Conventions
+
+The exporter uses standard GenAI semantic conventions with Sentry-specific attributes:
+
+**For MODEL\_GENERATION spans:**
+
+- `gen_ai.system`: Model provider (e.g., `openai`, `anthropic`)
+- `gen_ai.request.model`: Model identifier (e.g., `gpt-4`)
+- `gen_ai.response.model`: Response model
+- `gen_ai.response.text`: Output text response
+- `gen_ai.response.tool_calls`: Tool calls made during generation (JSON array)
+- `gen_ai.usage.input_tokens`: Input token count
+- `gen_ai.usage.output_tokens`: Output token count
+- `gen_ai.request.temperature`: Temperature parameter
+- `gen_ai.request.stream`: Whether streaming was requested
+- `gen_ai.request.messages`: Input messages/prompts (JSON)
+- `gen_ai.completion_start_time`: Time first token arrived
+
+**For TOOL\_CALL spans:**
+
+- `gen_ai.tool.name`: Tool identifier
+- `gen_ai.tool.type`: `function`
+- `gen_ai.tool.call.id`: Tool call ID
+- `gen_ai.tool.input`: Tool input (JSON)
+- `gen_ai.tool.output`: Tool output (JSON)
+- `tool.success`: Whether the tool call succeeded
+
+**For AGENT\_RUN spans:**
+
+- `gen_ai.agent.name`: Agent identifier
+- `gen_ai.pipeline.name`: Agent name (for Sentry AI view)
+- `gen_ai.agent.instructions`: Agent instructions
+- `gen_ai.response.model`: Model from child generation
+- `gen_ai.response.text`: Output text from child generation
+- `gen_ai.usage.*`: Token usage from child generation
+
+## Features
+
+- **Hierarchical traces**: Maintains parent-child relationships
+- **Token tracking**: Automatic token usage tracking for generations
+- **Tool call tracking**: Captures tool executions with input/output
+- **Streaming support**: Aggregates streaming responses
+- **Error tracking**: Automatic error status and exception capture
+- **Workflow support**: Tracks workflow execution steps
+- **Simplified hierarchy**: MODEL\_STEP and MODEL\_CHUNK spans are skipped to reduce noise
+
+## Related
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Sentry Documentation](https://docs.sentry.io/)
+- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)