@mastra/otel-exporter 1.3.12 → 1.3.13-alpha.1
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.
- package/README.md +16 -559
- package/dist/gen-ai-messages.d.ts.map +1 -1
- package/dist/span-converter.d.ts.map +1 -1
- package/dist/tracing.d.ts.map +1 -1
- package/package.json +7 -8
- package/CHANGELOG.md +0 -1966
package/README.md
CHANGED
|
@@ -1,587 +1,44 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mastra/otel-exporter
|
|
2
2
|
|
|
3
3
|
Export Mastra traces and logs to any OpenTelemetry-compatible observability platform.
|
|
4
4
|
|
|
5
5
|
> **⚠️ Important:** This package requires you to install an additional exporter package based on your provider. Each provider section below includes the specific installation command.
|
|
6
6
|
|
|
7
|
-
##
|
|
8
|
-
|
|
9
|
-
The exporter forwards two OpenTelemetry signals:
|
|
10
|
-
|
|
11
|
-
- **Traces** — Mastra spans, exported via `BatchSpanProcessor` over an OTLP `SpanExporter`.
|
|
12
|
-
- **Logs** — Mastra log events, exported via `BatchLogRecordProcessor` over an OTLP `LogRecordExporter`. When a log carries `traceId`/`spanId`, both the OTEL log record's native trace context and `mastra.traceId`/`mastra.spanId` attributes are populated so backends like Grafana, Datadog, and Honeycomb can correlate logs to traces automatically.
|
|
13
|
-
|
|
14
|
-
Both signals are enabled by default and share the same provider configuration. Toggle individual signals via `signals`:
|
|
15
|
-
|
|
16
|
-
```typescript
|
|
17
|
-
new OtelExporter({
|
|
18
|
-
provider: {/* ... */},
|
|
19
|
-
signals: {
|
|
20
|
-
traces: true, // default
|
|
21
|
-
logs: true, // default
|
|
22
|
-
},
|
|
23
|
-
});
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Log export requires the matching OTLP log exporter package for your protocol — install one of:
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
# HTTP/JSON
|
|
30
|
-
npm install @opentelemetry/exporter-logs-otlp-http
|
|
31
|
-
# HTTP/Protobuf
|
|
32
|
-
npm install @opentelemetry/exporter-logs-otlp-proto
|
|
33
|
-
# gRPC
|
|
34
|
-
npm install @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
If the matching log exporter package is not installed, log export is silently disabled and traces continue to work.
|
|
38
|
-
|
|
39
|
-
## Environment Variables
|
|
40
|
-
|
|
41
|
-
All providers support zero-config setup via environment variables. Set the appropriate variables and the exporter will automatically use them:
|
|
42
|
-
|
|
43
|
-
| Provider | Environment Variables |
|
|
44
|
-
| --------- | ------------------------------------------------------------------------------------------- |
|
|
45
|
-
| Dash0 | `DASH0_API_KEY` (required), `DASH0_ENDPOINT` (required), `DASH0_DATASET` (optional) |
|
|
46
|
-
| SigNoz | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional) |
|
|
47
|
-
| New Relic | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional) |
|
|
48
|
-
| Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) |
|
|
49
|
-
| Laminar | `LMNR_PROJECT_API_KEY` (required), `LAMINAR_ENDPOINT` (optional) |
|
|
50
|
-
|
|
51
|
-
## Supported Providers
|
|
52
|
-
|
|
53
|
-
### Dash0
|
|
54
|
-
|
|
55
|
-
#### Installation
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
# Dash0 uses gRPC protocol, requires both packages
|
|
59
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
#### Zero-Config Setup
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
# Required
|
|
66
|
-
DASH0_API_KEY=your-api-key
|
|
67
|
-
DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317
|
|
68
|
-
|
|
69
|
-
# Optional
|
|
70
|
-
DASH0_DATASET=production
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
```typescript
|
|
74
|
-
import { OtelExporter } from '@mastra/otel-exporter';
|
|
75
|
-
import { Mastra } from '@mastra/core/mastra';
|
|
76
|
-
|
|
77
|
-
const mastra = new Mastra({
|
|
78
|
-
...,
|
|
79
|
-
observability: {
|
|
80
|
-
configs: {
|
|
81
|
-
otel: {
|
|
82
|
-
serviceName: 'my-service',
|
|
83
|
-
exporters: [new OtelExporter({ provider: { dash0: {} } })],
|
|
84
|
-
},
|
|
85
|
-
},
|
|
86
|
-
},
|
|
87
|
-
});
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
#### Explicit Configuration
|
|
91
|
-
|
|
92
|
-
```typescript
|
|
93
|
-
new OtelExporter({
|
|
94
|
-
provider: {
|
|
95
|
-
dash0: {
|
|
96
|
-
apiKey: 'your-api-key',
|
|
97
|
-
endpoint: 'ingress.us-west-2.aws.dash0.com:4317',
|
|
98
|
-
dataset: 'production', // Optional
|
|
99
|
-
},
|
|
100
|
-
},
|
|
101
|
-
});
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
**Note:** Get your endpoint from your Dash0 dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
|
|
105
|
-
|
|
106
|
-
### SigNoz
|
|
107
|
-
|
|
108
|
-
#### Installation
|
|
109
|
-
|
|
110
|
-
```bash
|
|
111
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
#### Zero-Config Setup
|
|
115
|
-
|
|
116
|
-
```bash
|
|
117
|
-
# Required
|
|
118
|
-
SIGNOZ_API_KEY=your-api-key
|
|
119
|
-
|
|
120
|
-
# Optional
|
|
121
|
-
SIGNOZ_REGION=us # 'us' | 'eu' | 'in'
|
|
122
|
-
SIGNOZ_ENDPOINT=https://my-signoz.example.com # For self-hosted
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
```typescript
|
|
126
|
-
import { OtelExporter } from '@mastra/otel-exporter';
|
|
127
|
-
import { Mastra } from '@mastra/core/mastra';
|
|
128
|
-
|
|
129
|
-
const mastra = new Mastra({
|
|
130
|
-
...,
|
|
131
|
-
observability: {
|
|
132
|
-
configs: {
|
|
133
|
-
otel: {
|
|
134
|
-
serviceName: 'my-service',
|
|
135
|
-
exporters: [new OtelExporter({ provider: { signoz: {} } })],
|
|
136
|
-
},
|
|
137
|
-
},
|
|
138
|
-
},
|
|
139
|
-
});
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
#### Explicit Configuration
|
|
143
|
-
|
|
144
|
-
```typescript
|
|
145
|
-
new OtelExporter({
|
|
146
|
-
provider: {
|
|
147
|
-
signoz: {
|
|
148
|
-
apiKey: 'your-api-key',
|
|
149
|
-
region: 'us', // Optional: 'us' | 'eu' | 'in'
|
|
150
|
-
endpoint: 'https://my-signoz.example.com', // Optional: for self-hosted
|
|
151
|
-
},
|
|
152
|
-
},
|
|
153
|
-
});
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
### New Relic
|
|
157
|
-
|
|
158
|
-
#### Installation
|
|
7
|
+
## Installation
|
|
159
8
|
|
|
160
9
|
```bash
|
|
161
|
-
npm install @mastra/otel-exporter
|
|
10
|
+
npm install @mastra/otel-exporter
|
|
162
11
|
```
|
|
163
12
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
# Required
|
|
168
|
-
NEW_RELIC_LICENSE_KEY=your-license-key
|
|
13
|
+
## Usage
|
|
169
14
|
|
|
170
|
-
|
|
171
|
-
NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net # For EU region
|
|
172
|
-
```
|
|
15
|
+
Set the standard `OTEL_EXPORTER_OTLP_*` environment variables for your collector.
|
|
173
16
|
|
|
174
17
|
```typescript
|
|
175
|
-
import { OtelExporter } from '@mastra/otel-exporter';
|
|
176
18
|
import { Mastra } from '@mastra/core/mastra';
|
|
177
|
-
|
|
178
|
-
const mastra = new Mastra({
|
|
179
|
-
...,
|
|
180
|
-
observability: {
|
|
181
|
-
configs: {
|
|
182
|
-
otel: {
|
|
183
|
-
serviceName: 'my-service',
|
|
184
|
-
exporters: [new OtelExporter({ provider: { newrelic: {} } })],
|
|
185
|
-
},
|
|
186
|
-
},
|
|
187
|
-
},
|
|
188
|
-
});
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
#### Explicit Configuration
|
|
192
|
-
|
|
193
|
-
```typescript
|
|
194
|
-
new OtelExporter({
|
|
195
|
-
provider: {
|
|
196
|
-
newrelic: {
|
|
197
|
-
apiKey: 'your-license-key',
|
|
198
|
-
endpoint: 'https://otlp.eu01.nr-data.net', // Optional: for EU region
|
|
199
|
-
},
|
|
200
|
-
},
|
|
201
|
-
});
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
### Traceloop
|
|
205
|
-
|
|
206
|
-
#### Installation
|
|
207
|
-
|
|
208
|
-
```bash
|
|
209
|
-
# Traceloop uses HTTP/JSON protocol
|
|
210
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
#### Zero-Config Setup
|
|
214
|
-
|
|
215
|
-
```bash
|
|
216
|
-
# Required
|
|
217
|
-
TRACELOOP_API_KEY=your-api-key
|
|
218
|
-
|
|
219
|
-
# Optional
|
|
220
|
-
TRACELOOP_DESTINATION_ID=my-destination
|
|
221
|
-
TRACELOOP_ENDPOINT=https://custom.traceloop.com
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
```typescript
|
|
19
|
+
import { Observability } from '@mastra/observability';
|
|
225
20
|
import { OtelExporter } from '@mastra/otel-exporter';
|
|
226
|
-
import { Mastra } from '@mastra/core/mastra';
|
|
227
21
|
|
|
228
|
-
const mastra = new Mastra({
|
|
229
|
-
|
|
230
|
-
observability: {
|
|
22
|
+
export const mastra = new Mastra({
|
|
23
|
+
observability: new Observability({
|
|
231
24
|
configs: {
|
|
232
25
|
otel: {
|
|
233
26
|
serviceName: 'my-service',
|
|
234
|
-
exporters: [new OtelExporter({ provider: {
|
|
235
|
-
},
|
|
236
|
-
},
|
|
237
|
-
},
|
|
238
|
-
});
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
#### Explicit Configuration
|
|
242
|
-
|
|
243
|
-
```typescript
|
|
244
|
-
new OtelExporter({
|
|
245
|
-
provider: {
|
|
246
|
-
traceloop: {
|
|
247
|
-
apiKey: 'your-api-key',
|
|
248
|
-
destinationId: 'my-destination', // Optional
|
|
249
|
-
endpoint: 'https://custom.traceloop.com', // Optional
|
|
250
|
-
},
|
|
251
|
-
},
|
|
252
|
-
});
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
### Laminar
|
|
256
|
-
|
|
257
|
-
#### Installation
|
|
258
|
-
|
|
259
|
-
```bash
|
|
260
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
#### Zero-Config Setup
|
|
264
|
-
|
|
265
|
-
```bash
|
|
266
|
-
# Required
|
|
267
|
-
LMNR_PROJECT_API_KEY=your-api-key
|
|
268
|
-
|
|
269
|
-
# Optional
|
|
270
|
-
LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
```typescript
|
|
274
|
-
import { OtelExporter } from '@mastra/otel-exporter';
|
|
275
|
-
import { Mastra } from '@mastra/core/mastra';
|
|
276
|
-
|
|
277
|
-
const mastra = new Mastra({
|
|
278
|
-
...,
|
|
279
|
-
observability: {
|
|
280
|
-
configs: {
|
|
281
|
-
otel: {
|
|
282
|
-
serviceName: 'my-service',
|
|
283
|
-
exporters: [new OtelExporter({ provider: { laminar: {} } })],
|
|
284
|
-
},
|
|
285
|
-
},
|
|
286
|
-
},
|
|
287
|
-
});
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
#### Explicit Configuration
|
|
291
|
-
|
|
292
|
-
```typescript
|
|
293
|
-
new OtelExporter({
|
|
294
|
-
provider: {
|
|
295
|
-
laminar: {
|
|
296
|
-
apiKey: 'your-api-key',
|
|
297
|
-
endpoint: 'https://api.lmnr.ai/v1/traces', // Optional
|
|
298
|
-
},
|
|
299
|
-
},
|
|
300
|
-
});
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
### Zipkin
|
|
304
|
-
|
|
305
|
-
#### Installation
|
|
306
|
-
|
|
307
|
-
```bash
|
|
308
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-zipkin
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
#### Configuration
|
|
312
|
-
|
|
313
|
-
```typescript
|
|
314
|
-
import { OtelExporter } from '@mastra/otel-exporter';
|
|
315
|
-
import { Mastra } from '@mastra/core/mastra';
|
|
316
|
-
|
|
317
|
-
const mastra = new Mastra({
|
|
318
|
-
...,
|
|
319
|
-
observability: {
|
|
320
|
-
configs: {
|
|
321
|
-
otel: {
|
|
322
|
-
serviceName: 'mastra-service',
|
|
323
|
-
exporters: [
|
|
324
|
-
new OtelExporter({
|
|
325
|
-
provider: {
|
|
326
|
-
custom: {
|
|
327
|
-
endpoint: 'http://localhost:9411/api/v2/spans',
|
|
328
|
-
protocol: 'zipkin',
|
|
329
|
-
}
|
|
330
|
-
},
|
|
331
|
-
})
|
|
332
|
-
],
|
|
333
|
-
},
|
|
334
|
-
},
|
|
335
|
-
},
|
|
336
|
-
});
|
|
337
|
-
```
|
|
338
|
-
|
|
339
|
-
### Custom/Other Providers
|
|
340
|
-
|
|
341
|
-
#### Installation
|
|
342
|
-
|
|
343
|
-
Choose the appropriate exporter based on your collector's protocol:
|
|
344
|
-
|
|
345
|
-
```bash
|
|
346
|
-
# For HTTP/JSON: Human-readable, larger payload, good for debugging
|
|
347
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
|
|
348
|
-
|
|
349
|
-
# For HTTP/Protobuf: Binary format, smaller payload, recommended for production
|
|
350
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
|
|
351
|
-
|
|
352
|
-
# For gRPC: Bidirectional streaming, lowest latency, requires gRPC support
|
|
353
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
|
|
354
|
-
|
|
355
|
-
# For Zipkin: Zipkin-specific format
|
|
356
|
-
npm install @mastra/otel-exporter @opentelemetry/exporter-zipkin
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
Most providers recommend HTTP/Protobuf for production use.
|
|
360
|
-
|
|
361
|
-
#### Configuration
|
|
362
|
-
|
|
363
|
-
```typescript
|
|
364
|
-
import { OtelExporter } from '@mastra/otel-exporter';
|
|
365
|
-
import { Mastra } from '@mastra/core/mastra';
|
|
366
|
-
|
|
367
|
-
const mastra = new Mastra({
|
|
368
|
-
...,
|
|
369
|
-
observability: {
|
|
370
|
-
configs: {
|
|
371
|
-
otel: {
|
|
372
|
-
serviceName: 'mastra-service',
|
|
373
|
-
exporters: [
|
|
374
|
-
new OtelExporter({
|
|
375
|
-
provider: {
|
|
376
|
-
custom: {
|
|
377
|
-
endpoint: 'https://your-collector.example.com/v1/traces', // Required at runtime
|
|
378
|
-
protocol: 'http/protobuf', // Optional: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'
|
|
379
|
-
headers: { // Optional
|
|
380
|
-
'x-api-key': process.env.API_KEY,
|
|
381
|
-
},
|
|
382
|
-
}
|
|
383
|
-
}
|
|
384
|
-
})
|
|
385
|
-
],
|
|
27
|
+
exporters: [new OtelExporter({ provider: { dash0: {} } })],
|
|
386
28
|
},
|
|
387
29
|
},
|
|
388
|
-
},
|
|
30
|
+
}),
|
|
389
31
|
});
|
|
390
32
|
```
|
|
391
33
|
|
|
392
|
-
##
|
|
393
|
-
|
|
394
|
-
We've made exporter dependencies optional to:
|
|
395
|
-
|
|
396
|
-
- **Reduce bundle size** - Only include what you need
|
|
397
|
-
- **Faster installs** - Fewer dependencies to download
|
|
398
|
-
- **Avoid conflicts** - Some exporters have conflicting dependencies
|
|
399
|
-
|
|
400
|
-
If you forget to install the required exporter, you'll get a helpful error message telling you exactly what to install.
|
|
401
|
-
|
|
402
|
-
## Endpoint Configuration Notes
|
|
403
|
-
|
|
404
|
-
### Protocol Requirements
|
|
405
|
-
|
|
406
|
-
- **gRPC endpoints**: Automatically append `/v1/traces` to the base endpoint
|
|
407
|
-
- **HTTP endpoints**: Most providers expect `/v1/traces` or provider-specific paths
|
|
408
|
-
- **Authentication**:
|
|
409
|
-
- HTTP uses `headers` with standard HTTP headers
|
|
410
|
-
- gRPC uses lowercase metadata keys (e.g., `authorization` instead of `Authorization`)
|
|
411
|
-
|
|
412
|
-
### Provider-Specific Endpoints
|
|
413
|
-
|
|
414
|
-
| Provider | Protocol | Endpoint Format | Notes |
|
|
415
|
-
| --------- | ------------- | ---------------------------------------------------- | ------------------ |
|
|
416
|
-
| Dash0 | gRPC | `ingress.{region}.aws.dash0.com:4317` | Get from dashboard |
|
|
417
|
-
| SigNoz | HTTP/Protobuf | `https://ingest.{region}.signoz.cloud:443/v1/traces` | Cloud hosted |
|
|
418
|
-
| New Relic | HTTP/Protobuf | `https://otlp.nr-data.net:443/v1/traces` | US region |
|
|
419
|
-
| Traceloop | HTTP/JSON | `https://api.traceloop.com/v1/traces` | Default endpoint |
|
|
420
|
-
| Laminar | HTTP/Protobuf | `https://api.lmnr.ai/v1/traces` | Default endpoint |
|
|
421
|
-
|
|
422
|
-
## Additional configuration
|
|
423
|
-
|
|
424
|
-
```typescript
|
|
425
|
-
// Main configuration interface
|
|
426
|
-
interface OtelExporterConfig {
|
|
427
|
-
// Provider configuration (discriminated union)
|
|
428
|
-
provider?: ProviderConfig;
|
|
429
|
-
|
|
430
|
-
// Export configuration
|
|
431
|
-
timeout?: number; // Export timeout in milliseconds (default: 30000)
|
|
432
|
-
batchSize?: number; // Max spans/logs per batch (default: 512)
|
|
433
|
-
|
|
434
|
-
// Per-signal toggles. All signals are enabled by default.
|
|
435
|
-
signals?: {
|
|
436
|
-
traces?: boolean;
|
|
437
|
-
logs?: boolean;
|
|
438
|
-
};
|
|
439
|
-
|
|
440
|
-
// Debug
|
|
441
|
-
logLevel?: 'debug' | 'info' | 'warn' | 'error';
|
|
442
|
-
}
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
## Batching Strategy
|
|
446
|
-
|
|
447
|
-
The OtelExporter uses OpenTelemetry's `BatchSpanProcessor` for efficient span export:
|
|
448
|
-
|
|
449
|
-
- **Automatic batching**: Spans are queued and exported in batches
|
|
450
|
-
- **Default batch size**: 512 spans (configurable via `batchSize`)
|
|
451
|
-
- **Export interval**: Every 5 seconds or when batch is full
|
|
452
|
-
- **Queue size**: Up to 2048 spans queued in memory
|
|
453
|
-
- **High-throughput support**: Handles large volumes of spans efficiently
|
|
454
|
-
|
|
455
|
-
This approach ensures:
|
|
456
|
-
|
|
457
|
-
- Efficient network usage (fewer HTTP/gRPC calls)
|
|
458
|
-
- Better performance under load
|
|
459
|
-
- Automatic retry with backoff
|
|
460
|
-
- Proper trace context propagation across all spans in a trace
|
|
461
|
-
|
|
462
|
-
## OpenTelemetry Semantic Conventions
|
|
463
|
-
|
|
464
|
-
This exporter follows the [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) to ensure compatibility with observability platforms.
|
|
465
|
-
|
|
466
|
-
### Span Naming
|
|
467
|
-
|
|
468
|
-
Spans are named following OTEL conventions:
|
|
469
|
-
|
|
470
|
-
- **LLM Operations**: `chat {model}` or `tool_selection {model}`
|
|
471
|
-
- **Tool Execution**: `tool.execute {tool_name}`
|
|
472
|
-
- **Agent Runs**: `invoke_agent {agent_name}`
|
|
473
|
-
- **Workflow Runs**: `workflow.{workflow_id}`
|
|
474
|
-
|
|
475
|
-
### Attributes
|
|
476
|
-
|
|
477
|
-
The exporter maps Mastra's tracing data to OTEL-compliant attributes:
|
|
478
|
-
|
|
479
|
-
#### Core Attributes
|
|
480
|
-
|
|
481
|
-
- `gen_ai.operation.name` - Operation type (chat, tool.execute, agent.run, workflow.run)
|
|
482
|
-
- `gen_ai.provider.name` - AI provider (openai, anthropic, etc.)
|
|
483
|
-
- `gen_ai.request.model` - Model identifier
|
|
484
|
-
- `gen_ai.conversation.id` - Conversation/thread identifier, emitted on every span in a run (agent, model generation, tool, MCP tool, workflow) when a thread id is present
|
|
34
|
+
## Documentation
|
|
485
35
|
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
- `gen_ai.usage.input_tokens` - Number of input tokens
|
|
489
|
-
- `gen_ai.usage.output_tokens` - Number of output tokens
|
|
490
|
-
- `gen_ai.usage.total_tokens` - Total token count
|
|
491
|
-
- `gen_ai.request.temperature` - Sampling temperature
|
|
492
|
-
- `gen_ai.request.max_tokens` - Maximum tokens to generate
|
|
493
|
-
- `gen_ai.request.top_p` - Top-p sampling parameter
|
|
494
|
-
- `gen_ai.request.top_k` - Top-k sampling parameter
|
|
495
|
-
- `gen_ai.response.finish_reasons` - Reason for completion
|
|
496
|
-
- `gen_ai.response.model` - Actual model used in response (may differ from request)
|
|
497
|
-
- `gen_ai.response.id` - Unique response identifier
|
|
498
|
-
- `gen_ai.prompt` - Input prompt (for Model spans)
|
|
499
|
-
- `gen_ai.completion` - Model output (for Model spans)
|
|
500
|
-
- `server.address` - Server address for the model endpoint
|
|
501
|
-
- `server.port` - Server port for the model endpoint
|
|
502
|
-
|
|
503
|
-
#### Tool Attributes
|
|
504
|
-
|
|
505
|
-
- `gen_ai.tool.name` - Tool identifier
|
|
506
|
-
- `gen_ai.tool.description` - Tool description
|
|
507
|
-
- `gen_ai.tool.success` - Whether tool execution succeeded
|
|
508
|
-
- `gen_ai.tool.input` - Tool input parameters
|
|
509
|
-
- `gen_ai.tool.output` - Tool execution result
|
|
510
|
-
|
|
511
|
-
#### Agent & Workflow Attributes
|
|
512
|
-
|
|
513
|
-
- `gen_ai.agent.id` - Agent identifier
|
|
514
|
-
- `gen_ai.agent.name` - Human-readable agent name
|
|
515
|
-
- `agent.id` - Agent identifier (also included for compatibility)
|
|
516
|
-
- `agent.max_steps` - Maximum agent steps
|
|
517
|
-
- `workflow.id` - Workflow identifier
|
|
518
|
-
- `workflow.status` - Workflow execution status
|
|
519
|
-
|
|
520
|
-
#### Error Attributes
|
|
521
|
-
|
|
522
|
-
- `error` - Boolean indicating error occurred
|
|
523
|
-
- `error.type` - Error identifier
|
|
524
|
-
- `error.message` - Error description
|
|
525
|
-
- `error.domain` - Error domain/category
|
|
526
|
-
|
|
527
|
-
### Opt-In Content Attributes
|
|
528
|
-
|
|
529
|
-
For enhanced observability, you can enable additional content attributes that capture detailed message data. These attributes may contain sensitive information and should only be enabled with proper consent and security considerations.
|
|
530
|
-
|
|
531
|
-
To enable content attributes:
|
|
532
|
-
|
|
533
|
-
```typescript
|
|
534
|
-
new OtelExporter({
|
|
535
|
-
provider: {/* your provider config */},
|
|
536
|
-
genAiConventions: {
|
|
537
|
-
includeContentAttributes: true, // Default: false
|
|
538
|
-
},
|
|
539
|
-
});
|
|
540
|
-
```
|
|
541
|
-
|
|
542
|
-
When enabled, the following additional attributes are captured:
|
|
543
|
-
|
|
544
|
-
#### Model Content Attributes
|
|
545
|
-
|
|
546
|
-
- `gen_ai.input.messages` - Structured input messages in OpenTelemetry format
|
|
547
|
-
- `gen_ai.output.messages` - Structured output messages in OpenTelemetry format
|
|
548
|
-
|
|
549
|
-
These attributes convert Mastra's message format to the OpenTelemetry GenAI standard message schema, providing detailed conversation history and tool interactions.
|
|
550
|
-
|
|
551
|
-
#### Agent Content Attributes
|
|
552
|
-
|
|
553
|
-
- `gen_ai.system_instructions` - Agent system instructions/prompts
|
|
554
|
-
|
|
555
|
-
**Privacy Considerations:**
|
|
556
|
-
|
|
557
|
-
- These attributes may contain user data, prompts, and model responses
|
|
558
|
-
- Only enable in environments where data privacy and compliance requirements are met
|
|
559
|
-
- Consider using span processors to filter sensitive data before export
|
|
560
|
-
- Review your organization's data retention and privacy policies before enabling
|
|
561
|
-
|
|
562
|
-
## Troubleshooting
|
|
563
|
-
|
|
564
|
-
### Missing Dependency Error
|
|
565
|
-
|
|
566
|
-
If you forget to install the required exporter package, you'll get a clear error message:
|
|
567
|
-
|
|
568
|
-
```
|
|
569
|
-
HTTP/Protobuf exporter is not installed (required for signoz).
|
|
570
|
-
To use HTTP/Protobuf export, install the required package:
|
|
571
|
-
|
|
572
|
-
npm install @opentelemetry/exporter-trace-otlp-proto
|
|
573
|
-
# or
|
|
574
|
-
pnpm add @opentelemetry/exporter-trace-otlp-proto
|
|
575
|
-
# or
|
|
576
|
-
yarn add @opentelemetry/exporter-trace-otlp-proto
|
|
577
|
-
```
|
|
36
|
+
- [@mastra/otel-exporter documentation](https://mastra.ai/integrations/observability/opentelemetry)
|
|
578
37
|
|
|
579
|
-
|
|
38
|
+
## Changelog
|
|
580
39
|
|
|
581
|
-
|
|
582
|
-
2. **Multiple exporters needed**: If switching between providers, you may need multiple exporters installed
|
|
583
|
-
3. **Bundle size concerns**: Only install the exporters you actually use
|
|
40
|
+
See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/observability/otel-exporter/CHANGELOG.md) for version history and release notes.
|
|
584
41
|
|
|
585
|
-
##
|
|
42
|
+
## Support
|
|
586
43
|
|
|
587
|
-
|
|
44
|
+
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.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"gen-ai-messages.d.ts","sourceRoot":"","sources":["../src/gen-ai-messages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oCAAoC,
|
|
1
|
+
{"version":3,"file":"gen-ai-messages.d.ts","sourceRoot":"","sources":["../src/gen-ai-messages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oCAAoC,sBAAuB,MAAM,KAAG,MAyEhF,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"span-converter.d.ts","sourceRoot":"","sources":["../src/span-converter.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,QAAQ,EAA8B,MAAM,oBAAoB,CAAC;AAM1E,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,+BAA+B,CAAC;AAU9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG,eAAe,CAAC;AAQzC,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,KAAK,CAAC,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAgB;IACpC,OAAO,CAAC,MAAM,CAAa;
|
|
1
|
+
{"version":3,"file":"span-converter.d.ts","sourceRoot":"","sources":["../src/span-converter.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,QAAQ,EAA8B,MAAM,oBAAoB,CAAC;AAM1E,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,+BAA+B,CAAC;AAU9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG,eAAe,CAAC;AAQzC,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,KAAK,CAAC,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAgB;IACpC,OAAO,CAAC,MAAM,CAAa;IAE3B,YACmB,MAAM,EAAE;QACvB,MAAM,EAAE,UAAU,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,kBAAkB,CAAC;KAC7B,EAGF;IAED;;;OAGG;YACW,YAAY;IAmC1B;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CA8E9D;CACF;AAeD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CASpD"}
|
package/dist/tracing.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EACR,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAkBrD,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAiErE,qBAAa,YAAa,SAAQ,YAAY;IAC5C,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,mBAAmB,CAAC,CAA8B;IAG1D,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,QAAQ,CAAC,CAAe;IAGhC,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,UAAU,CAAC,CAAS;IAG5B,OAAO,CAAC,cAAc,CAAC,CAAgC;IACvD,OAAO,CAAC,YAAY,CAAC,CAAS;IAI9B,OAAO,CAAC,YAAY,CAAC,CAAgB;IAErC,IAAI,SAAmB;
|
|
1
|
+
{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EACR,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAkBrD,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAiErE,qBAAa,YAAa,SAAQ,YAAY;IAC5C,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,mBAAmB,CAAC,CAA8B;IAG1D,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,QAAQ,CAAC,CAAe;IAGhC,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,UAAU,CAAC,CAAS;IAG5B,OAAO,CAAC,cAAc,CAAC,CAAgC;IACvD,OAAO,CAAC,YAAY,CAAC,CAAS;IAI9B,OAAO,CAAC,YAAY,CAAC,CAAgB;IAErC,IAAI,SAAmB;IAEvB,YAAY,MAAM,EAAE,kBAAkB,EAarC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,mBAAmB,QAGhC;IAMD,OAAO,KAAK,OAAO,GAElB;IAED;;;;;;OAMG;IAEH,OAAO,CAAC,QAAQ,CAAyF;IAEzG,OAAO,CAAC,eAAe;IAyBvB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAyBzB;;;OAGG;YACW,oBAAoB;IAoBlC;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAOnB;;;OAGG;YACW,eAAe;YA+Bf,WAAW;YA6DX,SAAS;IAmDvB,UAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBtE;IAMK,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAgD/C;IAMD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAyB3B;IAEK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB9B;CACF"}
|
package/package.json
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/otel-exporter",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.13-alpha.1",
|
|
4
4
|
"description": "OpenTelemetry observability exporter for Mastra - supports OTLP traces and logs with multiple cloud providers",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
8
8
|
"files": [
|
|
9
|
-
"dist"
|
|
10
|
-
"CHANGELOG.md"
|
|
9
|
+
"dist"
|
|
11
10
|
],
|
|
12
11
|
"exports": {
|
|
13
12
|
".": {
|
|
@@ -32,7 +31,7 @@
|
|
|
32
31
|
"@opentelemetry/sdk-trace-base": "^2.10.0",
|
|
33
32
|
"@opentelemetry/sdk-trace-node": "^2.10.0",
|
|
34
33
|
"@opentelemetry/semantic-conventions": "^1.43.0",
|
|
35
|
-
"@mastra/observability": "1.17.
|
|
34
|
+
"@mastra/observability": "1.17.5-alpha.1"
|
|
36
35
|
},
|
|
37
36
|
"optionalDependencies": {
|
|
38
37
|
"@grpc/grpc-js": "^1.14.4",
|
|
@@ -50,11 +49,11 @@
|
|
|
50
49
|
"@vitest/ui": "4.1.10",
|
|
51
50
|
"eslint": "^10.7.0",
|
|
52
51
|
"tsdown": "0.22.9",
|
|
53
|
-
"typescript": "^
|
|
52
|
+
"typescript": "^7.0.2",
|
|
54
53
|
"vitest": "4.1.10",
|
|
55
|
-
"@internal/lint": "0.0.
|
|
56
|
-
"@internal/types-builder": "0.0.
|
|
57
|
-
"@mastra/core": "1.
|
|
54
|
+
"@internal/lint": "0.0.129",
|
|
55
|
+
"@internal/types-builder": "0.0.104",
|
|
56
|
+
"@mastra/core": "1.64.0-alpha.7"
|
|
58
57
|
},
|
|
59
58
|
"peerDependencies": {
|
|
60
59
|
"@grpc/grpc-js": "^1.13.4",
|