@introspection-sdk/introspection-node 0.4.2 → 0.4.4

package/src/otel/logs.ts

@@ -0,0 +1,394 @@
+/**
+ * IntrospectionLogs — OTel logs exporter for Introspection.
+ *
+ * Owns its own `LoggerProvider` and OTLP log exporter. Provides `track`,
+ * `feedback`, `identify`, and async-context helpers (`withBaggage`,
+ * `withAgent`, `withConversation`, etc.) that propagate identity and
+ * gen_ai context through OpenTelemetry baggage.
+ *
+ * Fully independent of {@link IntrospectionClient}. Construct it directly
+ * with the OTel peer dependencies installed.
+ *
+ * @example
+ * ```typescript
+ * import { IntrospectionLogs } from "@introspection-sdk/introspection-node/otel";
+ *
+ * const logs = new IntrospectionLogs({
+ *   token: process.env.INTROSPECTION_TOKEN,
+ *   serviceName: "my-service",
+ * });
+ *
+ * await logs.withAgent("support-bot", "agent_1", () =>
+ *   logs.withConversation("conv_123", undefined, () => {
+ *     logs.feedback("thumbs_up", { comments: "Great answer" });
+ *   }),
+ * );
+ *
+ * await logs.shutdown();
+ * ```
+ */
+
+import { SeverityNumber, type LogAttributes } from "@opentelemetry/api-logs";
+import {
+  LoggerProvider,
+  BatchLogRecordProcessor,
+} from "@opentelemetry/sdk-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
+import {
+  resourceFromAttributes,
+  defaultResource,
+} from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { propagation, context } from "@opentelemetry/api";
+
+import { logger as sdkLogger, withOtlpHttpsProxy } from "../utils.js";
+import { VERSION } from "../version.js";
+import {
+  generateEventId,
+  type FeedbackOptions,
+  type UserTraits,
+  type GenAiContext,
+  type IdentityContext,
+} from "../types.js";
+
+/**
+ * Configuration for {@link IntrospectionLogs}.
+ */
+export interface IntrospectionLogsOptions {
+  /** Authentication token (env: INTROSPECTION_TOKEN). */
+  token?: string;
+  /** Service name for telemetry (env: INTROSPECTION_SERVICE_NAME, default: "introspection-client"). */
+  serviceName?: string;
+  /**
+   * Base URL for the OTLP collector (env: INTROSPECTION_BASE_OTEL_URL,
+   * default: "https://otel.introspection.dev").
+   */
+  baseOtelUrl?: string;
+  /** Additional HTTP headers to include in exporter requests. */
+  additionalHeaders?: Record<string, string>;
+  /** Flush interval in milliseconds (default: 5000). */
+  flushInterval?: number;
+  /** Maximum queue size before auto-flush (default: 100). */
+  maxBatchSize?: number;
+}
+
+export class IntrospectionLogs {
+  private loggerProvider: LoggerProvider;
+  private otelLogger: ReturnType<LoggerProvider["getLogger"]>;
+  private userId: string | undefined;
+  private anonymousId: string | undefined;
+  private traits: Record<string, unknown> = {};
+
+  constructor(options: IntrospectionLogsOptions = {}) {
+    const token = options.token || process.env.INTROSPECTION_TOKEN || "";
+    const serviceName =
+      options.serviceName ||
+      process.env.INTROSPECTION_SERVICE_NAME ||
+      "introspection-client";
+    const baseOtelUrl =
+      options.baseOtelUrl ||
+      process.env.INTROSPECTION_BASE_OTEL_URL ||
+      "https://otel.introspection.dev";
+
+    if (!token) {
+      sdkLogger.warn(
+        "IntrospectionLogs: No token provided. Events will not be sent.",
+      );
+    }
+
+    // Construct endpoint URL for logs.
+    const endpoint = baseOtelUrl.endsWith("/v1/logs")
+      ? baseOtelUrl
+      : `${baseOtelUrl.replace(/\/$/, "")}/v1/logs`;
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${token}`,
+      ...(options.additionalHeaders || {}),
+    };
+
+    const exporter = new OTLPLogExporter(
+      withOtlpHttpsProxy({
+        url: endpoint,
+        headers,
+      }),
+    );
+
+    const processor = new BatchLogRecordProcessor(exporter, {
+      maxQueueSize: options.maxBatchSize ?? 100,
+      scheduledDelayMillis: options.flushInterval ?? 5000,
+    });
+
+    const baseResource = defaultResource();
+    const introspectionResource = resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: serviceName,
+    });
+    const resource = baseResource.merge(introspectionResource);
+
+    this.loggerProvider = new LoggerProvider({
+      resource,
+      processors: [processor],
+    });
+
+    this.otelLogger = this.loggerProvider.getLogger(
+      "@introspection-sdk/introspection-node",
+      VERSION,
+    );
+
+    sdkLogger.info(
+      `IntrospectionLogs initialized: service=${serviceName}, otlp=${endpoint}`,
+    );
+  }
+
+  /** Get gen_ai context from baggage */
+  private getGenAiFromContext(): GenAiContext {
+    const baggage = propagation.getBaggage(context.active());
+    return {
+      conversationId: baggage?.getEntry("gen_ai.conversation.id")?.value,
+      previousResponseId: baggage?.getEntry(
+        "gen_ai.request.previous_response_id",
+      )?.value,
+      agentName: baggage?.getEntry("gen_ai.agent.name")?.value,
+      agentId: baggage?.getEntry("gen_ai.agent.id")?.value,
+    };
+  }
+
+  /** Get identity from baggage or instance state */
+  private getIdentityFromContext(): IdentityContext {
+    const baggage = propagation.getBaggage(context.active());
+    return {
+      userId: baggage?.getEntry("identity.user_id")?.value || this.userId,
+      anonymousId:
+        baggage?.getEntry("identity.anonymous_id")?.value || this.anonymousId,
+    };
+  }
+
+  private getTimestamp(): [number, number] {
+    const hrTimeNs = process.hrtime.bigint();
+    const epochNs = BigInt(Date.now()) * BigInt(1_000_000);
+    const offsetNs = hrTimeNs - process.hrtime.bigint() + epochNs;
+    const seconds = Number(offsetNs / BigInt(1_000_000_000));
+    const nanos = Number(offsetNs % BigInt(1_000_000_000));
+    return [seconds, nanos];
+  }
+
+  private buildAttributes(
+    eventName: string,
+    options: {
+      properties?: Record<string, unknown>;
+      traits?: Record<string, unknown>;
+      conversationId?: string;
+      previousResponseId?: string;
+      eventId?: string;
+    } = {},
+  ): LogAttributes {
+    const { properties, traits, conversationId, previousResponseId, eventId } =
+      options;
+
+    const attributes: LogAttributes = {
+      "event.name": eventName,
+      "event.id": eventId || generateEventId(),
+    };
+
+    const identity = this.getIdentityFromContext();
+    if (identity.userId) attributes["identity.user.id"] = identity.userId;
+    if (identity.anonymousId)
+      attributes["identity.anonymous.id"] = identity.anonymousId;
+
+    const genAi = this.getGenAiFromContext();
+    const finalConversationId = conversationId || genAi.conversationId;
+    const finalPreviousResponseId =
+      previousResponseId || genAi.previousResponseId;
+
+    if (finalConversationId)
+      attributes["gen_ai.conversation.id"] = finalConversationId;
+    if (finalPreviousResponseId)
+      attributes["gen_ai.request.previous_response_id"] =
+        finalPreviousResponseId;
+    if (genAi.agentName) attributes["gen_ai.agent.name"] = genAi.agentName;
+    if (genAi.agentId) attributes["gen_ai.agent.id"] = genAi.agentId;
+
+    if (properties) {
+      for (const [key, value] of Object.entries(properties)) {
+        if (value != null) {
+          const attrKey = `properties.${key}`;
+          if (typeof value === "object") {
+            attributes[attrKey] = JSON.stringify(value);
+          } else if (
+            typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean"
+          ) {
+            attributes[attrKey] = value;
+          }
+        }
+      }
+    }
+
+    if (traits) {
+      for (const [key, value] of Object.entries(traits)) {
+        if (value != null) {
+          const attrKey = `context.traits.${key}`;
+          if (typeof value === "object") {
+            attributes[attrKey] = JSON.stringify(value);
+          } else if (
+            typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean"
+          ) {
+            attributes[attrKey] = value;
+          }
+        }
+      }
+    }
+
+    return attributes;
+  }
+
+  track(
+    eventName: string,
+    properties?: Record<string, unknown>,
+    options?: { eventId?: string },
+  ): void {
+    const attributes = this.buildAttributes(eventName, {
+      properties,
+      eventId: options?.eventId,
+    });
+    this.otelLogger.emit({
+      timestamp: this.getTimestamp(),
+      context: context.active(),
+      severityNumber: SeverityNumber.INFO,
+      severityText: "INFO",
+      attributes,
+    });
+    sdkLogger.debug(`Tracked: ${eventName}`);
+  }
+
+  feedback(name: string, options: FeedbackOptions = {}): void {
+    const { comments, conversationId, previousResponseId, eventId, ...extra } =
+      options;
+    const properties: Record<string, unknown> = { name, ...extra };
+    if (comments) properties.comments = comments;
+    const attributes = this.buildAttributes("introspection.feedback", {
+      properties,
+      conversationId: conversationId as string | undefined,
+      previousResponseId: previousResponseId as string | undefined,
+      eventId: eventId as string | undefined,
+    });
+    this.otelLogger.emit({
+      timestamp: this.getTimestamp(),
+      context: context.active(),
+      severityNumber: SeverityNumber.INFO,
+      severityText: "INFO",
+      attributes,
+    });
+    sdkLogger.debug(`Feedback: ${name}`);
+  }
+
+  identify(
+    userId: string,
+    traits?: UserTraits,
+    anonymousId?: string,
+    eventId?: string,
+  ): void {
+    this.userId = userId;
+    if (anonymousId) this.anonymousId = anonymousId;
+    if (traits) this.traits = { ...this.traits, ...traits };
+    const attributes = this.buildAttributes("identify", { traits, eventId });
+    this.otelLogger.emit({
+      timestamp: this.getTimestamp(),
+      context: context.active(),
+      severityNumber: SeverityNumber.INFO,
+      severityText: "INFO",
+      attributes,
+    });
+    sdkLogger.debug(`Identified: ${userId}`);
+  }
+
+  createBaggageContext(values: Record<string, string>) {
+    const ctx = context.active();
+    let bag = propagation.getBaggage(ctx) || propagation.createBaggage();
+    for (const [key, value] of Object.entries(values)) {
+      bag = bag.setEntry(key, { value });
+    }
+    return propagation.setBaggage(ctx, bag);
+  }
+
+  async withBaggage<T>(
+    values: Record<string, string>,
+    callback: () => T | Promise<T>,
+  ): Promise<T> {
+    const ctx = this.createBaggageContext(values);
+    return await context.with(ctx, callback);
+  }
+
+  async withAgent<T>(
+    agentName: string,
+    agentId: string | undefined,
+    callback: () => T | Promise<T>,
+  ): Promise<T> {
+    const values: Record<string, string> = { "gen_ai.agent.name": agentName };
+    if (agentId) values["gen_ai.agent.id"] = agentId;
+    return await context.with(this.createBaggageContext(values), callback);
+  }
+
+  async withConversation<T>(
+    conversationId: string | undefined,
+    previousResponseId: string | undefined,
+    callback: () => T | Promise<T>,
+  ): Promise<T> {
+    const values: Record<string, string> = {};
+    if (conversationId) values["gen_ai.conversation.id"] = conversationId;
+    if (previousResponseId)
+      values["gen_ai.request.previous_response_id"] = previousResponseId;
+    return await context.with(this.createBaggageContext(values), callback);
+  }
+
+  setUserId(userId: string): void {
+    this.userId = userId;
+  }
+
+  setAnonymousId(anonymousId: string): void {
+    this.anonymousId = anonymousId;
+  }
+
+  async withUserId<T>(
+    userId: string,
+    callback: () => T | Promise<T>,
+  ): Promise<T> {
+    return await context.with(
+      this.createBaggageContext({ "identity.user_id": userId }),
+      callback,
+    );
+  }
+
+  async withAnonymousId<T>(
+    anonymousId: string,
+    callback: () => T | Promise<T>,
+  ): Promise<T> {
+    return await context.with(
+      this.createBaggageContext({ "identity.anonymous_id": anonymousId }),
+      callback,
+    );
+  }
+
+  getAnonymousId(): string | undefined {
+    return this.anonymousId;
+  }
+
+  reset(): void {
+    this.userId = undefined;
+    this.anonymousId = undefined;
+    this.traits = {};
+    sdkLogger.debug("IntrospectionLogs state reset");
+  }
+
+  async flush(): Promise<void> {
+    await this.loggerProvider.forceFlush();
+    sdkLogger.debug("Flushed pending log records");
+  }
+
+  async shutdown(): Promise<void> {
+    await this.loggerProvider.shutdown();
+    sdkLogger.debug("IntrospectionLogs shutdown complete");
+  }
+}

package/src/{mastra-exporter.ts → otel/mastra-exporter.ts}

@@ -51,8 +51,8 @@ import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { randomUUID } from "crypto";
 
-import { logger, withOtlpHttpsProxy } from "./utils.js";
-import { VERSION } from "./version.js";
+import { logger, withOtlpHttpsProxy } from "../utils.js";
+import { VERSION } from "../version.js";
 import type {
   InputMessage,
   OutputMessage,
@@ -77,7 +77,7 @@ export interface MastraExporterAdvancedOptions {
 export interface IntrospectionMastraExporterOptions {
   /** Authentication token (env: INTROSPECTION_TOKEN). */
   token?: string;
-  /** Base URL for the API (env: INTROSPECTION_BASE_URL). */
+  /** Base URL for the API (env: INTROSPECTION_BASE_OTEL_URL). */
   baseUrl?: string;
   /** Additional headers to include in requests. */
   additionalHeaders?: Record<string, string>;
@@ -152,7 +152,7 @@ export class IntrospectionMastraExporter extends BaseExporter {
 
       const baseUrl =
         opts.baseUrl ||
-        process.env.INTROSPECTION_BASE_URL ||
+        process.env.INTROSPECTION_BASE_OTEL_URL ||
         "https://otel.introspection.dev";
       const endpoint = baseUrl.endsWith("/v1/traces")
         ? baseUrl
@@ -291,7 +291,26 @@ export class IntrospectionMastraExporter extends BaseExporter {
       span.entityName || span.name || "agent",
     );
 
-    if (attrs?.["instructions"] && typeof attrs["instructions"] === "string") {
+    // Prefer system messages from span.input (full prompt sent to LLM) over
+    // attrs.instructions (may be just the short placeholder string).
+    const inputMsgs = Array.isArray(span.input)
+      ? (span.input as Record<string, unknown>[])
+      : undefined;
+    const systemMsgsFromInput = inputMsgs?.filter((m) => m.role === "system");
+    if (systemMsgsFromInput && systemMsgsFromInput.length > 0) {
+      rootSpan.setAttribute(
+        "gen_ai.system_instructions",
+        JSON.stringify(
+          systemMsgsFromInput.map((m) => ({
+            type: "text",
+            content: this._extractTextContent(m.content),
+          })),
+        ),
+      );
+    } else if (
+      attrs?.["instructions"] &&
+      typeof attrs["instructions"] === "string"
+    ) {
       rootSpan.setAttribute(
         "gen_ai.system_instructions",
         JSON.stringify([{ type: "text", content: attrs["instructions"] }]),
@@ -345,12 +364,30 @@ export class IntrospectionMastraExporter extends BaseExporter {
       otelSpan.setAttribute("gen_ai.response.model", responseModel);
     if (responseId) otelSpan.setAttribute("gen_ai.response.id", responseId);
 
-    // Input messages — model_step has input.body.input (raw API messages)
+    // Input messages — span.input is either:
+    //   (a) a flat normalized array { role, content }[] from Mastra's inputMessages path, or
+    //   (b) an object { body: { input/messages, tools } } from the raw HTTP request path.
     if (span.input != null) {
-      const rawInput = span.input as Record<string, unknown>;
-      const body = rawInput?.body as Record<string, unknown> | undefined;
-      const apiMessages = body?.input ?? body?.messages;
-      if (Array.isArray(apiMessages)) {
+      let apiMessages: Record<string, unknown>[] | undefined;
+      let tools: unknown[] | undefined;
+
+      if (Array.isArray(span.input)) {
+        // Path (a): flat array already normalized by Mastra's normalizeMessages()
+        apiMessages = span.input as Record<string, unknown>[];
+      } else {
+        // Path (b): nested request body
+        const rawInput = span.input as Record<string, unknown>;
+        const body = rawInput?.body as Record<string, unknown> | undefined;
+        const msgs = body?.input ?? body?.messages;
+        if (Array.isArray(msgs)) {
+          apiMessages = msgs as Record<string, unknown>[];
+        }
+        if (Array.isArray(body?.tools)) {
+          tools = body.tools as unknown[];
+        }
+      }
+
+      if (apiMessages && apiMessages.length > 0) {
         const inputMessages = this._convertInput(apiMessages);
         if (inputMessages.length > 0) {
           otelSpan.setAttribute(
@@ -359,28 +396,22 @@ export class IntrospectionMastraExporter extends BaseExporter {
           );
         }
 
-        // System instructions
-        const systemMsgs = (apiMessages as Record<string, unknown>[]).filter(
-          (m) => m.role === "system",
-        );
+        // System instructions — combine all system messages into one attribute
+        const systemMsgs = apiMessages.filter((m) => m.role === "system");
         if (systemMsgs.length > 0) {
           otelSpan.setAttribute(
             "gen_ai.system_instructions",
             JSON.stringify(
               systemMsgs.map((m) => ({
                 type: "text",
-                content:
-                  typeof m.content === "string"
-                    ? m.content
-                    : JSON.stringify(m.content),
+                content: this._extractTextContent(m.content),
               })),
             ),
           );
         }
       }
 
-      // Tool definitions from input.body.tools
-      const tools = body?.tools;
+      // Tool definitions (only present on path (b))
       if (Array.isArray(tools) && tools.length > 0) {
         otelSpan.setAttribute(
           "gen_ai.tool.definitions",
@@ -431,6 +462,11 @@ export class IntrospectionMastraExporter extends BaseExporter {
           "gen_ai.usage.cache_read.input_tokens",
           inputDetails["cacheRead"],
         );
+      if (typeof inputDetails?.["cacheWrite"] === "number")
+        otelSpan.setAttribute(
+          "gen_ai.usage.cache_creation.input_tokens",
+          inputDetails["cacheWrite"],
+        );
     }
 
     // Finish reason
@@ -505,11 +541,17 @@ export class IntrospectionMastraExporter extends BaseExporter {
         // Skip system messages (handled separately)
         if (msg.role === "system") continue;
 
-        // Standard role-based messages
+        // Standard role-based messages (AIv4 uses msg.content; AIv5 may use msg.parts)
         if (msg.role) {
+          const parts =
+            msg.content != null
+              ? this._extractParts(msg.content)
+              : Array.isArray(msg.parts)
+                ? this._extractParts(msg.parts)
+                : [];
           result.push({
             role: msg.role as InputMessage["role"],
-            parts: this._extractParts(msg.content),
+            parts,
           });
           continue;
         }
@@ -588,6 +630,25 @@ export class IntrospectionMastraExporter extends BaseExporter {
     return [{ role: "assistant", parts, finish_reason: finishReason }];
   }
 
+  /** Extract plain text from a message content field (string, array of parts, or AIv5 parts). */
+  private _extractTextContent(content: unknown): string {
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content
+        .map((p: unknown) => {
+          const part = p as Record<string, unknown>;
+          return typeof part.text === "string"
+            ? part.text
+            : typeof part.content === "string"
+              ? part.content
+              : "";
+        })
+        .filter(Boolean)
+        .join("\n");
+    }
+    return typeof content === "undefined" ? "" : JSON.stringify(content);
+  }
+
   private _extractParts(content: unknown): MessagePart[] {
     if (typeof content === "string") {
       return [{ type: "text", content }];

package/src/otel/pi.ts

@@ -0,0 +1,88 @@
+/**
+ * High-level pi Agent SDK integration for Introspection.
+ *
+ * Wraps {@link @introspection-sdk/introspection-pi} behind a zero-config
+ * interface so users don't need to manage OpenTelemetry tracers directly.
+ *
+ * @example
+ * ```ts
+ * import { IntrospectionPiInstrumentor, setupTracing } from "@introspection-sdk/introspection-node";
+ * import { Agent } from "@mariozechner/pi-agent-core";
+ *
+ * setupTracing({ serviceName: "my-app" });
+ * const instrumentor = new IntrospectionPiInstrumentor();
+ *
+ * const agent = new Agent({ ... });
+ * instrumentor.instrument(agent, {
+ *   conversationId: "conv-123",
+ *   agentId: "weather-agent",
+ *   agentName: "Weather",
+ * });
+ *
+ * await agent.prompt("What's the weather in Tokyo?");
+ * instrumentor.stop();
+ * ```
+ */
+
+import { trace } from "@opentelemetry/api";
+import type { Agent } from "@mariozechner/pi-agent-core";
+import {
+  instrumentStream,
+  instrumentAgent,
+  type AgentMeta,
+  type AgentInstrumentation,
+} from "@introspection-sdk/introspection-pi";
+import { VERSION } from "../version.js";
+
+export type { AgentMeta } from "@introspection-sdk/introspection-pi";
+
+export interface IntrospectionPiInstrumentorOptions {
+  /** Tracer name used for all spans produced by this instrumentor. */
+  tracerName?: string;
+}
+
+/**
+ * Zero-config pi Agent SDK integration for Introspection.
+ *
+ * Uses the global OTel tracer provider (registered by {@link setupTracing}).
+ * Call {@link instrument} once per {@link Agent} instance, then {@link stop}
+ * to unsubscribe all tool instrumentation and finalize open spans.
+ */
+export class IntrospectionPiInstrumentor {
+  private _tracer: ReturnType<typeof trace.getTracer>;
+  private _instrumentations: AgentInstrumentation[] = [];
+
+  constructor(opts: IntrospectionPiInstrumentorOptions = {}) {
+    this._tracer = trace.getTracer(
+      opts.tracerName ?? "introspection-pi",
+      VERSION,
+    );
+  }
+
+  /**
+   * Instrument a pi {@link Agent}:
+   * - Wraps `agent.streamFn` to emit a `chat ${provider}` span per LLM call.
+   * - Subscribes to the agent loop to emit an `execute_tool ${name}` span per
+   *   tool execution.
+   *
+   * @param agent - The pi Agent instance to instrument.
+   * @param meta  - Identity metadata stamped on every span produced by this agent.
+   */
+  instrument(agent: Agent, meta: AgentMeta): void {
+    agent.streamFn = instrumentStream(agent.streamFn, {
+      tracer: this._tracer,
+      meta,
+    });
+    this._instrumentations.push(
+      instrumentAgent(agent, { tracer: this._tracer, meta }),
+    );
+  }
+
+  /**
+   * Unsubscribe all active tool instrumentations and finalize any open spans.
+   */
+  stop(): void {
+    for (const inst of this._instrumentations) inst.stop();
+    this._instrumentations = [];
+  }
+}