Conversation
- Create `tracing-configuration-reference.md` to document the `ObservabilityRegistryConfig`, `ObservabilityInstanceConfig`, `SerializationOptions`, `SamplingStrategy`, and related interfaces and methods for tracing configuration. - Create `tracing-instances-reference.md` to document the `DefaultObservabilityInstance`, `BaseObservabilityInstance`, and how to implement custom observability instances. feat: Introduce tracing interfaces documentation - Create `tracing-interfaces-reference.md` detailing core interfaces such as `ObservabilityInstance`, `Span`, `ObservabilityExporter`, and `SpanOutputProcessor`, along with their methods and properties. - Document span types and key attributes for better understanding of tracing mechanisms. feat: Add spans reference documentation - Create `tracing-spans-reference.md` to define `BaseSpan`, `Span`, and `ExportedSpan` interfaces, including lifecycle methods and events for span management. - Document span lifecycle events and introduce union types for handling spans. chore: Implement LibSQL configuration for memory storage - Create `libsql.ts` to configure `LibSQLStore` and `LibSQLVector` for vector storage and querying. - Initialize vector store with index creation and metadata handling. - Set up memory management options including semantic recall and working memory templates. - Log initialization details for database schema and memory options.
Learn moreAll Green is an AI agent that automatically: ✅ Addresses code review comments ✅ Fixes failing CI checks ✅ Resolves merge conflicts |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @ssdeanx, your pull request is larger than the review limit of 150000 diff characters
|
🤖 Hi @ssdeanx, I've received your request, and I'm working on it now! You can track my progress in the logs for more details. |
|
Caution Review failedThe pull request is closed. Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughThis PR adds comprehensive observability documentation for tracing, refactors tool implementations to migrate from OpenTelemetry tracer to a unified tracingContext-based child span API, introduces lifecycle hooks for streaming operations, extends context types with user and workspace metadata, and updates configuration for observability exporters. Changes
Sequence Diagram(s)sequenceDiagram
participant Tool as Tool Execution
participant Ctx as Tracing Context
participant Span as Child Span
participant Exporter as Span Exporter
Tool->>Ctx: Extract tracingContext from context
Tool->>Span: createChildSpan(TOOL_CALL, name, input, metadata)
activate Span
Note over Span: Span created with input & metadata
Tool->>Span: update(output, metadata)
Note over Span: Span updated with results
alt Success Path
Tool->>Span: end()
Span->>Exporter: emit SPAN_ENDED event
else Error Path
Tool->>Span: error(error, {endSpan: true})
Span->>Exporter: emit error with SPAN_ENDED event
end
deactivate Span
sequenceDiagram
participant Client as Tool Lifecycle Hooks
participant Tool as Tool Execute
participant Span as Child Span
participant Writer as Progress Writer
Client->>Client: onInputStart()
Note over Client: Log input received
Tool->>Tool: abortSignal check
Tool->>Span: createChildSpan
Client->>Writer: custom(in-progress)
Note over Writer: Emit progress event
Tool->>Tool: Process operation
Tool->>Span: update(output, metadata)
Client->>Client: onOutput()
Note over Client: Log output ready
Client->>Writer: custom(done)
Note over Writer: Emit completion event
Tool->>Span: end()
Note over Span: Finalize span
Estimated Code Review Effort🎯 4 (Complex) | ⏱️ ~60 minutes This PR exhibits high complexity due to: (1) seven new documentation files with detailed API specifications and examples requiring careful review for accuracy; (2) systematic refactoring across 32 tool files following a consistent but implementation-specific pattern (tracingContext migration, span lifecycle changes, context extensions); (3) public API changes including new exports, interface extensions, and signature updates; (4) coordination of multiple interdependent changes (imports, context types, lifecycle hooks, exporter configuration); (5) heterogeneous logic updates including error handling paths, progress signaling, and span metadata attachment that vary per tool. Possibly Related PRs
Poem
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (46)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
|
🤖 I'm sorry @ssdeanx, but I was unable to process your request. Please see the logs for more details. |
Summary of ChangesHello @ssdeanx, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the system's observability framework by introducing extensive documentation and standardizing the tracing implementation across various tools. It centralizes tracing logic within Mastra's internal context, ensuring a more cohesive and maintainable approach to monitoring. Additionally, it incorporates LibSQL for efficient memory management and updates core observability configurations. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant enhancement to the project's observability by adding comprehensive documentation for tracing and refactoring a large number of tools to use a new, centralized tracingContext. This is a great step towards standardizing instrumentation and improving maintainability. The introduction of LibSQL configuration is also a notable addition.
My review focuses on the correctness of the new LibSQL configuration and the consistency of the tracing migration across the various tools. While most of the refactoring is well-executed, there are some potential issues, particularly in the libsql.ts configuration, which I've detailed in the comments.
| await libsqlvector.createIndex({ | ||
| indexName: "memory_messages", | ||
| dimension: 3072, | ||
| metric: "cosine" | ||
| }); | ||
|
|
||
| // Add vectors with metadata | ||
| const vectors = [[0.1, 0.2], [0.3, 0.4]]; | ||
| const metadata = [ | ||
| { text: "first document", category: "A" }, | ||
| { text: "second document", category: "B" } | ||
| ]; | ||
| await libsqlvector.upsert({ | ||
| indexName: "memory_messages", | ||
| vectors, | ||
| metadata, | ||
| }); | ||
|
|
||
| // Query similar vectors | ||
| const queryVector = [0.1, 0.2]; // Your query vector | ||
|
|
||
| const results = await libsqlvector.query({ | ||
| indexName: "memory_messages", | ||
| queryVector, | ||
| topK: 10, // top K results | ||
| filter: { category: "A" } // optional metadata filter | ||
| }); |
There was a problem hiding this comment.
This block of code, which creates an index, upserts sample data, and performs a query, appears to be for testing or demonstration purposes. Including such side-effects in a configuration file that runs on module import is not a good practice. This can lead to unexpected behavior in production and makes the module stateful. This logic should be moved to a dedicated setup script, a test file, or an example usage file.
| log.info('PG Store and Memory initialized with PgVector support', { | ||
| schema: process.env.DB_SCHEMA ?? 'mastra', | ||
| maxConnections: parseInt(process.env.DB_MAX_CONNECTIONS ?? '20'), | ||
|
|
||
| memoryOptions: { | ||
| lastMessages: parseInt(process.env.MEMORY_LAST_MESSAGES ?? '500'), | ||
| semanticRecall: { | ||
| topK: parseInt(process.env.SEMANTIC_TOP_K ?? '5'), | ||
| messageRange: { | ||
| before: parseInt(process.env.SEMANTIC_RANGE_BEFORE ?? '3'), | ||
| after: parseInt(process.env.SEMANTIC_RANGE_AFTER ?? '2'), | ||
| }, | ||
| scope: 'resource', | ||
| indexConfig: { | ||
| type: 'ivfflat', // flat index type (supports dimensions > 4000, unlike HNSW limit of 2000) | ||
| metric: 'cosine', // Distance metric for normalized embeddings | ||
| } | ||
| }, | ||
| workingMemory: { | ||
| enabled: true, | ||
| scope: 'resource', | ||
| version: 'vnext', | ||
| } | ||
|
|
||
| }, | ||
| }) |
There was a problem hiding this comment.
The log message 'PG Store and Memory initialized with PgVector support' is misleading as this file configures LibSQL, not PostgreSQL. The logged object also contains properties like schema, maxConnections, and indexConfig: { type: 'ivfflat' }, which are specific to PostgreSQL and pgvector. This appears to be a copy-paste error and should be corrected to reflect the actual LibSQL configuration to avoid confusion during debugging.
| }, | ||
| } | ||
| span.end() | ||
| cryptoSpan?.end() |
There was a problem hiding this comment.
The span is ended here without capturing any output metadata. It's a good practice to update the span with key results before ending it, which improves observability. Consider using cryptoSpan?.update({ output: result, metadata: { ... } }) before cryptoSpan?.end().
cryptoSpan?.update({
output: result,
metadata: {
'tool.output.success': true,
'tool.output.dataKeys': Object.keys(result.data).length,
}
});
cryptoSpan?.end()| }, | ||
| } | ||
| span.end() | ||
| stockSpan?.end() |
There was a problem hiding this comment.
Similar to the crypto tool, the span for the stock tool is ended without capturing output metadata. To improve tracing and observability, you should update the span with the result before ending it.
stockSpan?.update({
output: result,
metadata: {
'tool.output.success': true,
'tool.output.dataKeys': Object.keys(result.data).length,
}
});
stockSpan?.end()| }, | ||
| } | ||
| span.end() | ||
| generalSpan?.end() |
There was a problem hiding this comment.
The span for the general Alpha Vantage tool is ended without capturing any output metadata. For consistency and better observability, please add a span.update() call with relevant output details before ending the span.
generalSpan?.update({
output: result,
metadata: {
'tool.output.success': true,
'tool.output.dataKeys': Object.keys(result.data).length,
}
});
generalSpan?.end()There was a problem hiding this comment.
Pull request overview
This pull request refactors tracing implementation across multiple tool files from OpenTelemetry API direct usage (@opentelemetry/api) to Mastra's observability system (@mastra/core/observability). The changes introduce unified tracing patterns, add user/workspace context tracking, and improve error handling consistency.
Key Changes:
- Replace
trace.getTracer().startSpan()withtracingContext?.currentSpan?.createChildSpan() - Update span lifecycle methods:
span.setAttributes()→span.update(),span.recordException()→span.error() - Add
userIdandworkspaceIdcontext fields to tool contexts - Improve null safety with optional chaining throughout
Reviewed changes
Copilot reviewed 45 out of 47 changed files in this pull request and generated 58 comments.
Show a summary per file
| File | Description |
|---|---|
| write-note.ts | Refactored to use Mastra tracing with child spans for note write operations |
| web-scraper-tool.ts | Large refactor with indentation fixes and tracing updates across 6 scraper tools |
| weather-tool.ts | Updated weather lookup with Mastra tracing and improved abort signal handling |
| url-tool.ts | Both validation and manipulation tools refactored with proper type annotations |
| text-analysis.tool.ts | Both analysis and processing tools updated with consistent tracing patterns |
| test-generator.tool.ts | Tracing updates and formatting standardization (indentation from tabs to spaces) |
| serpapi-shopping.tool.ts | Four shopping tools (Amazon, Walmart, eBay, Home Depot) updated with tracing |
| serpapi-search.tool.ts | Google search and AI overview tools refactored with improved metadata tracking |
| json-to-csv.tool.ts | Conversion tool updated with Mastra tracing and null coalescing operators |
| fs.ts | Filesystem operations tool refactored with proper error handling |
| // Query similar vectors | ||
| const queryVector = [0.1, 0.2]; // Your query vector | ||
|
|
||
| const results = await libsqlvector.query({ | ||
| indexName: "memory_messages", | ||
| queryVector, | ||
| topK: 10, // top K results | ||
| filter: { category: "A" } // optional metadata filter | ||
| }); | ||
|
|
||
| export const LibsqlMemory = new Memory({ | ||
| storage: libsqlstorage, | ||
| vector: libsqlvector, | ||
| embedder: google.textEmbedding('gemini-embedding-001'), | ||
| options: { |
There was a problem hiding this comment.
'results' is assigned a value but never used.
| // Query similar vectors | |
| const queryVector = [0.1, 0.2]; // Your query vector | |
| const results = await libsqlvector.query({ | |
| indexName: "memory_messages", | |
| queryVector, | |
| topK: 10, // top K results | |
| filter: { category: "A" } // optional metadata filter | |
| }); | |
| export const LibsqlMemory = new Memory({ | |
| storage: libsqlstorage, | |
| vector: libsqlvector, | |
| embedder: google.textEmbedding('gemini-embedding-001'), | |
| options: { | |
| // Query similar vectors (example query removed to avoid unused results) | |
| export const LibsqlMemory = new Memory({ | |
| storage: libsqlstorage, | |
| vector: libsqlvector, | |
| embedder: google.textEmbedding('gemini-embedding-001'), | |
| options: { | |
| options: { |
| // Check for cancellation before API call | ||
| if (abortSignal?.aborted) { | ||
| if (span) { | ||
| const spanAny = span as any |
There was a problem hiding this comment.
Unexpected any. Specify a different type.
| max_results: inputData.max_results ?? 10, | ||
| } | ||
| if (span) { | ||
| const spanAny = span as any |
There was a problem hiding this comment.
Unexpected any. Specify a different type.
| if (error instanceof Error && error.name === 'AbortError') { | ||
| const cancelMessage = `ArXiv search cancelled for "${inputData.query ?? inputData.id ?? 'papers'}"` | ||
| if (span) { | ||
| const spanAny = span as any |
There was a problem hiding this comment.
Unexpected any. Specify a different type.
| ? error.message | ||
| : 'Unknown error occurred' | ||
| if (span) { | ||
| const spanAny = span as any |
There was a problem hiding this comment.
Unexpected any. Specify a different type.
| }), | ||
| execute: async (inputData, context) => { | ||
| const writer = context?.writer | ||
| const abortSignal = context?.abortSignal |
There was a problem hiding this comment.
'abortSignal' is assigned a value but never used.
| }), | ||
| execute: async (inputData, context) => { | ||
| const writer = context?.writer | ||
| const abortSignal = context?.abortSignal |
There was a problem hiding this comment.
'abortSignal' is assigned a value but never used.
| }), | ||
| execute: async (inputData, context) => { | ||
| const writer = context?.writer | ||
| const abortSignal = context?.abortSignal |
There was a problem hiding this comment.
'abortSignal' is assigned a value but never used.
| }), | ||
| execute: async (inputData, context) => { | ||
| const writer = context?.writer | ||
| const abortSignal = context?.abortSignal |
There was a problem hiding this comment.
'abortSignal' is assigned a value but never used.
| const totalLines = content.split('\n').length | ||
| let sanitized = content | ||
| const totalLines = content.split('\n').length | ||
| let sanitized = content |
There was a problem hiding this comment.
The initial value of sanitized is unused, since it is always overwritten.
1 participant
tracing-configuration-reference.mdto document theObservabilityRegistryConfig,ObservabilityInstanceConfig,SerializationOptions,SamplingStrategy, and related interfaces and methods for tracing configuration.tracing-instances-reference.mdto document theDefaultObservabilityInstance,BaseObservabilityInstance, and how to implement custom observability instances.feat: Introduce tracing interfaces documentation
tracing-interfaces-reference.mddetailing core interfaces such asObservabilityInstance,Span,ObservabilityExporter, andSpanOutputProcessor, along with their methods and properties.feat: Add spans reference documentation
tracing-spans-reference.mdto defineBaseSpan,Span, andExportedSpaninterfaces, including lifecycle methods and events for span management.chore: Implement LibSQL configuration for memory storage
libsql.tsto configureLibSQLStoreandLibSQLVectorfor vector storage and querying.