@mastra/rag 2.1.3 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @mastra/rag
 
+## 2.2.0
+
+### Minor Changes
+
+- Add RAG observability (#10898) ([#15137](https://github.com/mastra-ai/mastra/pull/15137))
+
+  Surfaces RAG ingestion and query operations in Mastra's AI tracing.
+
+  New span types in `@mastra/core/observability`:
+  - `RAG_INGESTION` (root) — wraps an ingestion pipeline run
+  - `RAG_EMBEDDING` — embedding call (used by ingestion and query)
+  - `RAG_VECTOR_OPERATION` — vector store I/O (`query`/`upsert`/`delete`/`fetch`)
+  - `RAG_ACTION` — `chunk` / `extract_metadata` / `rerank`
+  - `GRAPH_ACTION` — non-RAG graph `build` / `traverse` / `update` / `prune`
+
+  New helpers exported from `@mastra/core/observability`:
+  - `startRagIngestion(opts)` — manual: returns `{ span, observabilityContext }`
+  - `withRagIngestion(opts, fn)` — scoped: runs `fn(observabilityContext)`,
+    attaches the return value as the span's output, routes thrown errors to
+    `span.error(...)`
+
+  Wired in `@mastra/rag`:
+  - `vectorQuerySearch` emits `RAG_EMBEDDING` (mode: `query`) and
+    `RAG_VECTOR_OPERATION` (operation: `query`)
+  - `rerank` / `rerankWithScorer` emit `RAG_ACTION` (action: `rerank`)
+  - `MDocument.chunk` emits `RAG_ACTION` (action: `chunk`) and
+    `RAG_ACTION` (action: `extract_metadata`)
+  - `createGraphRAGTool` emits `GRAPH_ACTION` (action: `build` / `traverse`)
+  - `createVectorQueryTool` and `createGraphRAGTool` thread
+    `observabilityContext` from the agent's `TOOL_CALL` span automatically
+
+  All new instrumentation is opt-in: functions accept an optional
+  `observabilityContext` and no-op when absent, so existing callers are
+  unaffected.
+
+### Patch Changes
+
+- Updated dependencies [[`8db7663`](https://github.com/mastra-ai/mastra/commit/8db7663c9a9c735828094c359d2e327fd4f8fba3), [`153e864`](https://github.com/mastra-ai/mastra/commit/153e86476b425db7cd0dc8490050096e92964a38), [`715710d`](https://github.com/mastra-ai/mastra/commit/715710d12fa47cf88e09d41f13843eddc29327b0), [`378c6c4`](https://github.com/mastra-ai/mastra/commit/378c6c4755726e8d8cf83a14809b350b90d46c62), [`9f91fd5`](https://github.com/mastra-ai/mastra/commit/9f91fd538ab2a44f8cc740bcad8e51205f74fbea), [`ba6fa9c`](https://github.com/mastra-ai/mastra/commit/ba6fa9cc0f3e1912c49fd70d4c3bb8c44903ddaa)]:
+  - @mastra/core@1.24.0
+
+## 2.2.0-alpha.0
+
+### Minor Changes
+
+- Add RAG observability (#10898) ([#15137](https://github.com/mastra-ai/mastra/pull/15137))
+
+  Surfaces RAG ingestion and query operations in Mastra's AI tracing.
+
+  New span types in `@mastra/core/observability`:
+  - `RAG_INGESTION` (root) — wraps an ingestion pipeline run
+  - `RAG_EMBEDDING` — embedding call (used by ingestion and query)
+  - `RAG_VECTOR_OPERATION` — vector store I/O (`query`/`upsert`/`delete`/`fetch`)
+  - `RAG_ACTION` — `chunk` / `extract_metadata` / `rerank`
+  - `GRAPH_ACTION` — non-RAG graph `build` / `traverse` / `update` / `prune`
+
+  New helpers exported from `@mastra/core/observability`:
+  - `startRagIngestion(opts)` — manual: returns `{ span, observabilityContext }`
+  - `withRagIngestion(opts, fn)` — scoped: runs `fn(observabilityContext)`,
+    attaches the return value as the span's output, routes thrown errors to
+    `span.error(...)`
+
+  Wired in `@mastra/rag`:
+  - `vectorQuerySearch` emits `RAG_EMBEDDING` (mode: `query`) and
+    `RAG_VECTOR_OPERATION` (operation: `query`)
+  - `rerank` / `rerankWithScorer` emit `RAG_ACTION` (action: `rerank`)
+  - `MDocument.chunk` emits `RAG_ACTION` (action: `chunk`) and
+    `RAG_ACTION` (action: `extract_metadata`)
+  - `createGraphRAGTool` emits `GRAPH_ACTION` (action: `build` / `traverse`)
+  - `createVectorQueryTool` and `createGraphRAGTool` thread
+    `observabilityContext` from the agent's `TOOL_CALL` span automatically
+
+  All new instrumentation is opt-in: functions accept an optional
+  `observabilityContext` and no-op when absent, so existing callers are
+  unaffected.
+
+### Patch Changes
+
+- Updated dependencies [[`8db7663`](https://github.com/mastra-ai/mastra/commit/8db7663c9a9c735828094c359d2e327fd4f8fba3), [`715710d`](https://github.com/mastra-ai/mastra/commit/715710d12fa47cf88e09d41f13843eddc29327b0), [`378c6c4`](https://github.com/mastra-ai/mastra/commit/378c6c4755726e8d8cf83a14809b350b90d46c62), [`9f91fd5`](https://github.com/mastra-ai/mastra/commit/9f91fd538ab2a44f8cc740bcad8e51205f74fbea), [`ba6fa9c`](https://github.com/mastra-ai/mastra/commit/ba6fa9cc0f3e1912c49fd70d4c3bb8c44903ddaa)]:
+  - @mastra/core@1.24.0-alpha.1
+
 ## 2.1.3
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-rag
 description: Documentation for @mastra/rag. Use when working with @mastra/rag APIs, configuration, or implementation.
 metadata:
   package: "@mastra/rag"
-  version: "2.1.3"
+  version: "2.2.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.3",
+  "version": "2.2.0",
   "package": "@mastra/rag",
   "exports": {},
   "modules": {}

package/dist/document/document.d.ts

@@ -1,3 +1,4 @@
+import type { ObservabilityContext } from '@mastra/core/observability';
 import { Document as Chunk } from './schema/index.js';
 import type { ChunkParams, ExtractParams, HTMLChunkOptions, RecursiveChunkOptions, CharacterChunkOptions, TokenChunkOptions, MarkdownChunkOptions, SemanticMarkdownChunkOptions, JsonChunkOptions, LatexChunkOptions, SentenceChunkOptions } from './types.js';
 export declare class MDocument {
@@ -28,7 +29,9 @@ export declare class MDocument {
     chunkMarkdown(options?: MarkdownChunkOptions): Promise<void>;
     chunkSentence(options?: SentenceChunkOptions): Promise<void>;
     chunkSemanticMarkdown(options?: SemanticMarkdownChunkOptions): Promise<void>;
-    chunk(params?: ChunkParams): Promise<Chunk[]>;
+    chunk(params?: ChunkParams, options?: {
+        observabilityContext?: ObservabilityContext;
+    }): Promise<Chunk[]>;
     getDocs(): Chunk[];
     getText(): string[];
     getMetadata(): Record<string, any>[];

package/dist/document/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document/document.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,QAAQ,IAAI,KAAK,EAAgC,MAAM,UAAU,CAAC;AAU3E,OAAO,KAAK,EACV,WAAW,EAEX,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EAErB,MAAM,SAAS,CAAC;AAGjB,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,IAAI,CAAS;gBAET,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;SAAE,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAOhG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IAuDzG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAYxE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAYxE,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAYhF,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAY9E,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,YAAY,CAAC,CAA4E;IAEjG,OAAO,KAAK,WAAW,GAetB;YAEa,OAAO;IASf,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9D,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9D,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CpD,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpD,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtD,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5D,qBAAqB,CAAC,OAAO,CAAC,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5E,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAiBnD,OAAO,IAAI,KAAK,EAAE;IAIlB,OAAO,IAAI,MAAM,EAAE;IAInB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;CAGrC"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document/document.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AASvE,OAAO,EAAE,QAAQ,IAAI,KAAK,EAAgC,MAAM,UAAU,CAAC;AAU3E,OAAO,KAAK,EACV,WAAW,EAEX,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EAErB,MAAM,SAAS,CAAC;AAGjB,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,IAAI,CAAS;gBAET,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;SAAE,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAOhG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IAuDzG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAYxE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAYxE,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAYhF,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAY9E,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,YAAY,CAAC,CAA4E;IAEjG,OAAO,KAAK,WAAW,GAetB;YAEa,OAAO;IASf,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9D,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9D,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CpD,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpD,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtD,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5D,qBAAqB,CAAC,OAAO,CAAC,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5E,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAqD9G,OAAO,IAAI,KAAK,EAAE;IAIlB,OAAO,IAAI,MAAM,EAAE;IAInB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;CAGrC"}

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var observability = require('@mastra/core/observability');
 var agent = require('@mastra/core/agent');
 var crypto = require('crypto');
 var zod = require('zod');
@@ -6917,15 +6918,47 @@ var MDocument = class _MDocument {
     const textSplit = rt.transformDocuments(this.chunks);
     this.chunks = textSplit;
   }
-  async chunk(params) {
+  async chunk(params, options) {
     const { strategy: passedStrategy, extract, ...chunkOptions } = params || {};
     const strategy = passedStrategy || this.defaultStrategy();
-    validateChunkParams(strategy, chunkOptions);
-    await this.chunkBy(strategy, chunkOptions);
-    if (extract) {
-      await this.extractMetadata(extract);
+    const parentSpan = options?.observabilityContext?.tracingContext?.currentSpan;
+    const chunkSpan = parentSpan?.createChildSpan({
+      type: observability.SpanType.RAG_ACTION,
+      name: `rag chunk: ${strategy}`,
+      input: { strategy },
+      attributes: {
+        action: "chunk",
+        strategy,
+        chunkSize: chunkOptions?.size,
+        chunkOverlap: chunkOptions?.overlap
+      }
+    });
+    try {
+      validateChunkParams(strategy, chunkOptions);
+      await this.chunkBy(strategy, chunkOptions);
+      if (extract) {
+        const extractSpan = chunkSpan?.createChildSpan({
+          type: observability.SpanType.RAG_ACTION,
+          name: "rag extract metadata",
+          attributes: {
+            action: "extract_metadata",
+            extractor: Object.keys(extract).join(",")
+          }
+        });
+        try {
+          await this.extractMetadata(extract);
+        } catch (err) {
+          extractSpan?.error({ error: err, endSpan: true });
+          throw err;
+        }
+        extractSpan?.end();
+      }
+      chunkSpan?.end({ output: { chunkCount: this.chunks.length } });
+      return this.chunks;
+    } catch (err) {
+      chunkSpan?.error({ error: err, endSpan: true });
+      throw err;
     }
-    return this.chunks;
   }
   getDocs() {
     return this.chunks;
@@ -7047,14 +7080,27 @@ async function executeRerank({
   scorer,
   options
 }) {
-  const { queryEmbedding, topK = 3 } = options;
+  const { queryEmbedding, topK = 3, observabilityContext } = options;
+  const rerankSpan = observabilityContext?.tracingContext?.currentSpan?.createChildSpan({
+    type: observability.SpanType.RAG_ACTION,
+    name: `rag rerank`,
+    input: { query, candidateCount: results.length },
+    attributes: {
+      action: "rerank",
+      candidateCount: results.length,
+      topN: topK,
+      scorer: scorer?.constructor?.name
+    }
+  });
   const weights = {
     ...DEFAULT_WEIGHTS,
     ...options.weights
   };
   const sum = Object.values(weights).reduce((acc, w) => acc.plus(w.toString()), new big_js.Big(0));
   if (!sum.eq(1)) {
-    throw new Error(`Weights must add up to 1. Got ${sum} from ${weights}`);
+    const err = new Error(`Weights must add up to 1. Got ${sum} from ${weights}`);
+    rerankSpan?.error({ error: err, endSpan: true });
+    throw err;
   }
   const resultLength = results.length;
   const queryAnalysis = queryEmbedding ? analyzeQueryEmbedding(queryEmbedding) : null;
@@ -7087,7 +7133,9 @@ async function executeRerank({
       };
     })
   );
-  return scoredResults.sort((a, b) => b.score - a.score).slice(0, topK);
+  const final = scoredResults.sort((a, b) => b.score - a.score).slice(0, topK);
+  rerankSpan?.end({ output: { returned: final.length } });
+  return final;
 }
 async function rerankWithScorer({
   results,
@@ -7377,33 +7425,67 @@ var vectorQuerySearch = async ({
   includeVectors = false,
   maxRetries = 2,
   databaseConfig = {},
-  providerOptions
+  providerOptions,
+  observabilityContext
 }) => {
+  const parentSpan = observabilityContext?.tracingContext?.currentSpan;
+  const embedSpan = parentSpan?.createChildSpan({
+    type: observability.SpanType.RAG_EMBEDDING,
+    name: `rag embed: query`,
+    input: queryText,
+    attributes: {
+      mode: "query",
+      model: model?.modelId,
+      provider: model?.provider,
+      inputCount: 1
+    }
+  });
   let embeddingResult;
-  if (model.specificationVersion === "v3") {
-    embeddingResult = await vector.embedV3({
-      model,
-      value: queryText,
-      maxRetries,
-      // Type assertion needed: providerOptions type is a union, but embedV3 expects specific version
-      ...providerOptions && { providerOptions }
-    });
-  } else if (model.specificationVersion === "v2") {
-    embeddingResult = await vector.embedV2({
-      model,
-      value: queryText,
-      maxRetries,
-      // Type assertion needed: providerOptions type is a union, but embedV2 expects specific version
-      ...providerOptions && { providerOptions }
-    });
-  } else {
-    embeddingResult = await vector.embedV1({
-      value: queryText,
-      model,
-      maxRetries
-    });
+  try {
+    if (model.specificationVersion === "v3") {
+      embeddingResult = await vector.embedV3({
+        model,
+        value: queryText,
+        maxRetries,
+        // Type assertion needed: providerOptions type is a union, but embedV3 expects specific version
+        ...providerOptions && {
+          providerOptions
+        }
+      });
+    } else if (model.specificationVersion === "v2") {
+      embeddingResult = await vector.embedV2({
+        model,
+        value: queryText,
+        maxRetries,
+        // Type assertion needed: providerOptions type is a union, but embedV2 expects specific version
+        ...providerOptions && {
+          providerOptions
+        }
+      });
+    } else {
+      embeddingResult = await vector.embedV1({
+        value: queryText,
+        model,
+        maxRetries
+      });
+    }
+  } catch (err) {
+    embedSpan?.error({ error: err, endSpan: true });
+    throw err;
   }
   const embedding = embeddingResult.embedding;
+  const embedUsage = embeddingResult?.usage;
+  embedSpan?.end({
+    attributes: {
+      dimensions: embedding?.length,
+      ...embedUsage && {
+        usage: {
+          inputTokens: embedUsage.tokens ?? embedUsage.promptTokens ?? embedUsage.inputTokens
+        }
+      }
+    },
+    output: { dimensions: embedding?.length }
+  });
   const queryParams = {
     indexName,
     queryVector: embedding,
@@ -7411,7 +7493,29 @@ var vectorQuerySearch = async ({
     filter: queryFilter,
     includeVector: includeVectors
   };
-  const results = await vectorStore.query({ ...queryParams, ...databaseSpecificParams(databaseConfig) });
+  const querySpan = parentSpan?.createChildSpan({
+    type: observability.SpanType.RAG_VECTOR_OPERATION,
+    name: `rag vector: query`,
+    // Pass filter as-is; the observability layer's deepClean handles
+    // size limits and sanitization centrally.
+    input: { topK, filter: queryFilter },
+    attributes: {
+      operation: "query",
+      indexName,
+      topK,
+      dimensions: embedding?.length
+    }
+  });
+  let results;
+  try {
+    results = await vectorStore.query({ ...queryParams, ...databaseSpecificParams(databaseConfig) });
+  } catch (err) {
+    querySpan?.error({ error: err, endSpan: true });
+    throw err;
+  }
+  querySpan?.end({
+    output: { returned: results?.length ?? 0 }
+  });
   return { results, queryEmbedding: embedding };
 };
 var databaseSpecificParams = (databaseConfig) => {
@@ -7675,7 +7779,9 @@ var createGraphRAGTool = (options) => {
     outputSchema,
     description: toolDescription,
     execute: async (inputData, context) => {
-      const { requestContext, mastra } = context || {};
+      const { requestContext, mastra, tracingContext } = context || {};
+      const observabilityContext = observability.createObservabilityContext(tracingContext);
+      const parentSpan = observabilityContext.tracingContext?.currentSpan;
       const indexName = requestContext?.get("indexName") ?? options.indexName;
       const vectorStoreName = "vectorStore" in options ? storeName : requestContext?.get("vectorStoreName") ?? storeName;
       if (!indexName) throw new Error(`indexName is required, got: ${indexName}`);
@@ -7713,7 +7819,8 @@ var createGraphRAGTool = (options) => {
           queryFilter: Object.keys(queryFilter || {}).length > 0 ? queryFilter : void 0,
           topK: topKValue,
           includeVectors: true,
-          providerOptions
+          providerOptions,
+          observabilityContext
         });
         if (logger) {
           logger.debug("vectorQuerySearch returned results", { count: results.length });
@@ -7729,17 +7836,50 @@ var createGraphRAGTool = (options) => {
           if (logger) {
             logger.debug("Initializing graph", { chunkCount: chunks.length, embeddingCount: embeddings.length });
           }
-          graphRag.createGraph(chunks, embeddings);
+          const buildSpan = parentSpan?.createChildSpan({
+            type: observability.SpanType.GRAPH_ACTION,
+            name: "graph build",
+            input: { nodeCount: chunks.length },
+            attributes: {
+              action: "build",
+              nodeCount: chunks.length,
+              threshold: graphOptions.threshold
+            }
+          });
+          try {
+            graphRag.createGraph(chunks, embeddings);
+          } catch (err) {
+            buildSpan?.error({ error: err, endSpan: true });
+            throw err;
+          }
+          buildSpan?.end();
           isInitialized = true;
         } else if (logger) {
           logger.debug("Graph already initialized, skipping graph construction");
         }
-        const rerankedResults = graphRag.query({
-          query: queryEmbedding,
-          topK: topKValue,
-          randomWalkSteps,
-          restartProb
+        const traverseSpan = parentSpan?.createChildSpan({
+          type: observability.SpanType.GRAPH_ACTION,
+          name: "graph traverse",
+          input: { topK: topKValue, randomWalkSteps, restartProb },
+          attributes: {
+            action: "traverse",
+            startNodes: 1,
+            maxDepth: randomWalkSteps
+          }
         });
+        let rerankedResults;
+        try {
+          rerankedResults = graphRag.query({
+            query: queryEmbedding,
+            topK: topKValue,
+            randomWalkSteps,
+            restartProb
+          });
+        } catch (err) {
+          traverseSpan?.error({ error: err, endSpan: true });
+          throw err;
+        }
+        traverseSpan?.end({ output: { returned: rerankedResults.length } });
         if (logger) {
           logger.debug("GraphRAG query returned results", { count: rerankedResults.length });
         }
@@ -7778,7 +7918,8 @@ var createVectorQueryTool = (options) => {
     inputSchema,
     outputSchema,
     execute: async (inputData, context) => {
-      const { requestContext, mastra } = context || {};
+      const { requestContext, mastra, tracingContext } = context || {};
+      const observabilityContext = observability.createObservabilityContext(tracingContext);
       const indexName = requestContext?.get("indexName") ?? options.indexName;
       const vectorStoreName = "vectorStore" in options ? storeName : requestContext?.get("vectorStoreName") ?? storeName;
       const includeVectors = requestContext?.get("includeVectors") ?? options.includeVectors ?? false;
@@ -7819,7 +7960,8 @@ var createVectorQueryTool = (options) => {
           topK: topKValue,
           includeVectors,
           databaseConfig,
-          providerOptions
+          providerOptions,
+          observabilityContext
         });
         if (logger) {
           logger.debug("vectorQuerySearch returned results", { count: results.length });
@@ -7836,13 +7978,15 @@ var createVectorQueryTool = (options) => {
               scorer: reranker.model,
               options: {
                 ...reranker.options,
-                topK: reranker.options?.topK || topKValue
+                topK: reranker.options?.topK || topKValue,
+                observabilityContext
               }
             });
           } else {
             rerankedResults = await rerank(results, queryText, reranker.model, {
               ...reranker.options,
-              topK: reranker.options?.topK || topKValue
+              topK: reranker.options?.topK || topKValue,
+              observabilityContext
             });
           }
           if (logger) {