@mastra/core 0.13.0-alpha.3 → 0.13.0

package/dist/ai-tracing/index.cjs

@@ -0,0 +1,585 @@
+'use strict';
+
+var chunk3BFAQTC3_cjs = require('../chunk-3BFAQTC3.cjs');
+var chunkYT4RGZYO_cjs = require('../chunk-YT4RGZYO.cjs');
+var chunkIDDUQR6P_cjs = require('../chunk-IDDUQR6P.cjs');
+
+// src/ai-tracing/no-op.ts
+var NoOpAISpan = class _NoOpAISpan {
+  id;
+  name;
+  type;
+  metadata;
+  trace;
+  traceId;
+  startTime;
+  endTime;
+  aiTracing;
+  constructor(options, aiTracing) {
+    this.id = "no-op";
+    this.name = options.name;
+    this.type = options.type;
+    this.metadata = options.metadata;
+    this.trace = options.parent ? options.parent.trace : this;
+    this.traceId = "no-op-trace";
+    this.startTime = /* @__PURE__ */ new Date();
+    this.aiTracing = aiTracing;
+  }
+  end() {
+  }
+  error() {
+  }
+  createChildSpan(type, name, metadata) {
+    return new _NoOpAISpan({ type, name, metadata, parent: this }, this.aiTracing);
+  }
+  update() {
+  }
+};
+
+// src/ai-tracing/types.ts
+var AISpanType = /* @__PURE__ */ ((AISpanType2) => {
+  AISpanType2["AGENT_RUN"] = "agent_run";
+  AISpanType2["GENERIC"] = "generic";
+  AISpanType2["LLM_GENERATION"] = "llm_generation";
+  AISpanType2["MCP_TOOL_CALL"] = "mcp_tool_call";
+  AISpanType2["TOOL_CALL"] = "tool_call";
+  AISpanType2["WORKFLOW_RUN"] = "workflow_run";
+  AISpanType2["WORKFLOW_STEP"] = "workflow_step";
+  return AISpanType2;
+})(AISpanType || {});
+var SamplingStrategyType = /* @__PURE__ */ ((SamplingStrategyType2) => {
+  SamplingStrategyType2["ALWAYS"] = "always";
+  SamplingStrategyType2["NEVER"] = "never";
+  SamplingStrategyType2["RATIO"] = "ratio";
+  SamplingStrategyType2["CUSTOM"] = "custom";
+  return SamplingStrategyType2;
+})(SamplingStrategyType || {});
+var AITracingEventType = /* @__PURE__ */ ((AITracingEventType2) => {
+  AITracingEventType2["SPAN_STARTED"] = "span_started";
+  AITracingEventType2["SPAN_UPDATED"] = "span_updated";
+  AITracingEventType2["SPAN_ENDED"] = "span_ended";
+  return AITracingEventType2;
+})(AITracingEventType || {});
+
+// src/ai-tracing/base.ts
+var MastraAITracing = class extends chunkYT4RGZYO_cjs.MastraBase {
+  config;
+  constructor(config) {
+    super({ component: chunkIDDUQR6P_cjs.RegisteredLogger.AI_TELEMETRY, name: config.serviceName });
+    this.config = config;
+    this.logger.debug(`AI Tracing initialized [service=${config.serviceName}] [sampling=${this.config.sampling.type}]`);
+  }
+  // ============================================================================
+  // Protected getters for clean config access
+  // ============================================================================
+  get exporters() {
+    return this.config.exporters || [];
+  }
+  get processors() {
+    return this.config.processors || [];
+  }
+  // ============================================================================
+  // Public API - Single type-safe span creation method
+  // ============================================================================
+  /**
+   * Start a new span of a specific AISpanType
+   */
+  startSpan(type, name, metadata, parent, runtimeContext, attributes) {
+    if (!this.shouldSample({ runtimeContext, attributes })) {
+      return new NoOpAISpan({ type, name, metadata, parent }, this);
+    }
+    const options = {
+      type,
+      name,
+      metadata,
+      parent
+    };
+    const span = this.createSpan(options);
+    span.trace = parent ? parent.trace : span;
+    this.wireSpanLifecycle(span);
+    this.emitSpanStarted(span);
+    return span;
+  }
+  // ============================================================================
+  // Configuration Management
+  // ============================================================================
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  // ============================================================================
+  // Plugin Access
+  // ============================================================================
+  /**
+   * Get all exporters
+   */
+  getExporters() {
+    return [...this.exporters];
+  }
+  /**
+   * Get all processors
+   */
+  getProcessors() {
+    return [...this.processors];
+  }
+  /**
+   * Get the logger instance (for exporters and other components)
+   */
+  getLogger() {
+    return this.logger;
+  }
+  // ============================================================================
+  // Span Lifecycle Management
+  // ============================================================================
+  /**
+   * Automatically wires up AI tracing lifecycle events for any span
+   * This ensures all spans emit events regardless of implementation
+   */
+  wireSpanLifecycle(span) {
+    const originalEnd = span.end.bind(span);
+    const originalUpdate = span.update.bind(span);
+    span.end = (metadata) => {
+      originalEnd(metadata);
+      this.emitSpanEnded(span);
+    };
+    span.update = (metadata) => {
+      originalUpdate(metadata);
+      this.emitSpanUpdated(span);
+    };
+  }
+  // ============================================================================
+  // Utility Methods
+  // ============================================================================
+  /**
+   * Check if an AI trace should be sampled
+   */
+  shouldSample(traceContext) {
+    const { sampling } = this.config;
+    switch (sampling.type) {
+      case "always" /* ALWAYS */:
+        return true;
+      case "never" /* NEVER */:
+        return false;
+      case "ratio" /* RATIO */:
+        if (sampling.probability === void 0 || sampling.probability < 0 || sampling.probability > 1) {
+          this.logger.warn(
+            `Invalid sampling probability: ${sampling.probability}. Expected value between 0 and 1. Defaulting to no sampling.`
+          );
+          return false;
+        }
+        return Math.random() < sampling.probability;
+      case "custom" /* CUSTOM */:
+        return sampling.sampler(traceContext);
+      default:
+        throw new Error(`Sampling strategy type not implemented: ${sampling.type}`);
+    }
+  }
+  /**
+   * Process a span through all processors
+   */
+  processSpan(span) {
+    let processedSpan = span;
+    for (const processor of this.processors) {
+      if (!processedSpan) {
+        break;
+      }
+      try {
+        processedSpan = processor.process(processedSpan);
+      } catch (error) {
+        this.logger.error(`Processor error [name=${processor.name}]`, error);
+      }
+    }
+    return processedSpan;
+  }
+  // ============================================================================
+  // Event-driven Export Methods
+  // ============================================================================
+  /**
+   * Emit a span started event
+   */
+  emitSpanStarted(span) {
+    const processedSpan = this.processSpan(span);
+    if (processedSpan) {
+      this.exportEvent({ type: "span_started" /* SPAN_STARTED */, span: processedSpan }).catch((error) => {
+        this.logger.error("Failed to export span_started event", error);
+      });
+    }
+  }
+  /**
+   * Emit a span ended event (called automatically when spans end)
+   */
+  emitSpanEnded(span) {
+    const processedSpan = this.processSpan(span);
+    if (processedSpan) {
+      this.exportEvent({ type: "span_ended" /* SPAN_ENDED */, span: processedSpan }).catch((error) => {
+        this.logger.error("Failed to export span_ended event", error);
+      });
+    }
+  }
+  /**
+   * Emit a span updated event
+   */
+  emitSpanUpdated(span) {
+    const processedSpan = this.processSpan(span);
+    if (processedSpan) {
+      this.exportEvent({ type: "span_updated" /* SPAN_UPDATED */, span: processedSpan }).catch((error) => {
+        this.logger.error("Failed to export span_updated event", error);
+      });
+    }
+  }
+  /**
+   * Export tracing event through all exporters (realtime mode)
+   */
+  async exportEvent(event) {
+    const exportPromises = this.exporters.map(async (exporter) => {
+      try {
+        if (exporter.exportEvent) {
+          await exporter.exportEvent(event);
+          this.logger.debug(`Event exported [exporter=${exporter.name}] [type=${event.type}]`);
+        }
+      } catch (error) {
+        this.logger.error(`Export error [exporter=${exporter.name}]`, error);
+      }
+    });
+    await Promise.allSettled(exportPromises);
+  }
+  // ============================================================================
+  // Lifecycle Management
+  // ============================================================================
+  /**
+   * Initialize AI tracing (called by Mastra during component registration)
+   */
+  async init() {
+    this.logger.debug(`AI Tracing initialization started [name=${this.name}]`);
+    this.logger.info(`AI Tracing initialized successfully [name=${this.name}]`);
+  }
+  /**
+   * Shutdown AI tracing and clean up resources
+   */
+  async shutdown() {
+    this.logger.debug(`AI Tracing shutdown started [name=${this.name}]`);
+    const shutdownPromises = [...this.exporters.map((e) => e.shutdown()), ...this.processors.map((p) => p.shutdown())];
+    await Promise.allSettled(shutdownPromises);
+    this.logger.info(`AI Tracing shutdown completed [name=${this.name}]`);
+  }
+};
+
+// src/ai-tracing/default.ts
+function generateSpanId() {
+  const bytes = new Uint8Array(8);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 8; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function generateTraceId() {
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+var DefaultAISpan = class {
+  id;
+  name;
+  type;
+  metadata;
+  trace;
+  traceId;
+  startTime;
+  endTime;
+  aiTracing;
+  constructor(options, aiTracing) {
+    this.id = generateSpanId();
+    this.name = options.name;
+    this.type = options.type;
+    this.metadata = options.metadata;
+    this.trace = options.parent ? options.parent.trace : this;
+    this.startTime = /* @__PURE__ */ new Date();
+    this.aiTracing = aiTracing;
+    if (!options.parent) {
+      this.traceId = generateTraceId();
+    } else {
+      this.traceId = options.parent.trace.traceId;
+    }
+  }
+  end(metadata) {
+    this.endTime = /* @__PURE__ */ new Date();
+    if (metadata) {
+      this.metadata = { ...this.metadata, ...metadata };
+    }
+  }
+  error(error, endSpan = true) {
+    const errorMetadata = error instanceof chunk3BFAQTC3_cjs.MastraError ? {
+      error: {
+        id: error.id,
+        details: error.details,
+        category: error.category,
+        domain: error.domain,
+        message: error.message
+      }
+    } : {
+      error: {
+        message: error.message
+      }
+    };
+    if (endSpan) {
+      this.end(errorMetadata);
+    } else {
+      this.update(errorMetadata);
+    }
+  }
+  createChildSpan(type, name, metadata) {
+    return this.aiTracing.startSpan(type, name, metadata, this);
+  }
+  update(metadata) {
+    this.metadata = { ...this.metadata, ...metadata };
+  }
+  async export() {
+    return JSON.stringify({
+      id: this.id,
+      metadata: this.metadata,
+      startTime: this.startTime,
+      endTime: this.endTime,
+      traceId: this.traceId
+      // OpenTelemetry trace ID
+    });
+  }
+};
+var SensitiveDataFilter = class {
+  name = "sensitive-data-filter";
+  sensitiveFields;
+  constructor(sensitiveFields) {
+    this.sensitiveFields = (sensitiveFields || [
+      "password",
+      "token",
+      "secret",
+      "key",
+      "apiKey",
+      "auth",
+      "authorization",
+      "bearer",
+      "jwt",
+      "credential",
+      "sessionId"
+    ]).map((field) => field.toLowerCase());
+  }
+  process(span) {
+    const deepFilter = (obj, seen = /* @__PURE__ */ new WeakSet()) => {
+      if (obj === null || typeof obj !== "object") {
+        return obj;
+      }
+      if (seen.has(obj)) {
+        return "[Circular Reference]";
+      }
+      seen.add(obj);
+      if (Array.isArray(obj)) {
+        return obj.map((item) => deepFilter(item, seen));
+      }
+      const filtered = {};
+      Object.keys(obj).forEach((key) => {
+        if (this.sensitiveFields.includes(key.toLowerCase())) {
+          if (obj[key] && typeof obj[key] === "object") {
+            filtered[key] = deepFilter(obj[key], seen);
+          } else {
+            filtered[key] = "[REDACTED]";
+          }
+        } else {
+          filtered[key] = deepFilter(obj[key], seen);
+        }
+      });
+      return filtered;
+    };
+    try {
+      const filteredSpan = { ...span };
+      filteredSpan.metadata = deepFilter(span.metadata);
+      return filteredSpan;
+    } catch (error) {
+      const safeSpan = { ...span };
+      safeSpan.metadata = {
+        "[FILTERING_ERROR]": "Metadata was completely redacted due to filtering error",
+        "[ERROR_MESSAGE]": error instanceof Error ? error.message : "Unknown filtering error"
+      };
+      return safeSpan;
+    }
+  }
+  async shutdown() {
+  }
+};
+var DefaultConsoleExporter = class {
+  name = "default-console";
+  logger;
+  constructor(logger) {
+    if (logger) {
+      this.logger = logger;
+    } else {
+      this.logger = new chunkIDDUQR6P_cjs.ConsoleLogger({
+        name: "default-console-exporter"
+      });
+    }
+  }
+  async exportEvent(event) {
+    const span = event.span;
+    const formatMetadata = (metadata) => {
+      try {
+        return JSON.stringify(metadata, null, 2);
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : "Unknown formatting error";
+        return `[Unable to serialize metadata: ${errMsg}]`;
+      }
+    };
+    const formatDuration = (startTime, endTime) => {
+      if (!endTime) return "N/A";
+      const duration = endTime.getTime() - startTime.getTime();
+      return `${duration}ms`;
+    };
+    switch (event.type) {
+      case "span_started" /* SPAN_STARTED */:
+        this.logger.info(`\u{1F680} SPAN_STARTED`);
+        this.logger.info(`   Type: ${span.type}`);
+        this.logger.info(`   Name: ${span.name}`);
+        this.logger.info(`   ID: ${span.id}`);
+        this.logger.info(`   Trace ID: ${span.traceId}`);
+        this.logger.info(`   Metadata: ${formatMetadata(span.metadata)}`);
+        this.logger.info("\u2500".repeat(80));
+        break;
+      case "span_ended" /* SPAN_ENDED */:
+        const duration = formatDuration(span.startTime, span.endTime);
+        this.logger.info(`\u2705 SPAN_ENDED`);
+        this.logger.info(`   Type: ${span.type}`);
+        this.logger.info(`   Name: ${span.name}`);
+        this.logger.info(`   ID: ${span.id}`);
+        this.logger.info(`   Duration: ${duration}`);
+        this.logger.info(`   Trace ID: ${span.traceId}`);
+        this.logger.info(`   Final Metadata: ${formatMetadata(span.metadata)}`);
+        this.logger.info("\u2500".repeat(80));
+        break;
+      case "span_updated" /* SPAN_UPDATED */:
+        this.logger.info(`\u{1F4DD} SPAN_UPDATED`);
+        this.logger.info(`   Type: ${span.type}`);
+        this.logger.info(`   Name: ${span.name}`);
+        this.logger.info(`   ID: ${span.id}`);
+        this.logger.info(`   Trace ID: ${span.traceId}`);
+        this.logger.info(`   Updated Metadata: ${formatMetadata(span.metadata)}`);
+        this.logger.info("\u2500".repeat(80));
+        break;
+      default:
+        throw new Error(`Tracing event type not implemented: ${event.type}`);
+    }
+  }
+  async shutdown() {
+    this.logger.info("DefaultConsoleExporter shutdown");
+  }
+};
+var aiTracingDefaultConfig = {
+  serviceName: "mastra-ai-service",
+  sampling: { type: "always" /* ALWAYS */ },
+  exporters: [new DefaultConsoleExporter()],
+  // Uses its own fallback logger
+  processors: [new SensitiveDataFilter()]
+};
+var DefaultAITracing = class extends MastraAITracing {
+  constructor(config = aiTracingDefaultConfig) {
+    super(config);
+  }
+  // ============================================================================
+  // Abstract Method Implementations
+  // ============================================================================
+  createSpan(options) {
+    return new DefaultAISpan(options, this);
+  }
+};
+
+// src/ai-tracing/registry.ts
+var AITracingRegistry = class {
+  instances = /* @__PURE__ */ new Map();
+  defaultInstance;
+  /**
+   * Register a tracing instance
+   */
+  register(name, instance, isDefault = false) {
+    this.instances.set(name, instance);
+    if (isDefault || !this.defaultInstance) {
+      this.defaultInstance = instance;
+    }
+  }
+  /**
+   * Get a tracing instance by name
+   */
+  get(name) {
+    if (name) {
+      return this.instances.get(name);
+    }
+    return this.defaultInstance;
+  }
+  /**
+   * Unregister a tracing instance
+   */
+  unregister(name) {
+    const instance = this.instances.get(name);
+    if (instance && instance === this.defaultInstance) {
+      const remaining = Array.from(this.instances.values()).filter((i) => i !== instance);
+      this.defaultInstance = remaining[0];
+    }
+    return this.instances.delete(name);
+  }
+  /**
+   * Clear all instances
+   */
+  clear() {
+    this.instances.clear();
+    this.defaultInstance = void 0;
+  }
+  /**
+   * Get all registered instances
+   */
+  getAll() {
+    return new Map(this.instances);
+  }
+};
+var aiTracingRegistry = new AITracingRegistry();
+function registerAITracing(name, instance, isDefault = false) {
+  aiTracingRegistry.register(name, instance, isDefault);
+}
+function getAITracing(name) {
+  return aiTracingRegistry.get(name);
+}
+function unregisterAITracing(name) {
+  return aiTracingRegistry.unregister(name);
+}
+function clearAITracingRegistry() {
+  aiTracingRegistry.clear();
+}
+function hasAITracing(name) {
+  const tracing = getAITracing(name);
+  if (!tracing) return false;
+  const config = tracing.getConfig();
+  const sampling = config.sampling;
+  return sampling.type !== "never" /* NEVER */;
+}
+
+exports.AISpanType = AISpanType;
+exports.AITracingEventType = AITracingEventType;
+exports.DefaultAITracing = DefaultAITracing;
+exports.DefaultConsoleExporter = DefaultConsoleExporter;
+exports.MastraAITracing = MastraAITracing;
+exports.SamplingStrategyType = SamplingStrategyType;
+exports.SensitiveDataFilter = SensitiveDataFilter;
+exports.aiTracingDefaultConfig = aiTracingDefaultConfig;
+exports.clearAITracingRegistry = clearAITracingRegistry;
+exports.getAITracing = getAITracing;
+exports.hasAITracing = hasAITracing;
+exports.registerAITracing = registerAITracing;
+exports.unregisterAITracing = unregisterAITracing;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map