@mastra/mcp-docs-server 1.1.18 → 1.1.19

package/.docs/docs/observability/logging.md

@@ -22,13 +22,70 @@ export const mastra = new Mastra({
 
 > **Info:** Visit [PinoLogger](https://mastra.ai/reference/logging/pino-logger) for all available configuration options.
 
+## Logging to observability storage
+
+When [observability](https://mastra.ai/docs/observability/overview) is configured, all logger calls are automatically forwarded to your observability storage. This means every `debug`, `info`, `warn`, `error`, and `trackException` call from your application and from Mastra's internal components appears alongside your traces.
+
+No code changes are required. Mastra wraps the configured logger so that it writes to both the original logger (console, file, or custom transport) and the observability system simultaneously.
+
+### Configuring observability log level
+
+You can control which log levels reach observability storage independently from your console logger. Add a `logging` option to your observability instance configuration:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { PinoLogger } from '@mastra/loggers'
+import { Observability, DefaultExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  logger: new PinoLogger({ name: 'Mastra', level: 'debug' }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-app',
+        exporters: [new DefaultExporter()],
+        logging: {
+          enabled: true, // set to false to disable log forwarding
+          level: 'info', // minimum level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+        },
+      },
+    },
+  }),
+})
+```
+
+In this example, the console logger outputs all levels starting from `debug`, but only `info` and above are written to observability storage. This keeps your storage clean while still having verbose console output during development.
+
+| Option    | Type       | Default   | Description                                                            |
+| --------- | ---------- | --------- | ---------------------------------------------------------------------- |
+| `enabled` | `boolean`  | `true`    | Set to `false` to disable all log forwarding to observability storage. |
+| `level`   | `LogLevel` | `'debug'` | Minimum severity level. Logs below this level are discarded.           |
+
+### Querying logs
+
+Logs written to observability storage are queryable through the Mastra client SDK:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient()
+
+const logs = await client.listLogsVNext({
+  filters: { level: 'error' },
+  pagination: { page: 1, perPage: 50 },
+  orderBy: { field: 'timestamp', direction: 'desc' },
+})
+```
+
+When using a persistent storage backend like DuckDB or ClickHouse, logs survive restarts and are available for historical analysis.
+
 ## Customizing logs
 
 Mastra provides access to a logger instance via the `mastra.getLogger()` method, available inside both workflow steps and tools. The logger supports standard severity levels: `debug`, `info`, `warn`, and `error`.
 
 ### Logging from workflow steps
 
-Within a workflow step, access the logger via the `mastra` parameter inside the `execute` function. This allows you to log messages relevant to the step’s execution.
+Within a workflow step, access the logger via the `mastra` parameter inside the `execute` function. This allows you to log messages relevant to the step's execution.
 
 ```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -52,7 +109,7 @@ export const testWorkflow = createWorkflow({...})
 
 ### Logging from tools
 
-Similarly, tools have access to the logger instance via the `mastra` parameter. Use this to log tool specific activity during execution.
+Similarly, tools have access to the logger instance via the `mastra` parameter. Use this to log tool-specific activity during execution.
 
 ```typescript
 import { createTool } from '@mastra/core/tools'
@@ -72,9 +129,7 @@ export const testTool = createTool({
 
 ### Logging with additional data
 
-Logger methods accept an optional second argument for additional data. This can be any value, such as an object, string, or number.
-
-In this example, the log message includes an object with a key of `agent` and a value of the `testAgent` instance.
+Logger methods accept an optional second argument for additional data. Pass a structured object to make logs filterable in observability storage.
 
 ```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";

package/.docs/docs/observability/overview.md

@@ -13,6 +13,10 @@ Specialized tracing for AI operations that captures:
 - **Workflow steps**: Branching logic, parallel execution, and step outputs
 - **Automatic instrumentation**: Tracing with decorators
 
+### Logging
+
+All logger calls from your application and Mastra's internal components are automatically forwarded to observability storage when observability is configured. You can [control the log level and disable forwarding](https://mastra.ai/docs/observability/logging) independently from your console logger.
+
 ## Storage requirements
 
 The `DefaultExporter` persists traces to your configured storage backend. Not all storage providers support observability—for the full list, see [Storage Provider Support](https://mastra.ai/docs/observability/tracing/exporters/default).
@@ -56,6 +60,9 @@ export const mastra = new Mastra({
           new DefaultExporter(), // Persists traces to storage for Mastra Studio
           new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
         ],
+        logging: {
+          level: 'info', // Minimum log level forwarded to storage (default: 'debug')
+        },
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
         ],

package/.docs/reference/observability/tracing/configuration.md

@@ -28,6 +28,7 @@ interface ObservabilityInstanceConfig {
   includeInternalSpans?: boolean
   requestContextKeys?: string[]
   serializationOptions?: SerializationOptions
+  logging?: { enabled?: boolean; level?: LogLevel }
 }
 ```
 
@@ -55,6 +56,12 @@ interface ObservabilityInstanceConfig {
 
 **serializationOptions.maxObjectKeys** (`number`): Maximum number of keys in objects (default: 50)
 
+**logging** (`{ enabled?: boolean; level?: LogLevel }`): Controls log forwarding to observability storage. See \[Logging to observability storage]\(/docs/observability/logging#logging-to-observability-storage) for details.
+
+**logging.enabled** (`boolean`): Set to false to disable log forwarding to observability storage (default: true)
+
+**logging.level** (`LogLevel`): Minimum log level to forward. One of 'debug', 'info', 'warn', 'error', 'fatal' (default: 'debug')
+
 ## `SamplingStrategy`
 
 ```typescript

package/.docs/reference/processors/language-detector.md

@@ -12,6 +12,7 @@ const processor = new LanguageDetector({
   targetLanguages: ['English', 'en'],
   threshold: 0.8,
   strategy: 'translate',
+  lastMessageOnly: true,
 })
 ```
 
@@ -31,6 +32,8 @@ const processor = new LanguageDetector({
 
 **options.instructions** (`string`): Custom detection instructions for the agent. If not provided, uses default instructions
 
+**options.lastMessageOnly** (`boolean`): Whether to detect language only for the most recent message in the batch instead of checking every message. Use this to keep LLM calls flat as conversation history grows.
+
 **options.minTextLength** (`number`): Minimum text length to perform detection. Short text is often unreliable for language detection
 
 **options.includeDetectionDetails** (`boolean`): Whether to include detailed detection info in logs

package/.docs/reference/processors/moderation-processor.md

@@ -12,6 +12,7 @@ const processor = new ModerationProcessor({
   threshold: 0.7,
   strategy: 'block',
   categories: ['hate', 'harassment', 'violence'],
+  lastMessageOnly: true,
 })
 ```
 
@@ -31,6 +32,8 @@ const processor = new ModerationProcessor({
 
 **options.includeScores** (`boolean`): Whether to include confidence scores in logs. Useful for tuning thresholds and debugging
 
+**options.lastMessageOnly** (`boolean`): Whether to run moderation only on the most recent message in the batch instead of checking every message. Use this to avoid an extra LLM call for each earlier message in long conversations.
+
 **options.chunkWindow** (`number`): Number of previous chunks to include for context when moderating stream chunks. If set to 1, includes the previous part, etc.
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal moderation agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)

package/.docs/reference/processors/pii-detector.md

@@ -12,6 +12,7 @@ const processor = new PIIDetector({
   threshold: 0.6,
   strategy: 'redact',
   detectionTypes: ['email', 'phone', 'credit-card', 'ssn'],
+  lastMessageOnly: true,
 })
 ```
 
@@ -33,6 +34,8 @@ const processor = new PIIDetector({
 
 **options.includeDetections** (`boolean`): Whether to include detection details in logs. Useful for compliance auditing and debugging
 
+**options.lastMessageOnly** (`boolean`): Whether to inspect only the most recent message in the batch instead of checking every message. Use this to avoid one LLM call per earlier message in long threads.
+
 **options.preserveFormat** (`boolean`): Whether to preserve PII format during redaction. When true, maintains structure like \*\*\*-\*\*-1234 for phone numbers
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)

package/.docs/reference/processors/prompt-injection-detector.md

@@ -12,6 +12,7 @@ const processor = new PromptInjectionDetector({
   threshold: 0.8,
   strategy: 'rewrite',
   detectionTypes: ['injection', 'jailbreak', 'system-override'],
+  lastMessageOnly: true,
 })
 ```
 
@@ -31,6 +32,8 @@ const processor = new PromptInjectionDetector({
 
 **options.includeScores** (`boolean`): Whether to include confidence scores in logs. Useful for tuning thresholds and debugging
 
+**options.lastMessageOnly** (`boolean`): Whether to inspect only the most recent message in the batch instead of checking every message. Use this to avoid extra LLM calls for earlier conversation history.
+
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`)
 
 ## Returns

package/.docs/reference/processors/system-prompt-scrubber.md

@@ -12,6 +12,7 @@ const processor = new SystemPromptScrubber({
   strategy: 'redact',
   redactionMethod: 'mask',
   includeDetections: true,
+  lastMessageOnly: true,
 })
 ```
 
@@ -27,6 +28,8 @@ const processor = new SystemPromptScrubber({
 
 **options.includeDetections** (`boolean`): Whether to include detection details in warnings. Useful for debugging and monitoring
 
+**options.lastMessageOnly** (`boolean`): Whether to inspect only the most recent output message in the batch instead of checking every message. Use this to limit LLM-based scrubbing to the latest response.
+
 **options.instructions** (`string`): Custom instructions for the detection agent. If not provided, uses default instructions
 
 **options.redactionMethod** (`'mask' | 'placeholder' | 'remove'`): Redaction method for system prompts: 'mask' replaces with asterisks, 'placeholder' replaces with placeholder text, 'remove' removes entirely

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @mastra/mcp-docs-server
 
+## 1.1.19
+
+### Patch Changes
+
+- Standardized all logger calls across the codebase to use static string messages with structured data objects. Dynamic values are now passed as key-value pairs in the second argument instead of being interpolated into template literal strings. This improves log filterability and searchability in observability storage. ([#14899](https://github.com/mastra-ai/mastra/pull/14899))
+
+  Removed ~150 redundant or noisy log calls including duplicate error logging after trackException and verbose in-memory storage CRUD traces.
+
+- Updated dependencies [[`cbeec24`](https://github.com/mastra-ai/mastra/commit/cbeec24b3c97a1a296e7e461e66cc7f7d215dc50), [`cee146b`](https://github.com/mastra-ai/mastra/commit/cee146b5d858212e1df2b2730fc36d3ceda0e08d), [`aa0aeff`](https://github.com/mastra-ai/mastra/commit/aa0aeffa11efbef5e219fbd97bf43d263cfe3afe), [`2bcec65`](https://github.com/mastra-ai/mastra/commit/2bcec652d62b07eab15e9eb9822f70184526eede), [`ad9bded`](https://github.com/mastra-ai/mastra/commit/ad9bdedf86a824801f49928a8d40f6e31ff5450f), [`cbeec24`](https://github.com/mastra-ai/mastra/commit/cbeec24b3c97a1a296e7e461e66cc7f7d215dc50), [`208c0bb`](https://github.com/mastra-ai/mastra/commit/208c0bbacbf5a1da6318f2a0e0c544390e542ddc), [`f566ee7`](https://github.com/mastra-ai/mastra/commit/f566ee7d53a3da33a01103e2a5ac2070ddefe6b0)]:
+  - @mastra/core@1.20.0
+  - @mastra/mcp@1.4.1
+
+## 1.1.19-alpha.0
+
+### Patch Changes
+
+- Standardized all logger calls across the codebase to use static string messages with structured data objects. Dynamic values are now passed as key-value pairs in the second argument instead of being interpolated into template literal strings. This improves log filterability and searchability in observability storage. ([#14899](https://github.com/mastra-ai/mastra/pull/14899))
+
+  Removed ~150 redundant or noisy log calls including duplicate error logging after trackException and verbose in-memory storage CRUD traces.
+
+- Updated dependencies [[`cbeec24`](https://github.com/mastra-ai/mastra/commit/cbeec24b3c97a1a296e7e461e66cc7f7d215dc50), [`cee146b`](https://github.com/mastra-ai/mastra/commit/cee146b5d858212e1df2b2730fc36d3ceda0e08d), [`aa0aeff`](https://github.com/mastra-ai/mastra/commit/aa0aeffa11efbef5e219fbd97bf43d263cfe3afe), [`2bcec65`](https://github.com/mastra-ai/mastra/commit/2bcec652d62b07eab15e9eb9822f70184526eede), [`ad9bded`](https://github.com/mastra-ai/mastra/commit/ad9bdedf86a824801f49928a8d40f6e31ff5450f), [`cbeec24`](https://github.com/mastra-ai/mastra/commit/cbeec24b3c97a1a296e7e461e66cc7f7d215dc50), [`208c0bb`](https://github.com/mastra-ai/mastra/commit/208c0bbacbf5a1da6318f2a0e0c544390e542ddc), [`f566ee7`](https://github.com/mastra-ai/mastra/commit/f566ee7d53a3da33a01103e2a5ac2070ddefe6b0)]:
+  - @mastra/core@1.20.0-alpha.0
+  - @mastra/mcp@1.4.1-alpha.0
+
 ## 1.1.18
 
 ### Patch Changes

package/dist/stdio.js

@@ -916,7 +916,7 @@ var clearMastraCourseHistory = {
 var docsBaseDir = fromPackageRoot(".docs/");
 async function listDirContents(dirPath) {
   try {
-    void logger.debug(`Listing directory contents: ${dirPath}`);
+    void logger.debug("Listing directory contents", { path: dirPath });
     const entries = await fs3.readdir(dirPath, { withFileTypes: true });
     const dirs = [];
     const files = [];
@@ -932,17 +932,19 @@ async function listDirContents(dirPath) {
       files: files.sort()
     };
   } catch (error) {
-    void logger.error(`Failed to list directory contents: ${dirPath}`, error);
+    void logger.error("Failed to list directory contents", { path: dirPath, error });
     throw error;
   }
 }
 async function readDocsContent(docPath, queryKeywords) {
-  const fullPath = path5__default.resolve(path5__default.join(docsBaseDir, docPath));
-  if (!fullPath.startsWith(path5__default.resolve(docsBaseDir))) {
-    void logger.error(`Path traversal attempt detected`);
+  const basePath = path5__default.resolve(docsBaseDir);
+  const fullPath = path5__default.resolve(path5__default.join(basePath, docPath));
+  const relativePath = path5__default.relative(basePath, fullPath);
+  if (relativePath.startsWith("..") || path5__default.isAbsolute(relativePath)) {
+    void logger.error("Path traversal attempt detected", { path: docPath, resolvedPath: fullPath });
     return { found: false, isSecurityViolation: true };
   }
-  void logger.debug(`Reading docs content from: ${fullPath}`);
+  void logger.debug("Reading docs content", { path: fullPath });
   try {
     const stats = await fs3.stat(fullPath);
     if (stats.isDirectory()) {
@@ -987,7 +989,7 @@ async function readDocsContent(docPath, queryKeywords) {
   }
 }
 async function findNearestDirectory(docPath, availablePaths2) {
-  void logger.debug(`Finding nearest directory for: ${docPath}`);
+  void logger.debug("Finding nearest directory", { path: docPath });
   const parts = docPath.split("/");
   while (parts.length > 0) {
     const testPath = parts.join("/");
@@ -1013,7 +1015,7 @@ async function findNearestDirectory(docPath, availablePaths2) {
         return listing.join("\n");
       }
     } catch {
-      void logger.debug(`Directory not found, trying parent: ${parts.slice(0, -1).join("/")}`);
+      void logger.debug("Directory not found, trying parent", { parent: parts.slice(0, -1).join("/") });
     }
     parts.pop();
   }
@@ -1833,7 +1835,7 @@ async function discoverMigrations(baseDir, relativePath = "") {
       }
     }
   } catch (error) {
-    void logger.error(`Failed to discover migrations in ${fullPath}`, error);
+    void logger.error("Failed to discover migrations", { path: fullPath, error });
   }
   return migrations;
 }
@@ -1906,7 +1908,7 @@ async function readMigrationContent(migrationPath) {
     const content = await fs3.readFile(filePath, "utf-8");
     return content;
   } catch (error) {
-    void logger.error(`Failed to read migration: ${migrationPath}`, error);
+    void logger.error("Failed to read migration", { path: migrationPath, error });
     return null;
   }
 }