@mastra/otel-exporter 1.0.0-beta.1 → 1.0.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @mastra/otel-exporter
 
+## 1.0.0-beta.3
+
+### Patch Changes
+
+- Updated OtelExporters, Bridge, and Arize packages to better implement GenAI v1.38.0 Otel Semantic Conventions. See: ([#10591](https://github.com/mastra-ai/mastra/pull/10591))
+  https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/gen-ai/README.md
+
+- feat(observability): Add tags support to OtelExporter, OtelBridge, and ArizeExporter ([#10843](https://github.com/mastra-ai/mastra/pull/10843))
+
+  This change adds support for the `tracingOptions.tags` feature to the OpenTelemetry-based exporters and bridge. Tags are now included as span attributes when present on root spans, following the same pattern as Braintrust and Langfuse exporters.
+
+  **Changes:**
+  - **OtelExporter**: Tags are now included as `mastra.tags` span attribute for root spans
+  - **OtelBridge**: Tags flow through the SpanConverter and are included in native OTEL spans as `mastra.tags`
+  - **ArizeExporter**: Tags are mapped to the native OpenInference `tag.tags` semantic convention
+
+  **Implementation Details:**
+  - Tags are only included on root spans (by design)
+  - Tags are stored as JSON-stringified arrays for maximum backend compatibility (many OTEL backends have limited native array support)
+  - Empty or undefined tag arrays are not included in span attributes
+
+  **Usage:**
+
+  ```typescript
+  const result = await agent.generate({
+    messages: [{ role: 'user', content: 'Hello' }],
+    tracingOptions: {
+      tags: ['production', 'experiment-v2'],
+    },
+  });
+  ```
+
+  Fixes #10771
+
+- Updated dependencies [[`6c59a40`](https://github.com/mastra-ai/mastra/commit/6c59a40e0ad160467bd13d63a8a287028d75b02d), [`3076c67`](https://github.com/mastra-ai/mastra/commit/3076c6778b18988ae7d5c4c5c466366974b2d63f), [`85d7ee1`](https://github.com/mastra-ai/mastra/commit/85d7ee18ff4e14d625a8a30ec6656bb49804989b), [`c6c1092`](https://github.com/mastra-ai/mastra/commit/c6c1092f8fbf76109303f69e000e96fd1960c4ce), [`81dc110`](https://github.com/mastra-ai/mastra/commit/81dc11008d147cf5bdc8996ead1aa61dbdebb6fc), [`7aedb74`](https://github.com/mastra-ai/mastra/commit/7aedb74883adf66af38e270e4068fd42e7a37036), [`8f02d80`](https://github.com/mastra-ai/mastra/commit/8f02d800777397e4b45d7f1ad041988a8b0c6630), [`d7aad50`](https://github.com/mastra-ai/mastra/commit/d7aad501ce61646b76b4b511e558ac4eea9884d0), [`ce0a73a`](https://github.com/mastra-ai/mastra/commit/ce0a73abeaa75b10ca38f9e40a255a645d50ebfb), [`a02e542`](https://github.com/mastra-ai/mastra/commit/a02e542d23179bad250b044b17ff023caa61739f), [`a372c64`](https://github.com/mastra-ai/mastra/commit/a372c640ad1fd12e8f0613cebdc682fc156b4d95), [`8846867`](https://github.com/mastra-ai/mastra/commit/8846867ffa9a3746767618e314bebac08eb77d87), [`0bada2f`](https://github.com/mastra-ai/mastra/commit/0bada2f2c1234932cf30c1c47a719ffb64b801c5), [`42a42cf`](https://github.com/mastra-ai/mastra/commit/42a42cf3132b9786feecbb8c13c583dce5b0e198), [`cc60ff6`](https://github.com/mastra-ai/mastra/commit/cc60ff616541a3b0fb531a7e469bf9ae7bb90528), [`ae08bf0`](https://github.com/mastra-ai/mastra/commit/ae08bf0ebc6a4e4da992b711c4a389c32ba84cf4), [`21735a7`](https://github.com/mastra-ai/mastra/commit/21735a7ef306963554a69a89b44f06c3bcd85141), [`1d877b8`](https://github.com/mastra-ai/mastra/commit/1d877b8d7b536a251c1a7a18db7ddcf4f68d6f8b)]:
+  - @mastra/observability@1.0.0-beta.3
+  - @mastra/core@1.0.0-beta.7
+
+## 1.0.0-beta.2
+
+### Minor Changes
+
+- Adds bidirectional integration with otel tracing via a new @mastra/otel-bridge package. ([#10482](https://github.com/mastra-ai/mastra/pull/10482))
+
+### Patch Changes
+
+- Updated dependencies [[`ac0d2f4`](https://github.com/mastra-ai/mastra/commit/ac0d2f4ff8831f72c1c66c2be809706d17f65789), [`1a0d3fc`](https://github.com/mastra-ai/mastra/commit/1a0d3fc811482c9c376cdf79ee615c23bae9b2d6), [`85a628b`](https://github.com/mastra-ai/mastra/commit/85a628b1224a8f64cd82ea7f033774bf22df7a7e), [`c237233`](https://github.com/mastra-ai/mastra/commit/c23723399ccedf7f5744b3f40997b79246bfbe64), [`15f9e21`](https://github.com/mastra-ai/mastra/commit/15f9e216177201ea6e3f6d0bfb063fcc0953444f), [`ff94dea`](https://github.com/mastra-ai/mastra/commit/ff94dea935f4e34545c63bcb6c29804732698809), [`5b2ff46`](https://github.com/mastra-ai/mastra/commit/5b2ff4651df70c146523a7fca773f8eb0a2272f8), [`db41688`](https://github.com/mastra-ai/mastra/commit/db4168806d007417e2e60b4f68656dca4e5f40c9), [`103586c`](https://github.com/mastra-ai/mastra/commit/103586cb23ebcd2466c7f68a71674d37cc10e263), [`5ca599d`](https://github.com/mastra-ai/mastra/commit/5ca599d0bb59a1595f19f58473fcd67cc71cef58), [`bff1145`](https://github.com/mastra-ai/mastra/commit/bff114556b3cbadad9b2768488708f8ad0e91475), [`5c8ca24`](https://github.com/mastra-ai/mastra/commit/5c8ca247094e0cc2cdbd7137822fb47241f86e77), [`e191844`](https://github.com/mastra-ai/mastra/commit/e1918444ca3f80e82feef1dad506cd4ec6e2875f), [`22553f1`](https://github.com/mastra-ai/mastra/commit/22553f11c63ee5e966a9c034a349822249584691), [`7237163`](https://github.com/mastra-ai/mastra/commit/72371635dbf96a87df4b073cc48fc655afbdce3d), [`2500740`](https://github.com/mastra-ai/mastra/commit/2500740ea23da067d6e50ec71c625ab3ce275e64), [`873ecbb`](https://github.com/mastra-ai/mastra/commit/873ecbb517586aa17d2f1e99283755b3ebb2863f), [`4f9bbe5`](https://github.com/mastra-ai/mastra/commit/4f9bbe5968f42c86f4930b8193de3c3c17e5bd36), [`02e51fe`](https://github.com/mastra-ai/mastra/commit/02e51feddb3d4155cfbcc42624fd0d0970d032c0), [`8f3fa3a`](https://github.com/mastra-ai/mastra/commit/8f3fa3a652bb77da092f913ec51ae46e3a7e27dc), [`cd29ad2`](https://github.com/mastra-ai/mastra/commit/cd29ad23a255534e8191f249593849ed29160886), [`bdf4d8c`](https://github.com/mastra-ai/mastra/commit/bdf4d8cdc656d8a2c21d81834bfa3bfa70f56c16), [`854e3da`](https://github.com/mastra-ai/mastra/commit/854e3dad5daac17a91a20986399d3a51f54bf68b), [`ce18d38`](https://github.com/mastra-ai/mastra/commit/ce18d38678c65870350d123955014a8432075fd9), [`cccf9c8`](https://github.com/mastra-ai/mastra/commit/cccf9c8b2d2dfc1a5e63919395b83d78c89682a0), [`61a5705`](https://github.com/mastra-ai/mastra/commit/61a570551278b6743e64243b3ce7d73de915ca8a), [`db70a48`](https://github.com/mastra-ai/mastra/commit/db70a48aeeeeb8e5f92007e8ede52c364ce15287), [`f0fdc14`](https://github.com/mastra-ai/mastra/commit/f0fdc14ee233d619266b3d2bbdeea7d25cfc6d13), [`db18bc9`](https://github.com/mastra-ai/mastra/commit/db18bc9c3825e2c1a0ad9a183cc9935f6691bfa1), [`9b37b56`](https://github.com/mastra-ai/mastra/commit/9b37b565e1f2a76c24f728945cc740c2b09be9da), [`41a23c3`](https://github.com/mastra-ai/mastra/commit/41a23c32f9877d71810f37e24930515df2ff7a0f), [`5d171ad`](https://github.com/mastra-ai/mastra/commit/5d171ad9ef340387276b77c2bb3e83e83332d729), [`f03ae60`](https://github.com/mastra-ai/mastra/commit/f03ae60500fe350c9d828621006cdafe1975fdd8), [`d1e74a0`](https://github.com/mastra-ai/mastra/commit/d1e74a0a293866dece31022047f5dbab65a304d0), [`39e7869`](https://github.com/mastra-ai/mastra/commit/39e7869bc7d0ee391077ce291474d8a84eedccff), [`5761926`](https://github.com/mastra-ai/mastra/commit/57619260c4a2cdd598763abbacd90de594c6bc76), [`c900fdd`](https://github.com/mastra-ai/mastra/commit/c900fdd504c41348efdffb205cfe80d48c38fa33), [`604a79f`](https://github.com/mastra-ai/mastra/commit/604a79fecf276e26a54a3fe01bb94e65315d2e0e), [`887f0b4`](https://github.com/mastra-ai/mastra/commit/887f0b4746cdbd7cb7d6b17ac9f82aeb58037ea5), [`2562143`](https://github.com/mastra-ai/mastra/commit/256214336b4faa78646c9c1776612393790d8784), [`ef11a61`](https://github.com/mastra-ai/mastra/commit/ef11a61920fa0ed08a5b7ceedd192875af119749)]:
+  - @mastra/core@1.0.0-beta.6
+  - @mastra/observability@1.0.0-beta.2
+
 ## 1.0.0-beta.1
 
 ### Patch Changes

package/README.md

@@ -359,7 +359,7 @@ Spans are named following OTEL conventions:
 
 - **LLM Operations**: `chat {model}` or `tool_selection {model}`
 - **Tool Execution**: `tool.execute {tool_name}`
-- **Agent Runs**: `agent.{agent_id}`
+- **Agent Runs**: `invoke_agent {agent_name}`
 - **Workflow Runs**: `workflow.{workflow_id}`
 
 ### Attributes
@@ -369,7 +369,7 @@ The exporter maps Mastra's tracing data to OTEL-compliant attributes:
 #### Core Attributes
 
 - `gen_ai.operation.name` - Operation type (chat, tool.execute, agent.run, workflow.run)
-- `gen_ai.system` - AI provider (openai, anthropic, etc.)
+- `gen_ai.provider.name` - AI provider (openai, anthropic, etc.)
 - `gen_ai.request.model` - Model identifier
 
 #### LLM-Specific Attributes
@@ -382,8 +382,12 @@ The exporter maps Mastra's tracing data to OTEL-compliant attributes:
 - `gen_ai.request.top_p` - Top-p sampling parameter
 - `gen_ai.request.top_k` - Top-k sampling parameter
 - `gen_ai.response.finish_reasons` - Reason for completion
+- `gen_ai.response.model` - Actual model used in response (may differ from request)
+- `gen_ai.response.id` - Unique response identifier
 - `gen_ai.prompt` - Input prompt (for Model spans)
 - `gen_ai.completion` - Model output (for Model spans)
+- `server.address` - Server address for the model endpoint
+- `server.port` - Server port for the model endpoint
 
 #### Tool Attributes
 
@@ -395,7 +399,10 @@ The exporter maps Mastra's tracing data to OTEL-compliant attributes:
 
 #### Agent & Workflow Attributes
 
-- `agent.id` - Agent identifier
+- `gen_ai.agent.id` - Agent identifier
+- `gen_ai.agent.name` - Human-readable agent name
+- `gen_ai.conversation.id` - Conversation/thread/session identifier
+- `agent.id` - Agent identifier (also included for compatibility)
 - `agent.max_steps` - Maximum agent steps
 - `workflow.id` - Workflow identifier
 - `workflow.status` - Workflow execution status
@@ -407,6 +414,43 @@ The exporter maps Mastra's tracing data to OTEL-compliant attributes:
 - `error.message` - Error description
 - `error.domain` - Error domain/category
 
+### Opt-In Content Attributes
+
+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.
+
+To enable content attributes:
+
+```typescript
+new OtelExporter({
+  provider: {
+    /* your provider config */
+  },
+  genAiConventions: {
+    includeContentAttributes: true, // Default: false
+  },
+});
+```
+
+When enabled, the following additional attributes are captured:
+
+#### Model Content Attributes
+
+- `gen_ai.input.messages` - Structured input messages in OpenTelemetry format
+- `gen_ai.output.messages` - Structured output messages in OpenTelemetry format
+
+These attributes convert Mastra's message format to the OpenTelemetry GenAI standard message schema, providing detailed conversation history and tool interactions.
+
+#### Agent Content Attributes
+
+- `gen_ai.system_instructions` - Agent system instructions/prompts
+
+**Privacy Considerations:**
+
+- These attributes may contain user data, prompts, and model responses
+- Only enable in environments where data privacy and compliance requirements are met
+- Consider using span processors to filter sensitive data before export
+- Review your organization's data retention and privacy policies before enabling
+
 ## Troubleshooting
 
 ### Missing Dependency Error

package/dist/gen-ai-messages.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Utilities for converting Mastra messages to OpenTelemetry gen_ai message format
+ * Based on OpenTelemetry GenAI semantic conventions
+ * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-input-messages
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-input-messages.json
+ */
+/**
+ * Convert an Input/Output string from a MastraSpan into a jsonified string that adheres to
+ * OpenTelemetry gen_ai.input.messages and gen_ai.output.messages schema.
+ * If parsing fails at any step, the original inputOutputString is returned unmodified.
+ *
+ * This conversion is best effort; It assumes a consistent shape for mastra messages, and converts
+ * into the gen_ai input and output schemas as of October 20th, 2025.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-input-messages
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-input-messages.json
+ * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/#gen-ai-output-messages
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-output-messages.json
+ *
+ * @param inputOutputString a jsonified string that contains messages adhering to what appears to be
+ * Mastra's message shape.
+ * @returns a jsonified string that contains messages adhering to the OpenTelemetry gen_ai.input.messages and gen_ai.output.messages schema.
+ * If parsing fails at any step, the original inputOutputString is returned unmodified.
+ */
+export declare const convertMastraMessagesToGenAIMessages: (inputOutputString: string) => string;
+//# sourceMappingURL=gen-ai-messages.d.ts.map

package/dist/gen-ai-messages.d.ts.map

@@ -0,0 +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,GAAI,mBAAmB,MAAM,KAAG,MAyEhF,CAAC"}

package/dist/gen-ai-semantics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Utilities for converting Mastra Spans to OTel Spans
+ * with Semantic conventions for generative AI systems
+ * @see https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/gen-ai/README.md
+ * @see https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/gen-ai/gen-ai-events.md
+ * @see https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/gen-ai/gen-ai-spans.md
+ * @see https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/gen-ai/gen-ai-agent-spans.md
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/non-normative/examples-llm-calls/
+ * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
+ */
+import type { AnyExportedSpan } from '@mastra/core/observability';
+import type { Attributes } from '@opentelemetry/api';
+/**
+ * Get an OTEL-compliant span name based on span type and attributes
+ */
+export declare function getSpanName(span: AnyExportedSpan): string;
+/**
+ * Gets OpenTelemetry attributes from Mastra Span
+ * Following OTEL Semantic Conventions for GenAI
+ */
+export declare function getAttributes(span: AnyExportedSpan): Attributes;
+//# sourceMappingURL=gen-ai-semantics.d.ts.map

package/dist/gen-ai-semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gen-ai-semantics.d.ts","sourceRoot":"","sources":["../src/gen-ai-semantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAEV,eAAe,EAKhB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAsFrD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAUzD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,CAwL/D"}