@mastra/otel-exporter 0.0.0-suspendRuntimeContextTypeFix-20250930142630 → 0.0.0-top-level-fix-20251211111608

package/README.md

@@ -1,6 +1,6 @@
-# OtelExporter - OpenTelemetry AI Tracing Exporter
+# OtelExporter - OpenTelemetry Tracing Exporter
 
-Export Mastra AI traces to any OpenTelemetry-compatible observability platform.
+Export Mastra traces to any OpenTelemetry-compatible observability platform.
 
 > **⚠️ Important:** This package requires you to install an additional exporter package based on your provider. Each provider section below includes the specific installation command.
 
@@ -19,7 +19,7 @@ npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
-import { Mastra } from '@mastra/core';
+import { Mastra } from '@mastra/core/mastra';
 
 const mastra = new Mastra({
   ...,
@@ -58,7 +58,7 @@ npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
-import { Mastra } from '@mastra/core';
+import { Mastra } from '@mastra/core/mastra';
 
 const mastra = new Mastra({
   ...,
@@ -95,7 +95,7 @@ npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
-import { Mastra } from '@mastra/core';
+import { Mastra } from '@mastra/core/mastra';
 
 const mastra = new Mastra({
   ...,
@@ -132,7 +132,7 @@ npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
-import { Mastra } from '@mastra/core';
+import { Mastra } from '@mastra/core/mastra';
 
 const mastra = new Mastra({
   ...,
@@ -169,7 +169,7 @@ npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
-import { Mastra } from '@mastra/core';
+import { Mastra } from '@mastra/core/mastra';
 
 const mastra = new Mastra({
   ...,
@@ -208,7 +208,7 @@ npm install @mastra/otel-exporter @opentelemetry/exporter-zipkin
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
-import { Mastra } from '@mastra/core';
+import { Mastra } from '@mastra/core/mastra';
 
 const mastra = new Mastra({
   ...,
@@ -258,7 +258,7 @@ Most providers recommend HTTP/Protobuf for production use.
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
-import { Mastra } from '@mastra/core';
+import { Mastra } from '@mastra/core/mastra';
 
 const mastra = new Mastra({
   ...,
@@ -359,17 +359,17 @@ 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
 
-The exporter maps Mastra's AI tracing data to OTEL-compliant attributes:
+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 AI 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.prompt` - Input prompt (for LLM spans)
-- `gen_ai.completion` - Model output (for LLM spans)
+- `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 AI 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 AI 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,40 @@
+/**
+ * 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, UsageStats } from '@mastra/core/observability';
+import type { Attributes } from '@opentelemetry/api';
+import { ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS } from '@opentelemetry/semantic-conventions/incubating';
+/**
+ * Token usage attributes following OTel GenAI semantic conventions.
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+ */
+export interface OtelUsageMetrics {
+    [ATTR_GEN_AI_USAGE_INPUT_TOKENS]?: number;
+    [ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]?: number;
+    'gen_ai.usage.reasoning_tokens'?: number;
+    'gen_ai.usage.cached_input_tokens'?: number;
+    'gen_ai.usage.cache_write_tokens'?: number;
+    'gen_ai.usage.audio_input_tokens'?: number;
+    'gen_ai.usage.audio_output_tokens'?: number;
+}
+/**
+ * Formats UsageStats to OTel GenAI semantic convention attributes.
+ */
+export declare function formatUsageMetrics(usage?: UsageStats): OtelUsageMetrics;
+/**
+ * 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,EAIf,UAAU,EAEX,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAgBL,8BAA8B,EAC9B,+BAA+B,EAYhC,MAAM,gDAAgD,CAAC;AAGxD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,8BAA8B,CAAC,CAAC,EAAE,MAAM,CAAC;IAC1C,CAAC,+BAA+B,CAAC,CAAC,EAAE,MAAM,CAAC;IAC3C,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,kCAAkC,CAAC,EAAE,MAAM,CAAC;IAC5C,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,kCAAkC,CAAC,EAAE,MAAM,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAqCvE;AAuDD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAUzD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,CA8K/D"}