@mastra/sentry 1.0.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @mastra/sentry
+
+## 1.0.0-beta.2
+
+### Major Changes
+
+- Adding @mastra/sentry observability exporter for AI tracing with OpenTelemetry GenAI semantic conventions ([#11890](https://github.com/mastra-ai/mastra/pull/11890))
+
+### Patch Changes
+
+- Updated dependencies [[`ebae12a`](https://github.com/mastra-ai/mastra/commit/ebae12a2dd0212e75478981053b148a2c246962d), [`c61a0a5`](https://github.com/mastra-ai/mastra/commit/c61a0a5de4904c88fd8b3718bc26d1be1c2ec6e7), [`69136e7`](https://github.com/mastra-ai/mastra/commit/69136e748e32f57297728a4e0f9a75988462f1a7), [`449aed2`](https://github.com/mastra-ai/mastra/commit/449aed2ba9d507b75bf93d427646ea94f734dfd1), [`eb648a2`](https://github.com/mastra-ai/mastra/commit/eb648a2cc1728f7678768dd70cd77619b448dab9), [`0131105`](https://github.com/mastra-ai/mastra/commit/0131105532e83bdcbb73352fc7d0879eebf140dc), [`9d5059e`](https://github.com/mastra-ai/mastra/commit/9d5059eae810829935fb08e81a9bb7ecd5b144a7), [`ef756c6`](https://github.com/mastra-ai/mastra/commit/ef756c65f82d16531c43f49a27290a416611e526), [`b00ccd3`](https://github.com/mastra-ai/mastra/commit/b00ccd325ebd5d9e37e34dd0a105caae67eb568f), [`3bdfa75`](https://github.com/mastra-ai/mastra/commit/3bdfa7507a91db66f176ba8221aa28dd546e464a), [`e770de9`](https://github.com/mastra-ai/mastra/commit/e770de941a287a49b1964d44db5a5763d19890a6), [`52e2716`](https://github.com/mastra-ai/mastra/commit/52e2716b42df6eff443de72360ae83e86ec23993), [`27b4040`](https://github.com/mastra-ai/mastra/commit/27b4040bfa1a95d92546f420a02a626b1419a1d6), [`610a70b`](https://github.com/mastra-ai/mastra/commit/610a70bdad282079f0c630e0d7bb284578f20151), [`8dc7f55`](https://github.com/mastra-ai/mastra/commit/8dc7f55900395771da851dc7d78d53ae84fe34ec), [`8379099`](https://github.com/mastra-ai/mastra/commit/8379099fc467af6bef54dd7f80c9bd75bf8bbddf), [`b06be72`](https://github.com/mastra-ai/mastra/commit/b06be7223d5ef23edc98c01a67ef713c6cc039f9), [`8c0ec25`](https://github.com/mastra-ai/mastra/commit/8c0ec25646c8a7df253ed1e5ff4863a0d3f1316c), [`db28d12`](https://github.com/mastra-ai/mastra/commit/db28d12d37e170c99db3e32c06febf6225d13480), [`ff4d9a6`](https://github.com/mastra-ai/mastra/commit/ff4d9a6704fc87b31a380a76ed22736fdedbba5a), [`69821ef`](https://github.com/mastra-ai/mastra/commit/69821ef806482e2c44e2197ac0b050c3fe3a5285), [`1ed5716`](https://github.com/mastra-ai/mastra/commit/1ed5716830867b3774c4a1b43cc0d82935f32b96), [`4186bdd`](https://github.com/mastra-ai/mastra/commit/4186bdd00731305726fa06adba0b076a1d50b49f), [`7aaf973`](https://github.com/mastra-ai/mastra/commit/7aaf973f83fbbe9521f1f9e7a4fd99b8de464617)]:
+  - @mastra/core@1.0.0-beta.22
+  - @mastra/observability@1.0.0-beta.11
+  - @mastra/otel-exporter@1.0.0-beta.13

package/README.md

@@ -0,0 +1,225 @@
+# @mastra/sentry
+
+Sentry AI Observability exporter for Mastra applications.
+
+## Installation
+
+```bash
+npm install @mastra/sentry
+```
+
+## Usage
+
+### Zero-Config Setup
+
+The exporter automatically reads credentials from environment variables:
+
+```bash
+# Required
+SENTRY_DSN=https://...@...sentry.io/...
+
+# Optional
+SENTRY_ENVIRONMENT=production
+SENTRY_RELEASE=1.0.0
+```
+
+```typescript
+import { SentryExporter } from '@mastra/sentry';
+
+const mastra = new Mastra({
+  ...,
+  observability: {
+    configs: {
+      sentry: {
+        serviceName: 'my-service',
+        exporters: [new SentryExporter()],
+      },
+    },
+  },
+});
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly:
+
+```typescript
+import { SentryExporter } from '@mastra/sentry';
+
+const mastra = new Mastra({
+  ...,
+  observability: {
+    configs: {
+      sentry: {
+        serviceName: 'my-service',
+        exporters: [
+          new SentryExporter({
+            dsn: 'https://...@...sentry.io/...',
+            environment: 'production', // Optional - deployment environment
+            tracesSampleRate: 1.0, // Optional - send 100% of transactions to Sentry
+            release: '1.0.0', // Optional - version of your code deployed
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+### Configuration Options
+
+| Option             | Type     | Description                                                                                                                             |
+| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `dsn`              | `string` | Data Source Name - tells the SDK where to send events. Defaults to `SENTRY_DSN` env var                                                 |
+| `environment`      | `string` | Deployment environment (enables filtering issues and alerts by environment). Defaults to `SENTRY_ENVIRONMENT` env var or `'production'` |
+| `tracesSampleRate` | `number` | Percentage of transactions sent to Sentry (0.0 = 0%, 1.0 = 100%). Defaults to `1.0`                                                     |
+| `release`          | `string` | Version of your code deployed (helps identify regressions and track deployments). Defaults to `SENTRY_RELEASE` env var                  |
+| `options`          | `object` | Additional Sentry SDK options (integrations, beforeSend, etc.)                                                                          |
+
+## Features
+
+### Tracing
+
+- **Automatic span mapping**: Root spans create Sentry traces, child spans nest properly
+- **OpenTelemetry semantic conventions**: Uses standard GenAI semantic conventions for AI spans
+- **Model generation support**: `MODEL_GENERATION` spans include token usage, model parameters, and streaming info
+- **Tool call tracking**: `TOOL_CALL` and `MCP_TOOL_CALL` spans track tool executions
+- **Workflow support**: `WORKFLOW_RUN` and `WORKFLOW_STEP` spans track workflow execution
+- **Error tracking**: Automatic error status and exception capture
+- **Hierarchical traces**: Maintains parent-child relationships
+
+### Span Types Mapping
+
+| Mastra SpanType             | Sentry Operation       | Span Name Pattern       | Notes                                                   |
+| --------------------------- | ---------------------- | ----------------------- | ------------------------------------------------------- |
+| `AGENT_RUN`                 | `gen_ai.invoke_agent`  | `invoke_agent {agent}`  | Accumulates tokens from the child MODEL_GENERATION span |
+| `MODEL_GENERATION`          | `gen_ai.chat`          | `chat {model} [stream]` | Contains aggregated streaming data                      |
+| `MODEL_STEP`                | _(skipped)_            | -                       | Skipped to simplify trace hierarchy                     |
+| `MODEL_CHUNK`               | _(skipped)_            | -                       | Too granular; data aggregated in MODEL_GENERATION       |
+| `TOOL_CALL`                 | `gen_ai.execute_tool`  | `execute_tool {tool}`   |                                                         |
+| `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  | `execute_tool {tool}`   |                                                         |
+| `WORKFLOW_RUN`              | `workflow.run`         | `workflow`              |                                                         |
+| `WORKFLOW_STEP`             | `workflow.step`        | `step`                  |                                                         |
+| `WORKFLOW_CONDITIONAL`      | `workflow.conditional` | `step`                  |                                                         |
+| `WORKFLOW_CONDITIONAL_EVAL` | `workflow.conditional` | `step`                  |                                                         |
+| `WORKFLOW_PARALLEL`         | `workflow.parallel`    | `step`                  |                                                         |
+| `WORKFLOW_LOOP`             | `workflow.loop`        | `step`                  |                                                         |
+| `WORKFLOW_SLEEP`            | `workflow.sleep`       | `step`                  |                                                         |
+| `WORKFLOW_WAIT_EVENT`       | `workflow.wait`        | `step`                  |                                                         |
+| `PROCESSOR_RUN`             | `ai.processor`         | `step`                  |                                                         |
+| `GENERIC`                   | `ai.span`              | `span`                  |                                                         |
+
+### Semantic Attributes
+
+**Common attributes (all spans):**
+
+- `sentry.origin`: `auto.ai.mastra` (identifies spans from Mastra)
+- `ai.span.type`: Mastra span type (e.g., `model_generation`, `tool_call`)
+
+**For `MODEL_GENERATION` and `MODEL_STEP` spans:**
+
+- `gen_ai.operation.name`: `chat`
+- `gen_ai.system`: Model provider (e.g., `openai`, `anthropic`)
+- `gen_ai.request.model`: Model identifier (e.g., `gpt-4`)
+- `gen_ai.request.messages`: Input messages/prompts (JSON)
+- `gen_ai.response.text`: Output text response
+- `gen_ai.usage.input_tokens`: Input token count
+- `gen_ai.usage.output_tokens`: Output token count
+- `gen_ai.usage.cache_read_input_tokens`: Cached input tokens
+- `gen_ai.usage.cache_write_input_tokens`: Cache write tokens
+- `gen_ai.usage.reasoning_tokens`: Reasoning tokens (for models like o1)
+- `gen_ai.request.temperature`: Temperature parameter
+- `gen_ai.request.max_tokens`: Max tokens parameter
+- `gen_ai.request.top_p`, `top_k`, `frequency_penalty`, `presence_penalty`: Other parameters
+- `gen_ai.request.stream`: Whether streaming was requested
+- `gen_ai.response.streaming`: Whether response was streamed
+- `gen_ai.response.tool_calls`: Tool calls made during generation (JSON array)
+- `gen_ai.completion_start_time`: Time first token arrived (for TTFT calculation)
+
+**For `TOOL_CALL` spans:**
+
+- `gen_ai.operation.name`: `ai.toolCall`
+- `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)
+- `gen_ai.tool.description`: Tool description
+- `tool.success`: Whether the tool call succeeded
+
+**For `AGENT_RUN` spans:**
+
+- `gen_ai.operation.name`: `invoke_agent`
+- `gen_ai.agent.name`: Agent identifier
+- `gen_ai.pipeline.name`: Agent name (for Sentry AI view)
+- `gen_ai.agent.instructions`: Agent instructions
+- `gen_ai.agent.prompt`: Agent prompt
+- `gen_ai.request.messages`: Input message (normalized)
+- `gen_ai.request.available_tools`: Available tools (JSON array)
+- `gen_ai.response.model`: Model from the child MODEL_GENERATION span
+- `gen_ai.response.text`: Output text from the child MODEL_GENERATION span
+- `gen_ai.usage.input_tokens`: Input tokens from the child MODEL_GENERATION span
+- `gen_ai.usage.output_tokens`: Output tokens from the child MODEL_GENERATION span
+- `gen_ai.usage.total_tokens`: Total tokens from the child MODEL_GENERATION span
+- `gen_ai.usage.cache_read_input_tokens`: Cached input tokens from the child MODEL_GENERATION span
+- `gen_ai.usage.cache_write_input_tokens`: Cache write tokens from the child MODEL_GENERATION span
+- `gen_ai.usage.reasoning_tokens`: Reasoning tokens from the child MODEL_GENERATION span
+- `agent.max_steps`: Maximum steps allowed
+- `agent.available_tools`: Available tools (comma-separated)
+
+## Example
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { SentryExporter } from '@mastra/sentry';
+import { Agent } from '@mastra/core';
+import { openai } from '@ai-sdk/openai';
+
+const mastra = new Mastra({
+  observability: {
+    configs: {
+      sentry: {
+        serviceName: 'my-ai-app',
+        exporters: [
+          new SentryExporter({
+            dsn: process.env.SENTRY_DSN,
+            environment: process.env.NODE_ENV,
+            tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
+          }),
+        ],
+      },
+    },
+  },
+});
+
+const agent = new Agent({
+  name: 'customer-support',
+  instructions: 'Help customers with their questions',
+  model: openai('gpt-4'),
+  mastra,
+});
+
+// All agent executions will be traced in Sentry
+const result = await agent.generate('How do I reset my password?');
+```
+
+## Troubleshooting
+
+### Spans not appearing in Sentry
+
+1. Verify your DSN is correct
+2. Check the `tracesSampleRate` - set to `1.0` for testing
+3. Ensure you're using Sentry SDK v10.32.1 or higher
+4. Check console for any Sentry initialization errors
+
+### High volume / cost
+
+Adjust the `tracesSampleRate` to send fewer transactions to Sentry:
+
+```typescript
+new SentryExporter({
+  tracesSampleRate: 0.1, // Send only 10% of transactions (recommended for high-load applications)
+});
+```
+
+**Note:** To disable tracing entirely, don't set `tracesSampleRate` at all rather than setting it to `0`.