@mastra/sentry 1.2.15-alpha.0 → 1.2.15-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +12 -198
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @mastra/sentry
2
2
 
3
- Sentry AI Observability exporter for Mastra applications.
3
+ Export Mastra traces to Sentry AI monitoring with OpenTelemetry semantic conventions, zero-config setup, and optional SDK or exporter settings.
4
4
 
5
5
  ## Installation
6
6
 
@@ -10,217 +10,31 @@ npm install @mastra/sentry
10
10
 
11
11
  ## Usage
12
12
 
13
- ### Zero-Config Setup
14
-
15
- The exporter automatically reads credentials from environment variables:
16
-
17
- ```bash
18
- # Required
19
- SENTRY_DSN=https://...@...sentry.io/...
20
-
21
- # Optional
22
- SENTRY_ENVIRONMENT=production
23
- SENTRY_RELEASE=1.0.0
24
- ```
25
-
26
13
  ```typescript
14
+ import { Mastra } from '@mastra/core/mastra';
15
+ import { Observability } from '@mastra/observability';
27
16
  import { SentryExporter } from '@mastra/sentry';
28
17
 
29
- const mastra = new Mastra({
30
- ...,
31
- observability: {
18
+ export const mastra = new Mastra({
19
+ observability: new Observability({
32
20
  configs: {
33
21
  sentry: {
34
22
  serviceName: 'my-service',
35
23
  exporters: [new SentryExporter()],
36
24
  },
37
25
  },
38
- },
26
+ }),
39
27
  });
40
28
  ```
41
29
 
42
- ### Explicit Configuration
43
-
44
- You can also pass credentials directly:
45
-
46
- ```typescript
47
- import { SentryExporter } from '@mastra/sentry';
48
-
49
- const mastra = new Mastra({
50
- ...,
51
- observability: {
52
- configs: {
53
- sentry: {
54
- serviceName: 'my-service',
55
- exporters: [
56
- new SentryExporter({
57
- dsn: 'https://...@...sentry.io/...',
58
- environment: 'production', // Optional - deployment environment
59
- tracesSampleRate: 1.0, // Optional - send 100% of transactions to Sentry
60
- release: '1.0.0', // Optional - version of your code deployed
61
- }),
62
- ],
63
- },
64
- },
65
- },
66
- });
67
- ```
68
-
69
- ### Configuration Options
70
-
71
- | Option | Type | Description |
72
- | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
73
- | `dsn` | `string` | Data Source Name - tells the SDK where to send events. Defaults to `SENTRY_DSN` env var |
74
- | `environment` | `string` | Deployment environment (enables filtering issues and alerts by environment). Defaults to `SENTRY_ENVIRONMENT` env var or `'production'` |
75
- | `tracesSampleRate` | `number` | Percentage of transactions sent to Sentry (0.0 = 0%, 1.0 = 100%). Defaults to `1.0` |
76
- | `release` | `string` | Version of your code deployed (helps identify regressions and track deployments). Defaults to `SENTRY_RELEASE` env var |
77
- | `options` | `object` | Additional Sentry SDK options (integrations, beforeSend, etc.) |
78
-
79
- ## Features
80
-
81
- ### Tracing
82
-
83
- - **Automatic span mapping**: Root spans create Sentry traces, child spans nest properly
84
- - **OpenTelemetry semantic conventions**: Uses standard GenAI semantic conventions for AI spans
85
- - **Model generation support**: `MODEL_GENERATION` spans include token usage, model parameters, and streaming info
86
- - **Tool call tracking**: `TOOL_CALL` and `MCP_TOOL_CALL` spans track tool executions
87
- - **Workflow support**: `WORKFLOW_RUN` and `WORKFLOW_STEP` spans track workflow execution
88
- - **Error tracking**: Automatic error status and exception capture
89
- - **Hierarchical traces**: Maintains parent-child relationships
90
-
91
- ### Span Types Mapping
92
-
93
- | Mastra SpanType | Sentry Operation | Span Name Pattern | Notes |
94
- | --------------------------- | ---------------------- | ----------------------- | ------------------------------------------------------- |
95
- | `AGENT_RUN` | `gen_ai.invoke_agent` | `invoke_agent {agent}` | Accumulates tokens from the child MODEL_GENERATION span |
96
- | `MODEL_GENERATION` | `gen_ai.chat` | `chat {model} [stream]` | Contains aggregated streaming data |
97
- | `MODEL_STEP` | _(skipped)_ | - | Skipped to simplify trace hierarchy |
98
- | `MODEL_CHUNK` | _(skipped)_ | - | Too granular; data aggregated in MODEL_GENERATION |
99
- | `TOOL_CALL` | `gen_ai.execute_tool` | `execute_tool {tool}` | |
100
- | `MCP_TOOL_CALL` | `gen_ai.execute_tool` | `execute_tool {tool}` | |
101
- | `WORKFLOW_RUN` | `workflow.run` | `workflow` | |
102
- | `WORKFLOW_STEP` | `workflow.step` | `step` | |
103
- | `WORKFLOW_CONDITIONAL` | `workflow.conditional` | `step` | |
104
- | `WORKFLOW_CONDITIONAL_EVAL` | `workflow.conditional` | `step` | |
105
- | `WORKFLOW_PARALLEL` | `workflow.parallel` | `step` | |
106
- | `WORKFLOW_LOOP` | `workflow.loop` | `step` | |
107
- | `WORKFLOW_SLEEP` | `workflow.sleep` | `step` | |
108
- | `WORKFLOW_WAIT_EVENT` | `workflow.wait` | `step` | |
109
- | `PROCESSOR_RUN` | `ai.processor` | `step` | |
110
- | `GENERIC` | `ai.span` | `span` | |
111
-
112
- ### Semantic Attributes
113
-
114
- **Common attributes (all spans):**
30
+ ## Documentation
115
31
 
