Add tests and docs

Author: cephalization

js/packages/openinference-mastra/README.md

@@ -14,7 +14,7 @@ A typical Mastra project will already have OpenTelemetry and related packages in
 
 ## Usage
 
-`@arizeai/openinference-mastra` provides a set of utilities to help you ingest Mastra spans into platforms and works in conjunction with Mastra's OpenTelemetry support. To get started, you will need to add OpenTelemetry support to your Mastra project according to the [Mastra Observability guide](https://mastra.ai/en/reference/observability/providers), or, follow along with the rest of this README.
+`@arizeai/openinference-mastra` provides a set of utilities to help you ingest Mastra spans into the Phoenix platform (and any other OpenInference-compatible platform) and works in conjunction with Mastra's OpenTelemetry support. To get started, you will need to add OpenTelemetry support to your Mastra project according to the [Mastra Observability guide](https://mastra.ai/en/reference/observability/providers), or, follow along with the rest of this README.
 
 To process your Mastra spans add an `OpenInferenceOTLPTraceExporter` to your `telemetry` configuration within your `Mastra` instance.
 
@@ -26,7 +26,7 @@ export PHOENIX_API_KEY="your-api-key"
 
 ```typescript
 import { Mastra } from "@mastra/core";
-import { OpenInferenceOTLPTraceExporter } from "@arizeai/openinference-mastra";
+import { OpenInferenceOTLPTraceExporter, isOpenInferenceSpan } from "@arizeai/openinference-mastra";
 
 export const mastra = new Mastra({
   // ... other config
@@ -37,7 +37,12 @@ export const mastra = new Mastra({
       type: "custom",
       exporter: new OpenInferenceOTLPTraceExporter({
         collectorEndpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
+        // optional: add bearer auth token if Phoenix or other platform requires it
         apiKey: process.env.PHOENIX_API_KEY,
+        // optional: filter out http, and other node service specific spans
+        // they will still be exported to Mastra, but not to the target of
+        // this exporter
+        spanFilter: isOpenInferenceSpan,
       }),
     },
   },
@@ -48,4 +53,74 @@ For general details on Mastra's OpenTelemetry support see the [Mastra Observabil
 
 ## Examples
 
-TODO: Add examples
+### Weather Agent
+
+To setup the canonical Mastra weather agent example, and then ingest the spans into Phoenix, follow the steps below.
+
+- Create a new Mastra project
+
+```shell
+npm create mastra@latest
+# answer the prompts, include agent, tools, and the example when asked
+cd chosen-project-name
+npm install --save @arizeai/openinference-mastra
+# export some variables for mastra to use later on
+export PHOENIX_COLLECTOR_ENDPOINT="https://localhost:6006/v1/traces"
+export PHOENIX_API_KEY="your-api-key"
+export OPENAI_API_KEY="your-openai-api-key"
+```
+
+- Add the OpenInferenceOTLPTraceExporter to your Mastra project
+
+```typescript
+// chosen-project-name/src/index.ts
+import { Mastra } from "@mastra/core/mastra";
+import { createLogger } from "@mastra/core/logger";
+import { LibSQLStore } from "@mastra/libsql";
+import {
+  isOpenInferenceSpan,
+  OpenInferenceOTLPTraceExporter,
+} from "@arizeai/openinference-mastra";
+
+import { weatherAgent } from "./agents";
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+  storage: new LibSQLStore({
+    url: ":memory:",
+  }),
+  logger: createLogger({
+    name: "Mastra",
+    level: "info",
+  }),
+  telemetry: {
+    enabled: true,
+    serviceName: "weather-agent",
+    export: {
+      type: "custom",
+      exporter: new OpenInferenceOTLPTraceExporter({
+        apiKey: process.env.PHOENIX_API_KEY,
+        collectorEndpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
+        spanFilter: isOpenInferenceSpan,
+      }),
+    },
+  },
+});
+```
+
+- Run the agent
+
+```shell
+npm run dev
+```
+
+- Send a chat message to the agent in the playground [http://localhost:4111/agents/weatherAgent/chat/](http://localhost:4111/agents/weatherAgent/chat/)
+
+![weather agent chat](./docs/mastra-weather-agent.png)
+
+- After a few moments, you should see the spans for the agent's request and response in Phoenix. 
+  - Not sure how to run the Phoenix collector? [Check out the Phoenix docs](https://docs.arize.com/phoenix/self-hosting/deployment-options/docker#docker).
+
+![weather agent spans](./docs/mastra-weather-agent-spans.png)
+
+You've done it! For next steps, check out the [Mastra docs](https://mastra.ai/en/docs) to learn how to add more agents, tools, and storage options to your project.

js/packages/openinference-mastra/docs/mastra-weather-agent-spans.png

@@ -0,0 +1,53 @@
+import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+
+let debugSpans: Pick<
+  ReadableSpan,
+  | "name"
+  | "attributes"
+  | "parentSpanId"
+  | "kind"
+  | "status"
+  | "resource"
+  | "startTime"
+  | "endTime"
+>[] = [];
+
+/**
+ * DEBUG
+ *
+ * Accumulate items across invocations until the item has no parentId, then dump items to json file
+ * $HOME/debug-mastra-instrumentation/spans-{new Date().toISOString()}.json
+ */
+export const debug = async (items: ReadableSpan[]) => {
+  // only import fs if we need it
+  // this allows the module to be used in environments that don't have fs
+  const fs = await import("node:fs");
+  debugSpans.push(
+    // @ts-expect-error -just grabbing incomplete fields for testing
+    ...items
+      .map((i) => ({
+        name: i.name,
+        attributes: i.attributes,
+        parentSpanId: i.parentSpanId,
+        kind: i.kind,
+        status: i.status,
+        resource: {},
+        startTime: i.startTime,
+        endTime: i.endTime,
+      }))
+      .filter((i) =>
+        ["post", "agent", "ai"].some((prefix) =>
+          i.name.toLocaleLowerCase().startsWith(prefix),
+        ),
+      ),
+  );
+  const root = items.find((i) => i.parentSpanId == null);
+  if (root) {
+    fs.mkdirSync("debug-mastra-instrumentation", { recursive: true });
+    fs.writeFileSync(
+      `debug-mastra-instrumentation/${encodeURIComponent(root.name)}-${new Date().toISOString()}.json`,
+      JSON.stringify(debugSpans, null, 2),
+    );
+    debugSpans = [];
+  }
+};

js/packages/openinference-mastra/docs/mastra-weather-agent.png

@@ -1,10 +1,43 @@
+import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
 import { OpenInferenceOTLPTraceExporter } from "../src/OpenInferenceTraceExporter.js";
+import weatherAgentSpans from "./__fixtures__/weatherAgentSpans.json";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+
+vi.mock(import("@opentelemetry/exporter-trace-otlp-proto"), () => {
+  const mockedClass = vi.fn();
+  mockedClass.prototype.export = vi.fn();
+  return {
+    OTLPTraceExporter: mockedClass,
+  };
+});
 
 describe("OpenInferenceTraceExporter", () => {
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
   it("should initialize without throwing an error", () => {
     new OpenInferenceOTLPTraceExporter({
-      collectorEndpoint: "http://localhost:6006/v1/traces",
+      collectorEndpoint: "http://example.com/v1/traces",
+      apiKey: "test-api-key",
+    });
+  });
+
+  // Quickly capture a known working state of the instrumentation to ensure
+  // we don't regress.
+  // TODO: Replace with a more fine-grained test that is easier to update over
+  // time with the changes in the instrumentation.
+  it("(snapshot) should export spans with openinference properties", async () => {
+    const exporter = new OpenInferenceOTLPTraceExporter({
+      collectorEndpoint: "http://example.com/v1/traces",
       apiKey: "test-api-key",
     });
+    exporter.export(weatherAgentSpans as unknown as ReadableSpan[], () => {});
+    await expect(
+      // @ts-expect-error - mock.calls is provided by vitest
+      OTLPTraceExporter.prototype.export.mock.calls,
+    ).toMatchFileSnapshot(
+      `./__snapshots__/OpenInferenceTraceExporter.test.ts.export.json`,
+    );
   });
 });