@mastra/mcp-docs-server 1.2.15 → 1.2.16-alpha.3

package/.docs/docs/observability/integrations/exporters/mastra-platform.md

@@ -1,201 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Mastra platform exporter
-
-The `MastraPlatformExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.
-
-> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` for backward compatibility, but it's deprecated. New code should use `MastraPlatformExporter`.
-
-> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra platform), you still need a deployed Studio project to view traces, logs, and metrics. `MastraPlatformExporter` sends data to a Studio project, so one must exist before you can use it.
->
-> 1. [Create a Mastra project](https://mastra.ai/guides/getting-started/quickstart) if you don't have one yet.
-> 2. [Deploy Studio](https://mastra.ai/docs/studio/deployment) to the Mastra platform with `mastra studio deploy`.
-> 3. Follow the [quickstart steps below](#quickstart) to create an access token and find your project ID.
-
-## Version compatibility
-
-- `MastraPlatformExporter` is available starting in `@mastra/observability@1.12.0`. In `1.8.0` through `1.11.x` the same exporter includes only as `CloudExporter`. The constructor signature and environment variables are identical.
-- In `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
-- Starting in `@mastra/observability@1.9.2`, the exporter defaults to `https://observability.mastra.ai`, so `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` is only required when you want to send telemetry to a different collector.
-
-## Quickstart
-
-To connect `MastraPlatformExporter`, create an access token, find the destination `projectId`, and add the exporter to your observability config.
-
-### 1. Create an access token
-
-Run the following command:
-
-```bash
-mastra auth tokens create exporter-token
-```
-
-This command prints a token secret that you can use as `MASTRA_PLATFORM_ACCESS_TOKEN`.
-
-If you already have an access token, copy the **Observability** value from the Mastra platform instead. You can find it in either of these places:
-
-- On the **Projects** page, open the project list and find the **Observability** row on the project card.
-- On the project **Overview** page, find the **Observability** row directly below the deployment URL.
-
-Set the token as an environment variable:
-
-```bash
-MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
-```
-
-### 2. Find your `projectId`
-
-Run the following command:
-
-```bash
-mastra studio deploy list
-```
-
-The output looks similar to this:
-
-```text
-✅ <your-project-name> (<your-project-id>)
-   Latest:   00000000-0000-0000-0000-000000000000 — running
-   URL:      https://260407.studio.mastra.cloud
-```
-
-In this output, the value in parentheses is the `projectId`:
-
-```text
-<your-project-id>
-```
-
-Set it as an environment variable:
-
-```bash
-MASTRA_PROJECT_ID=<your-project-id>
-```
-
-### 3. Set your environment variables
-
-Set both values in your environment so `MastraPlatformExporter` can authenticate and route telemetry to the correct project:
-
-```bash
-MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
-MASTRA_PROJECT_ID=<your-project-id>
-```
-
-If you use `@mastra/observability@1.8.0` through `1.9.1`, also set the Mastra platform collector explicitly:
-
-```bash
-MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai
-```
-
-If you want to send telemetry somewhere other than Mastra platform, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` as well. Pass either a base origin or a full traces publish URL ending in `/spans/publish`.
-
-```bash
-MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
-```
-
-When you pass a base origin, `MastraPlatformExporter` derives the matching publish URLs for traces, logs, metrics, scores, and feedback automatically.
-
-### 4. Enable `MastraPlatformExporter`
-
-The following example demonstrates how to add `MastraPlatformExporter` to your observability config:
-
-```ts
-import { Mastra } from '@mastra/core'
-import { Observability, MastraPlatformExporter } from '@mastra/observability'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      production: {
-        serviceName: 'api-server',
-        exporters: [new MastraPlatformExporter()],
-      },
-    },
-  }),
-})
-```
-
-Set `serviceName` on the observability config, not on `MastraPlatformExporter` itself.
-
-Use a stable `serviceName` value. In Studio, traces can be filtered by **Deployments → Service Name**, so a consistent name makes traces easier to find.
-
-Visit [Observability configuration reference](https://mastra.ai/reference/observability/tracing/configuration) for the full observability config shape.
-
-If you prefer, rely entirely on environment variables:
-
-```ts
-new MastraPlatformExporter()
-```
-
-With `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `MastraPlatformExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`, it sends data to that collector instead. Visit [MastraPlatformExporter reference](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for the full list of configuration options.
-
-## Recommended configuration
-
-Include `MastraStorageExporter` if you also want to inspect local traces in Studio or persist observability data to your configured storage.
-
-```ts
-import { Mastra } from '@mastra/core'
-import {
-  Observability,
-  MastraStorageExporter,
-  MastraPlatformExporter,
-  SensitiveDataFilter,
-} from '@mastra/observability'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: 'mastra',
-        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
-        spanOutputProcessors: [new SensitiveDataFilter()],
-      },
-    },
-  }),
-})
-```
-
-## Complete configuration
-
-`MastraPlatformExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` in your environment or pass `endpoint` in code.
-
-```bash
-MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
-```
-
-The following example demonstrates how to override the collector endpoint and batching behavior in code:
-
-```ts
-new MastraPlatformExporter({
-  endpoint: 'https://collector.example.com',
-  maxBatchSize: 1000,
-  maxBatchWaitMs: 5000,
-  logLevel: 'info',
-})
-```
-
-## Viewing data in Mastra Studio
-
-After you enable `MastraPlatformExporter`, open your project in [Mastra Studio](https://projects.mastra.ai) to inspect the exported data.
-
-- Open the project you set `MASTRA_PROJECT_ID` to and select **Open Studio**.
-- In Studio, go to **Traces** to inspect agent and workflow traces.
-- Open the filter menu and use **Deployments → Service Name** to isolate traces from a specific app or deployment.
-- Use the **Logs** page in the project dashboard to inspect exported logs.
-
-When you deploy with Mastra Studio, set **Deployment → Service Name** to a stable value and keep it aligned with the `serviceName` in your observability config. This makes traces easier to filter in Studio through **Deployments → Service Name** when multiple services or deployments send data to the same project.
-
-## Performance
-
-> **Note:** MastraPlatformExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
-
-### Batching behavior
-
-- Events are batched up to `maxBatchSize` (default: 1000).
-- Batches are sent when full or after `maxBatchWaitMs` (default: 5 seconds).
-- Failed batches are retried with exponential backoff.
-- The exporter degrades gracefully if Mastra Studio is unreachable.
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [MastraStorageExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)

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

@@ -1,47 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Integrations overview
-
-Mastra observability integrations control where observability data goes and how it's transformed on the way out. Use integrations to store data in Mastra storage, send it to Mastra platform, connect to external observability providers, or redact exported span data.
-
-## When to use integrations
-
-- Keep observability available in Studio with `MastraStorageExporter`.
-- Send hosted observability data to Mastra platform with `MastraPlatformExporter`.
-- Forward traces to external providers such as Datadog, Langfuse, or OpenTelemetry backends.
-- Redact sensitive values before they leave the runtime.
-
-## Choose an integration path
-
-- Studio workflow: Start with [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
-- Hosted Mastra workflow: Add [Mastra platform](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform).
-- External observability stack: Choose one or more exporter pages under the sidebar `Exporters` section.
-- Existing distributed trace context: Use a bridge, then add exporters as needed.
-
-## Exporters
-
-Exporters send observability data to a destination:
-
-- [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage): Persist observability data for Studio.
-- [Mastra platform](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform): Send hosted observability data to Mastra platform.
-- External providers: Use exporter pages for Datadog, Langfuse, OpenTelemetry, and other supported platforms.
-
-## Bridges
-
-Bridges connect Mastra to an existing distributed tracing context:
-
-- [OpenTelemetry bridge](https://mastra.ai/integrations/observability/opentelemetry): Integrate Mastra with an existing OpenTelemetry trace.
-- [Datadog bridge](https://mastra.ai/integrations/observability/datadog): Send Mastra traces to Datadog and its LLM Observability product.
-
-## Processors
-
-Processors transform or redact spans before export:
-
-- [Sensitive Data Filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter): Redact sensitive fields before spans leave the runtime.
-
-## Next steps
-
-- [Configuration](https://mastra.ai/docs/observability/overview)
-- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
-- [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)
-- [OpenTelemetry bridge](https://mastra.ai/integrations/observability/opentelemetry)

package/.docs/docs/observability/integrations/processors/sensitive-data-filter.md

@@ -1,302 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Sensitive data filter
-
-The Sensitive Data Filter is a span processor that redacts sensitive information from your traces during the processing pipeline before export. This ensures that passwords, API keys, tokens, and other confidential data never leave your application or get stored in observability platforms.
-
-## Default configuration
-
-The Sensitive Data Filter is included in the recommended observability configuration:
-
-```ts
-import {
-  Observability,
-  MastraStorageExporter,
-  MastraPlatformExporter,
-  SensitiveDataFilter,
-} from '@mastra/observability'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: 'mastra',
-        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
-        spanOutputProcessors: [
-          new SensitiveDataFilter(), // Redacts sensitive fields before export
-        ],
-      },
-    },
-  }),
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: 'file:./mastra.db',
-  }),
-})
-```
-
-With the default configuration, the filter redacts these common sensitive field names:
-
-- `password`
-- `token`
-- `secret`
-- `key`
-- `apikey`
-- `auth`
-- `authorization`
-- `bearer`
-- `bearertoken`
-- `jwt`
-- `credential`
-- `clientsecret`
-- `privatekey`
-- `refresh`
-- `ssn`
-
-> **Note:** Field matching is case-insensitive and normalizes separators. For example, `api-key`, `api_key`, and `Api Key` are all treated as `apikey`.
-
-## How it works
-
-The Sensitive Data Filter processes spans before they're sent to exporters, scanning through:
-
-- **Attributes** - Span metadata and properties
-- **Metadata** - Custom metadata attached to spans
-- **Input** - Data sent to agents, tools, and LLMs
-- **Output** - Responses and results
-- **Error Information** - Stack traces and error details
-
-When a sensitive field is detected, its value is replaced with `[REDACTED]` by default. The filter handles nested objects, arrays, and circular references safely.
-
-## Custom configuration
-
-You can customize which fields are redacted and how redaction displays:
-
-```ts
-import { SensitiveDataFilter, MastraStorageExporter, Observability } from '@mastra/observability'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      production: {
-        serviceName: 'my-service',
-        exporters: [new MastraStorageExporter()],
-        spanOutputProcessors: [
-          new SensitiveDataFilter({
-            // Add custom sensitive fields
-            sensitiveFields: [
-              // Default fields
-              'password',
-              'token',
-              'secret',
-              'key',
-              'apikey',
-              // Custom fields for your application
-              'creditCard',
-              'bankAccount',
-              'routingNumber',
-              'email',
-              'phoneNumber',
-              'dateOfBirth',
-            ],
-            // Custom redaction token
-            redactionToken: '***SENSITIVE***',
-            // Redaction style
-            redactionStyle: 'full', // or 'partial'
-          }),
-        ],
-      },
-    },
-  }),
-})
-```
-
-## Redaction styles
-
-The filter supports two redaction styles:
-
-### Full Redaction (Default)
-
-Replaces the entire value with a fixed token:
-
-```jsonc
-// Before
-{
-  "apiKey": "sk-abc123xyz789def456",
-  "userId": "user_12345"
-}
-
-// After
-{
-  "apiKey": "[REDACTED]",
-  "userId": "user_12345"
-}
-```
-
-### Partial Redaction
-
-Shows the first and last 3 characters, useful for debugging without exposing full values:
-
-```ts
-new SensitiveDataFilter({
-  redactionStyle: 'partial',
-})
-```
-
-```json
-// Before
-{
-  "apiKey": "sk-abc123xyz789def456",
-  "creditCard": "4111111111111111"
-}
-
-// After
-{
-  "apiKey": "sk-…456",
-  "creditCard": "411…111"
-}
-```
-
-Values shorter than 7 characters are fully redacted to prevent information leakage.
-
-## Field matching rules
-
-The filter uses intelligent field matching:
-
-1. **Case-Insensitive**: `APIKey`, `apikey`, and `ApiKey` are all matched
-
-2. **Separator-Agnostic**: `api-key`, `api_key`, and `apiKey` are treated identically
-
-3. **Exact Matching**: After normalization, fields must match exactly
-
-   - `token` matches `token`, `Token`, `TOKEN`
-   - `token` doesn't match `promptTokens` or `tokenCount`
-
-## Nested object handling
-
-The filter recursively processes nested structures:
-
-```json
-// Before
-{
-  "user": {
-    "id": "12345",
-    "credentials": {
-      "password": "SuperSecret123!",
-      "apiKey": "sk-production-key"
-    }
-  },
-  "config": {
-    "auth": {
-      "jwt": "eyJhbGciOiJIUzI1NiIs..."
-    }
-  }
-}
-
-// After
-{
-  "user": {
-    "id": "12345",
-    "credentials": {
-      "password": "[REDACTED]",
-      "apiKey": "[REDACTED]"
-    }
-  },
-  "config": {
-    "auth": {
-      "jwt": "[REDACTED]"
-    }
-  }
-}
-```
-
-## Performance considerations
-
-The Sensitive Data Filter is designed to be lightweight and efficient:
-
-- **Synchronous Processing**: No async operations, minimal latency impact
-- **Circular Reference Handling**: Safely handles complex object graphs
-- **Error Recovery**: If filtering fails, the field is replaced with an error marker rather than crashing
-
-## Disabling the filter
-
-If you need to disable sensitive data filtering (not recommended for production):
-
-```ts
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      debug: {
-        serviceName: 'debug-service',
-        spanOutputProcessors: [], // No processors, including no SensitiveDataFilter
-        exporters: [new MastraStorageExporter()],
-      },
-    },
-  }),
-})
-```
-
-> **Warning:** Only disable sensitive data filtering in controlled environments. Never disable it when sending traces to external services or shared storage.
-
-## Common use cases
-
-### Healthcare Applications
-
-```ts
-new SensitiveDataFilter({
-  sensitiveFields: [
-    // HIPAA-related fields
-    'ssn',
-    'socialSecurityNumber',
-    'medicalRecordNumber',
-    'mrn',
-    'healthInsuranceNumber',
-    'diagnosisCode',
-    'icd10',
-    'prescription',
-    'medication',
-  ],
-})
-```
-
-### Financial Services
-
-```ts
-new SensitiveDataFilter({
-  sensitiveFields: [
-    // PCI compliance fields
-    'creditCard',
-    'ccNumber',
-    'cardNumber',
-    'cvv',
-    'cvc',
-    'securityCode',
-    'expirationDate',
-    'expiry',
-    'bankAccount',
-    'accountNumber',
-    'routingNumber',
-    'iban',
-    'swift',
-  ],
-})
-```
-
-## Error handling
-
-If the filter encounters an error while processing a field, it replaces the field with a safe error marker:
-
-```json
-{
-  "problematicField": {
-    "error": {
-      "processor": "sensitive-data-filter"
-    }
-  }
-}
-```
-
-As a result, processing errors don't prevent traces from being exported or cause application crashes.
-
-## Related
-
-- [SensitiveDataFilter API](https://mastra.ai/reference/observability/tracing/processors/sensitive-data-filter)