116
- - `sentry.origin`: `auto.ai.mastra` (identifies spans from Mastra)
117
- - `ai.span.type`: Mastra span type (e.g., `model_generation`, `tool_call`)
118
- - `gen_ai.conversation.id`: Chat thread identifier, set from `metadata.threadId` (groups spans in Sentry's Conversations view)
32
+ - [Sentry](https://mastra.ai/integrations/observability/sentry)
119
33
 
120
- **For `MODEL_GENERATION` and `MODEL_STEP` spans:**
34
+ ## Changelog
121
35
 
122
- - `gen_ai.operation.name`: `chat`
123
- - `gen_ai.system`: Model provider (e.g., `openai`, `anthropic`)
124
- - `gen_ai.request.model`: Model identifier (e.g., `gpt-4`)
125
- - `gen_ai.request.messages`: Input messages/prompts (JSON)
126
- - `gen_ai.response.text`: Output text response
127
- - `gen_ai.usage.input_tokens`: Input token count
128
- - `gen_ai.usage.output_tokens`: Output token count
129
- - `gen_ai.usage.cache_read.input_tokens`: Cached input tokens
130
- - `gen_ai.usage.cache_creation.input_tokens`: Cache write tokens
131
- - `gen_ai.usage.reasoning_tokens`: Reasoning tokens (for models like o1)
132
- - `gen_ai.request.temperature`: Temperature parameter
133
- - `gen_ai.request.max_tokens`: Max tokens parameter
134
- - `gen_ai.request.top_p`, `top_k`, `frequency_penalty`, `presence_penalty`: Other parameters
135
- - `gen_ai.request.stream`: Whether streaming was requested
136
- - `gen_ai.response.streaming`: Whether response was streamed
137
- - `gen_ai.response.tool_calls`: Tool calls made during generation (JSON array)
138
- - `gen_ai.completion_start_time`: Time first token arrived (for TTFT calculation)
36
+ See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/observability/sentry/CHANGELOG.md) for version history and release notes.
139
37
 
140
- **For `TOOL_CALL` spans:**
141
-
142
- - `gen_ai.operation.name`: `ai.toolCall`
143
- - `gen_ai.tool.name`: Tool identifier
144
- - `gen_ai.tool.type`: `function`
145
- - `gen_ai.tool.call.id`: Tool call ID
146
- - `gen_ai.tool.input`: Tool input (JSON)
147
- - `gen_ai.tool.output`: Tool output (JSON)
148
- - `gen_ai.tool.description`: Tool description
149
- - `tool.success`: Whether the tool call succeeded
150
-
151
- **For `AGENT_RUN` spans:**
152
-
153
- - `gen_ai.operation.name`: `invoke_agent`
154
- - `gen_ai.agent.name`: Agent identifier
155
- - `gen_ai.pipeline.name`: Agent name (for Sentry AI view)
156
- - `gen_ai.agent.instructions`: Agent instructions
157
- - `gen_ai.agent.prompt`: Agent prompt
158
- - `gen_ai.request.messages`: Input message (normalized)
159
- - `gen_ai.request.available_tools`: Available tools (JSON array)
160
- - `gen_ai.response.model`: Model from the child MODEL_GENERATION span
161
- - `gen_ai.response.text`: Output text from the child MODEL_GENERATION span
162
- - `gen_ai.usage.input_tokens`: Input tokens from the child MODEL_GENERATION span
163
- - `gen_ai.usage.output_tokens`: Output tokens from the child MODEL_GENERATION span
164
- - `gen_ai.usage.total_tokens`: Total tokens from the child MODEL_GENERATION span
165
- - `gen_ai.usage.cache_read.input_tokens`: Cached input tokens from the child MODEL_GENERATION span
166
- - `gen_ai.usage.cache_creation.input_tokens`: Cache write tokens from the child MODEL_GENERATION span
167
- - `gen_ai.usage.reasoning_tokens`: Reasoning tokens from the child MODEL_GENERATION span
168
- - `agent.max_steps`: Maximum steps allowed
169
- - `agent.available_tools`: Available tools (comma-separated)
170
-
171
- ## Example
172
-
173
- ```typescript
174
- import { Mastra } from '@mastra/core';
175
- import { SentryExporter } from '@mastra/sentry';
176
- import { Agent } from '@mastra/core';
177
- import { openai } from '@ai-sdk/openai';
178
-
179
- const mastra = new Mastra({
180
- observability: {
181
- configs: {
182
- sentry: {
183
- serviceName: 'my-ai-app',
184
- exporters: [
185
- new SentryExporter({
186
- dsn: process.env.SENTRY_DSN,
187
- environment: process.env.NODE_ENV,
188
- tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
189
- }),
190
- ],
191
- },
192
- },
193
- },
194
- });
195
-
196
- const agent = new Agent({
197
- name: 'customer-support',
198
- instructions: 'Help customers with their questions',
199
- model: openai('gpt-4'),
200
- mastra,
201
- });
202
-
203
- // All agent executions will be traced in Sentry
204
- const result = await agent.generate('How do I reset my password?');
205
- ```
206
-
207
- ## Troubleshooting
208
-
209
- ### Spans not appearing in Sentry
210
-
211
- 1. Verify your DSN is correct
212
- 2. Check the `tracesSampleRate` - set to `1.0` for testing
213
- 3. Ensure you're using Sentry SDK v10.32.1 or higher
214
- 4. Check console for any Sentry initialization errors
215
-
216
- ### High volume / cost
217
-
218
- Adjust the `tracesSampleRate` to send fewer transactions to Sentry:
219
-
220
- ```typescript
221
- new SentryExporter({
222
- tracesSampleRate: 0.1, // Send only 10% of transactions (recommended for high-load applications)
223
- });
224
- ```
38
+ ## Support
225
39
 
226
- **Note:** To disable tracing entirely, don't set `tracesSampleRate` at all rather than setting it to `0`.
40
+ We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/sentry",
3
- "version": "1.2.15-alpha.0",
3
+ "version": "1.2.15-alpha.2",
4
4
  "description": "Sentry AI observability exporter for Mastra",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -24,8 +24,8 @@
24
24
  "license": "Apache-2.0",
25
25
  "dependencies": {
26
26
  "@sentry/node": "^10.68.0",
27
- "@mastra/observability": "1.17.5-alpha.0",
28
- "@mastra/otel-exporter": "1.3.13-alpha.0"
27
+ "@mastra/observability": "1.17.5-alpha.2",
28
+ "@mastra/otel-exporter": "1.3.13-alpha.2"
29
29
  },
30
30
  "devDependencies": {
31
31
  "@types/node": "22.20.1",
@@ -35,9 +35,9 @@
35
35
  "tsdown": "0.22.9",
36
36
  "typescript": "^7.0.2",
37
37
  "vitest": "4.1.10",
38
- "@mastra/core": "1.64.0-alpha.2",
39
- "@internal/types-builder": "0.0.104",
40
- "@internal/lint": "0.0.129"
38
+ "@internal/lint": "0.0.129",
39
+ "@mastra/core": "1.64.0-alpha.8",
40
+ "@internal/types-builder": "0.0.104"
41
41
  },
42
42
  "peerDependencies": {
43
43
  "@mastra/core": ">=1.16.0-0 <2.0.0-0"