@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.docs/organized/changelogs/%40internal%2Fstorage-test-utils.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fastra.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fchroma.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fconvex.md +29 -0
- package/.docs/organized/changelogs/%40mastra%2Fcore.md +411 -211
- package/.docs/organized/changelogs/%40mastra%2Fcouchbase.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-vercel.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fduckdb.md +42 -0
- package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Felasticsearch.md +52 -0
- package/.docs/organized/changelogs/%40mastra%2Fevals.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Flance.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Flibsql.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Floggers.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fmcp-registry-registry.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fmcp.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fmemory.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fmssql.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fopensearch.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fpg.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fpinecone.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fqdrant.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Frag.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Freact.md +89 -1
- package/.docs/organized/changelogs/%40mastra%2Fs3vectors.md +9 -0
- package/.docs/organized/changelogs/%40mastra%2Fschema-compat.md +42 -0
- package/.docs/organized/changelogs/%40mastra%2Fserver.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fturbopuffer.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fupstash.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvectorize.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-azure.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-cloudflare.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-deepgram.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-elevenlabs.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-gladia.md +92 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-google-gemini-live.md +67 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-google.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-murf.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-openai-realtime.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-openai.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-playai.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-sarvam.md +201 -1
- package/.docs/organized/changelogs/%40mastra%2Fvoice-speechify.md +201 -1
- package/.docs/organized/changelogs/create-mastra.md +201 -1
- package/.docs/organized/changelogs/mastra.md +201 -1
- package/.docs/organized/code-examples/agui.md +1 -0
- package/.docs/organized/code-examples/ai-sdk-v5.md +1 -0
- package/.docs/organized/code-examples/mcp-server-adapters.md +721 -0
- package/.docs/organized/code-examples/memory-with-processors.md +1 -1
- package/.docs/organized/code-examples/quick-start.md +1 -1
- package/.docs/organized/code-examples/server-app-access.md +342 -0
- package/.docs/raw/agents/adding-voice.mdx +7 -10
- package/.docs/raw/agents/agent-approval.mdx +189 -0
- package/.docs/raw/agents/guardrails.mdx +26 -23
- package/.docs/raw/agents/networks.mdx +2 -2
- package/.docs/raw/agents/overview.mdx +27 -62
- package/.docs/raw/agents/processors.mdx +279 -0
- package/.docs/raw/agents/using-tools.mdx +4 -5
- package/.docs/raw/course/01-first-agent/05-running-playground.md +5 -5
- package/.docs/raw/course/01-first-agent/09-testing-your-agent.md +3 -3
- package/.docs/raw/course/01-first-agent/13-testing-your-tool.md +3 -3
- package/.docs/raw/course/01-first-agent/17-testing-memory.md +2 -2
- package/.docs/raw/course/04-workflows/07-using-playground.md +1 -1
- package/.docs/raw/deployment/building-mastra.mdx +1 -1
- package/.docs/raw/deployment/cloud-providers/amazon-ec2.mdx +1 -1
- package/.docs/raw/deployment/cloud-providers/aws-lambda.mdx +1 -1
- package/.docs/raw/deployment/cloud-providers/azure-app-services.mdx +1 -1
- package/.docs/raw/deployment/cloud-providers/digital-ocean.mdx +1 -1
- package/.docs/raw/deployment/cloud-providers/index.mdx +20 -27
- package/.docs/raw/deployment/cloud-providers/netlify-deployer.mdx +44 -13
- package/.docs/raw/deployment/mastra-cloud/observability.mdx +19 -17
- package/.docs/raw/deployment/mastra-cloud/setting-up.mdx +1 -1
- package/.docs/raw/deployment/overview.mdx +2 -2
- package/.docs/raw/deployment/web-framework.mdx +5 -5
- package/.docs/raw/evals/custom-scorers.mdx +3 -5
- package/.docs/raw/evals/overview.mdx +2 -3
- package/.docs/raw/evals/running-in-ci.mdx +0 -2
- package/.docs/raw/{guides/guide → getting-started}/manual-install.mdx +2 -2
- package/.docs/raw/getting-started/project-structure.mdx +1 -1
- package/.docs/raw/getting-started/start.mdx +72 -0
- package/.docs/raw/getting-started/studio.mdx +1 -1
- package/.docs/raw/{frameworks/agentic-uis/ai-sdk.mdx → guides/build-your-ui/ai-sdk-ui.mdx} +113 -11
- package/.docs/raw/{frameworks/web-frameworks → guides/getting-started}/astro.mdx +23 -25
- package/.docs/raw/{frameworks/servers → guides/getting-started}/express.mdx +3 -4
- package/.docs/raw/guides/{quickstarts/nextjs.mdx → getting-started/next-js.mdx} +11 -11
- package/.docs/raw/guides/{quickstarts/standalone-server.mdx → getting-started/quickstart.mdx} +7 -7
- package/.docs/raw/{frameworks/web-frameworks → guides/getting-started}/sveltekit.mdx +23 -25
- package/.docs/raw/{frameworks/web-frameworks → guides/getting-started}/vite-react.mdx +7 -7
- package/.docs/raw/guides/guide/ai-recruiter.mdx +2 -3
- package/.docs/raw/guides/guide/chef-michel.mdx +2 -3
- package/.docs/raw/guides/guide/notes-mcp-server.mdx +2 -2
- package/.docs/raw/guides/guide/research-assistant.mdx +7 -8
- package/.docs/raw/guides/guide/stock-agent.mdx +4 -6
- package/.docs/raw/guides/guide/web-search.mdx +12 -10
- package/.docs/raw/guides/guide/whatsapp-chat-bot.mdx +421 -0
- package/.docs/raw/guides/index.mdx +3 -35
- package/.docs/raw/guides/migrations/agentnetwork.mdx +4 -4
- package/.docs/raw/guides/migrations/ai-sdk-v4-to-v5.mdx +1 -1
- package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx +40 -0
- package/.docs/raw/guides/migrations/upgrade-to-v1/tools.mdx +5 -0
- package/.docs/raw/guides/migrations/upgrade-to-v1/workflows.mdx +51 -0
- package/.docs/raw/guides/migrations/vnext-to-standard-apis.mdx +2 -2
- package/.docs/raw/index.mdx +2 -2
- package/.docs/raw/mcp/overview.mdx +3 -5
- package/.docs/raw/memory/memory-processors.mdx +264 -79
- package/.docs/raw/memory/semantic-recall.mdx +7 -7
- package/.docs/raw/memory/storage/memory-with-libsql.mdx +2 -4
- package/.docs/raw/memory/storage/memory-with-mongodb.mdx +2 -4
- package/.docs/raw/memory/storage/memory-with-pg.mdx +2 -4
- package/.docs/raw/memory/storage/memory-with-upstash.mdx +2 -4
- package/.docs/raw/memory/threads-and-resources.mdx +3 -3
- package/.docs/raw/memory/working-memory.mdx +14 -7
- package/.docs/raw/{logging.mdx → observability/logging.mdx} +1 -1
- package/.docs/raw/observability/overview.mdx +2 -3
- package/.docs/raw/observability/tracing/bridges/otel.mdx +176 -0
- package/.docs/raw/observability/tracing/exporters/arize.mdx +17 -0
- package/.docs/raw/observability/tracing/exporters/braintrust.mdx +19 -0
- package/.docs/raw/observability/tracing/exporters/langfuse.mdx +20 -0
- package/.docs/raw/observability/tracing/exporters/langsmith.mdx +12 -0
- package/.docs/raw/observability/tracing/exporters/otel.mdx +25 -5
- package/.docs/raw/observability/tracing/exporters/posthog.mdx +107 -0
- package/.docs/raw/observability/tracing/overview.mdx +74 -8
- package/.docs/raw/observability/tracing/processors/sensitive-data-filter.mdx +0 -1
- package/.docs/raw/rag/chunking-and-embedding.mdx +16 -17
- package/.docs/raw/rag/overview.mdx +3 -2
- package/.docs/raw/rag/retrieval.mdx +43 -38
- package/.docs/raw/rag/vector-databases.mdx +93 -2
- package/.docs/raw/reference/agents/agent.mdx +7 -10
- package/.docs/raw/reference/agents/generate.mdx +55 -6
- package/.docs/raw/reference/agents/generateLegacy.mdx +2 -2
- package/.docs/raw/reference/agents/getLLM.mdx +1 -1
- package/.docs/raw/reference/agents/network.mdx +46 -3
- package/.docs/raw/reference/cli/mastra.mdx +2 -1
- package/.docs/raw/reference/client-js/agents.mdx +3 -3
- package/.docs/raw/reference/client-js/memory.mdx +43 -0
- package/.docs/raw/reference/client-js/workflows.mdx +92 -63
- package/.docs/raw/reference/core/getLogger.mdx +1 -1
- package/.docs/raw/reference/core/listLogs.mdx +1 -1
- package/.docs/raw/reference/core/listLogsByRunId.mdx +1 -1
- package/.docs/raw/reference/core/mastra-model-gateway.mdx +5 -19
- package/.docs/raw/reference/core/setLogger.mdx +1 -1
- package/.docs/raw/reference/core/setTelemetry.mdx +1 -1
- package/.docs/raw/reference/deployer/netlify.mdx +1 -2
- package/.docs/raw/reference/evals/answer-relevancy.mdx +28 -98
- package/.docs/raw/reference/evals/answer-similarity.mdx +12 -258
- package/.docs/raw/reference/evals/bias.mdx +29 -87
- package/.docs/raw/reference/evals/completeness.mdx +31 -90
- package/.docs/raw/reference/evals/content-similarity.mdx +28 -88
- package/.docs/raw/reference/evals/context-precision.mdx +28 -130
- package/.docs/raw/reference/evals/context-relevance.mdx +11 -11
- package/.docs/raw/reference/evals/faithfulness.mdx +28 -101
- package/.docs/raw/reference/evals/hallucination.mdx +28 -103
- package/.docs/raw/reference/evals/keyword-coverage.mdx +28 -107
- package/.docs/raw/reference/evals/noise-sensitivity.mdx +11 -11
- package/.docs/raw/reference/evals/prompt-alignment.mdx +15 -15
- package/.docs/raw/reference/evals/scorer-utils.mdx +362 -0
- package/.docs/raw/reference/evals/textual-difference.mdx +27 -100
- package/.docs/raw/reference/evals/tone-consistency.mdx +25 -98
- package/.docs/raw/reference/evals/tool-call-accuracy.mdx +7 -7
- package/.docs/raw/reference/evals/toxicity.mdx +29 -92
- package/.docs/raw/reference/index.mdx +1 -0
- package/.docs/raw/reference/memory/memory-class.mdx +5 -7
- package/.docs/raw/reference/observability/tracing/bridges/otel.mdx +150 -0
- package/.docs/raw/reference/observability/tracing/configuration.mdx +0 -4
- package/.docs/raw/reference/observability/tracing/exporters/arize.mdx +4 -0
- package/.docs/raw/reference/observability/tracing/exporters/langsmith.mdx +17 -1
- package/.docs/raw/reference/observability/tracing/exporters/otel.mdx +6 -0
- package/.docs/raw/reference/observability/tracing/exporters/posthog.mdx +132 -0
- package/.docs/raw/reference/observability/tracing/instances.mdx +0 -4
- package/.docs/raw/reference/observability/tracing/interfaces.mdx +29 -4
- package/.docs/raw/reference/observability/tracing/spans.mdx +0 -4
- package/.docs/raw/reference/processors/batch-parts-processor.mdx +1 -1
- package/.docs/raw/reference/processors/language-detector.mdx +10 -3
- package/.docs/raw/reference/processors/message-history-processor.mdx +131 -0
- package/.docs/raw/reference/processors/moderation-processor.mdx +12 -5
- package/.docs/raw/reference/processors/pii-detector.mdx +12 -5
- package/.docs/raw/reference/processors/processor-interface.mdx +502 -0
- package/.docs/raw/reference/processors/prompt-injection-detector.mdx +10 -3
- package/.docs/raw/reference/processors/semantic-recall-processor.mdx +197 -0
- package/.docs/raw/reference/processors/system-prompt-scrubber.mdx +3 -4
- package/.docs/raw/reference/processors/token-limiter-processor.mdx +2 -2
- package/.docs/raw/reference/processors/tool-call-filter.mdx +125 -0
- package/.docs/raw/reference/processors/unicode-normalizer.mdx +1 -1
- package/.docs/raw/reference/processors/working-memory-processor.mdx +221 -0
- package/.docs/raw/reference/rag/embeddings.mdx +5 -5
- package/.docs/raw/reference/rag/rerank.mdx +1 -2
- package/.docs/raw/reference/rag/rerankWithScorer.mdx +0 -1
- package/.docs/raw/reference/storage/cloudflare-d1.mdx +37 -0
- package/.docs/raw/reference/storage/convex.mdx +164 -0
- package/.docs/raw/reference/storage/lance.mdx +33 -0
- package/.docs/raw/reference/storage/libsql.mdx +37 -0
- package/.docs/raw/reference/storage/mongodb.mdx +39 -0
- package/.docs/raw/reference/storage/mssql.mdx +37 -0
- package/.docs/raw/reference/storage/postgresql.mdx +37 -0
- package/.docs/raw/reference/streaming/ChunkType.mdx +1 -1
- package/.docs/raw/reference/streaming/agents/stream.mdx +64 -2
- package/.docs/raw/reference/streaming/workflows/observeStream.mdx +7 -9
- package/.docs/raw/reference/streaming/workflows/{resumeStreamVNext.mdx → resumeStream.mdx} +51 -11
- package/.docs/raw/reference/streaming/workflows/stream.mdx +83 -24
- package/.docs/raw/reference/templates/overview.mdx +1 -4
- package/.docs/raw/reference/tools/client.mdx +1 -2
- package/.docs/raw/reference/tools/create-tool.mdx +132 -0
- package/.docs/raw/reference/tools/graph-rag-tool.mdx +5 -5
- package/.docs/raw/reference/tools/mcp-client.mdx +76 -21
- package/.docs/raw/reference/tools/mcp-server.mdx +1 -2
- package/.docs/raw/reference/tools/vector-query-tool.mdx +14 -15
- package/.docs/raw/reference/vectors/chroma.mdx +81 -1
- package/.docs/raw/reference/vectors/convex.mdx +429 -0
- package/.docs/raw/reference/vectors/couchbase.mdx +24 -17
- package/.docs/raw/reference/vectors/duckdb.mdx +462 -0
- package/.docs/raw/reference/vectors/elasticsearch.mdx +310 -0
- package/.docs/raw/reference/vectors/lance.mdx +38 -22
- package/.docs/raw/reference/vectors/libsql.mdx +35 -2
- package/.docs/raw/reference/vectors/mongodb.mdx +35 -2
- package/.docs/raw/reference/vectors/opensearch.mdx +37 -16
- package/.docs/raw/reference/vectors/pg.mdx +43 -36
- package/.docs/raw/reference/vectors/pinecone.mdx +48 -1
- package/.docs/raw/reference/vectors/qdrant.mdx +36 -1
- package/.docs/raw/reference/vectors/turbopuffer.mdx +74 -0
- package/.docs/raw/reference/voice/google.mdx +159 -20
- package/.docs/raw/reference/voice/openai-realtime.mdx +2 -2
- package/.docs/raw/reference/voice/voice.addInstructions.mdx +2 -3
- package/.docs/raw/reference/voice/voice.addTools.mdx +1 -1
- package/.docs/raw/reference/voice/voice.answer.mdx +1 -1
- package/.docs/raw/reference/voice/voice.close.mdx +1 -1
- package/.docs/raw/reference/voice/voice.connect.mdx +1 -1
- package/.docs/raw/reference/voice/voice.off.mdx +1 -1
- package/.docs/raw/reference/voice/voice.on.mdx +1 -1
- package/.docs/raw/reference/voice/voice.send.mdx +1 -1
- package/.docs/raw/reference/voice/voice.updateConfig.mdx +1 -1
- package/.docs/raw/reference/workflows/run-methods/restart.mdx +142 -0
- package/.docs/raw/reference/workflows/run-methods/resume.mdx +44 -0
- package/.docs/raw/reference/workflows/run-methods/start.mdx +44 -0
- package/.docs/raw/reference/workflows/run.mdx +13 -5
- package/.docs/raw/reference/workflows/step.mdx +13 -0
- package/.docs/raw/reference/workflows/workflow.mdx +19 -0
- package/.docs/raw/server-db/mastra-client.mdx +1 -2
- package/.docs/raw/server-db/mastra-server.mdx +30 -1
- package/.docs/raw/server-db/request-context.mdx +0 -1
- package/.docs/raw/server-db/storage.mdx +11 -0
- package/.docs/raw/streaming/overview.mdx +26 -15
- package/.docs/raw/streaming/tool-streaming.mdx +48 -5
- package/.docs/raw/streaming/workflow-streaming.mdx +5 -11
- package/.docs/raw/tools-mcp/advanced-usage.mdx +1 -2
- package/.docs/raw/tools-mcp/mcp-overview.mdx +3 -5
- package/.docs/raw/voice/overview.mdx +21 -41
- package/.docs/raw/voice/speech-to-speech.mdx +4 -4
- package/.docs/raw/voice/speech-to-text.mdx +1 -2
- package/.docs/raw/voice/text-to-speech.mdx +1 -2
- package/.docs/raw/workflows/control-flow.mdx +180 -0
- package/.docs/raw/workflows/error-handling.mdx +1 -0
- package/.docs/raw/workflows/human-in-the-loop.mdx +4 -4
- package/.docs/raw/workflows/overview.mdx +56 -44
- package/.docs/raw/workflows/snapshots.mdx +1 -0
- package/.docs/raw/workflows/suspend-and-resume.mdx +85 -16
- package/.docs/raw/workflows/time-travel.mdx +313 -0
- package/.docs/raw/workflows/workflow-state.mdx +191 -0
- package/CHANGELOG.md +18 -0
- package/dist/{chunk-5NJC7NRO.js → chunk-4CM2BQNP.js} +24 -4
- package/dist/prepare-docs/package-changes.d.ts.map +1 -1
- package/dist/prepare-docs/prepare.js +1 -1
- package/dist/stdio.js +1 -1
- package/package.json +7 -7
- package/.docs/raw/agents/human-in-the-loop-with-tools.mdx +0 -90
- package/.docs/raw/frameworks/agentic-uis/cedar-os.mdx +0 -102
- package/.docs/raw/frameworks/agentic-uis/openrouter.mdx +0 -179
- package/.docs/raw/frameworks/web-frameworks/next-js.mdx +0 -379
- package/.docs/raw/getting-started/quickstart.mdx +0 -27
- package/.docs/raw/getting-started/templates.mdx +0 -73
- package/.docs/raw/reference/streaming/workflows/observeStreamVNext.mdx +0 -47
- package/.docs/raw/reference/streaming/workflows/streamVNext.mdx +0 -153
- /package/.docs/raw/{frameworks/agentic-uis → guides/build-your-ui}/assistant-ui.mdx +0 -0
- /package/.docs/raw/{frameworks/agentic-uis → guides/build-your-ui}/copilotkit.mdx +0 -0
|
@@ -11,7 +11,7 @@ When deploying to Mastra Cloud, logs are shown on the [Logs](/docs/v1/deployment
|
|
|
11
11
|
|
|
12
12
|
## Configuring logs with PinoLogger
|
|
13
13
|
|
|
14
|
-
When [initializing a new Mastra project](/guides/v1/
|
|
14
|
+
When [initializing a new Mastra project](/guides/v1/getting-started/quickstart) using the CLI, `PinoLogger` is included by default.
|
|
15
15
|
|
|
16
16
|
```typescript title="src/mastra/index.ts" showLineNumbers copy
|
|
17
17
|
import { Mastra } from "@mastra/core/mastra";
|
|
@@ -43,11 +43,10 @@ export const mastra = new Mastra({
|
|
|
43
43
|
|
|
44
44
|
With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
|
|
45
45
|
|
|
46
|
-
We also support various external tracing providers like Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](/docs/v1/observability/tracing/overview) documentation.
|
|
46
|
+
We also support various external tracing providers like MLflow, Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](/docs/v1/observability/tracing/overview) documentation.
|
|
47
47
|
|
|
48
48
|
## What's Next?
|
|
49
49
|
|
|
50
50
|
- **[Set up Tracing](/docs/v1/observability/tracing/overview)**: Configure tracing for your application
|
|
51
|
-
- **[Configure Logging](/docs/v1/logging)**: Add structured logging
|
|
52
|
-
- **[View Examples](/examples/v1/observability/basic-ai-tracing)**: See observability in action
|
|
51
|
+
- **[Configure Logging](/docs/v1/observability/logging)**: Add structured logging
|
|
53
52
|
- **[API Reference](/reference/v1/observability/tracing/instances)**: Detailed configuration options
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "OpenTelemetry Bridge | Tracing | Observability"
|
|
3
|
+
description: "Integrate Mastra tracing with existing OpenTelemetry infrastructure"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# OpenTelemetry Bridge
|
|
7
|
+
|
|
8
|
+
:::warning
|
|
9
|
+
|
|
10
|
+
The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
|
|
11
|
+
|
|
12
|
+
:::
|
|
13
|
+
|
|
14
|
+
The OpenTelemetry (OTEL) Bridge enables bidirectional integration between Mastra's tracing system and existing OpenTelemetry infrastructure. Unlike exporters that send trace data to external platforms, the bridge creates native OTEL spans that participate in your distributed tracing context.
|
|
15
|
+
|
|
16
|
+
:::info Looking to send traces without existing OTEL infrastructure?
|
|
17
|
+
|
|
18
|
+
If you don't have existing OpenTelemetry instrumentation, the [OpenTelemetry Exporter](/docs/v1/observability/tracing/exporters/otel) may be simpler — it sends traces directly without requiring an OTEL SDK setup.
|
|
19
|
+
|
|
20
|
+
:::
|
|
21
|
+
|
|
22
|
+
## When to Use the Bridge
|
|
23
|
+
|
|
24
|
+
Use the OtelBridge when you:
|
|
25
|
+
|
|
26
|
+
- Have existing OTEL instrumentation in your application (HTTP servers, database clients, etc.)
|
|
27
|
+
- Want Mastra operations to appear as child spans of your existing OTEL traces
|
|
28
|
+
- Need OTEL-instrumented code inside Mastra tools to maintain proper parent-child relationships
|
|
29
|
+
- Are building a distributed system where trace context must propagate across services
|
|
30
|
+
|
|
31
|
+
## How It Works
|
|
32
|
+
|
|
33
|
+
The OtelBridge provides two-way integration:
|
|
34
|
+
|
|
35
|
+
**From OTEL to Mastra:**
|
|
36
|
+
- Reads from OTEL ambient context (AsyncLocalStorage) automatically
|
|
37
|
+
- Inherits trace ID and parent span ID from active OTEL spans
|
|
38
|
+
- Respects OTEL sampling decisions — if a trace is not sampled, Mastra won't create spans for it
|
|
39
|
+
- No manual trace ID passing required when OTEL auto-instrumentation is active
|
|
40
|
+
|
|
41
|
+
**From Mastra to OTEL:**
|
|
42
|
+
- Creates native OTEL spans for Mastra operations (agents, LLM calls, tools, workflows)
|
|
43
|
+
- Maintains proper parent-child relationships in distributed traces
|
|
44
|
+
- Allows OTEL-instrumented code (HTTP clients, database calls) within Mastra operations to nest correctly
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
```bash npm2yarn
|
|
49
|
+
npm install @mastra/otel-bridge
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The bridge works with your existing OpenTelemetry setup. Depending on your configuration, you may also need some of these packages:
|
|
53
|
+
|
|
54
|
+
- `@opentelemetry/sdk-node` - Core Node.js SDK for OTEL
|
|
55
|
+
- `@opentelemetry/auto-instrumentations-node` - Auto-instrumentation for common libraries
|
|
56
|
+
- `@opentelemetry/exporter-trace-otlp-proto` - OTLP exporter (Protobuf over HTTP)
|
|
57
|
+
- `@opentelemetry/exporter-trace-otlp-http` - OTLP exporter (JSON over HTTP)
|
|
58
|
+
- `@opentelemetry/exporter-trace-otlp-grpc` - OTLP exporter (gRPC)
|
|
59
|
+
- `@opentelemetry/sdk-trace-base` - Base tracing SDK (for BatchSpanProcessor, etc.)
|
|
60
|
+
- `@opentelemetry/core` - Core utilities (for W3CTraceContextPropagator, etc.)
|
|
61
|
+
|
|
62
|
+
## Configuration
|
|
63
|
+
|
|
64
|
+
Using the OtelBridge requires two steps:
|
|
65
|
+
|
|
66
|
+
1. Configure OpenTelemetry instrumentation in your application
|
|
67
|
+
2. Add the OtelBridge to your Mastra observability config
|
|
68
|
+
|
|
69
|
+
### Step 1: OpenTelemetry Instrumentation
|
|
70
|
+
|
|
71
|
+
Create an instrumentation file that initializes OTEL. This must run before your application code:
|
|
72
|
+
|
|
73
|
+
```typescript title="instrumentation.ts" showLineNumbers copy
|
|
74
|
+
import { NodeSDK } from "@opentelemetry/sdk-node";
|
|
75
|
+
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
|
|
76
|
+
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
|
|
77
|
+
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
|
|
78
|
+
import { W3CTraceContextPropagator } from "@opentelemetry/core";
|
|
79
|
+
|
|
80
|
+
const sdk = new NodeSDK({
|
|
81
|
+
serviceName: "my-service",
|
|
82
|
+
spanProcessors: [
|
|
83
|
+
new BatchSpanProcessor(
|
|
84
|
+
new OTLPTraceExporter({
|
|
85
|
+
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318/v1/traces",
|
|
86
|
+
})
|
|
87
|
+
),
|
|
88
|
+
],
|
|
89
|
+
instrumentations: [getNodeAutoInstrumentations()],
|
|
90
|
+
textMapPropagator: new W3CTraceContextPropagator(),
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
sdk.start();
|
|
94
|
+
|
|
95
|
+
export { sdk };
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Step 2: Mastra Configuration
|
|
99
|
+
|
|
100
|
+
Add the OtelBridge to your Mastra observability config:
|
|
101
|
+
|
|
102
|
+
```typescript title="src/mastra/index.ts" showLineNumbers copy
|
|
103
|
+
import { Mastra } from "@mastra/core";
|
|
104
|
+
import { Observability } from "@mastra/observability";
|
|
105
|
+
import { OtelBridge } from "@mastra/otel-bridge";
|
|
106
|
+
|
|
107
|
+
export const mastra = new Mastra({
|
|
108
|
+
observability: new Observability({
|
|
109
|
+
configs: {
|
|
110
|
+
default: {
|
|
111
|
+
serviceName: "my-service",
|
|
112
|
+
bridge: new OtelBridge(),
|
|
113
|
+
},
|
|
114
|
+
},
|
|
115
|
+
}),
|
|
116
|
+
agents: {
|
|
117
|
+
/* your agents */
|
|
118
|
+
},
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
No Mastra exporters are required when using the bridge — traces are sent via your OTEL SDK configuration. You can optionally add Mastra exporters if you want to send traces to additional destinations.
|
|
123
|
+
|
|
124
|
+
### Running Your Application
|
|
125
|
+
|
|
126
|
+
Use the `--import` flag to ensure instrumentation loads before your application:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
tsx --import ./instrumentation.ts ./src/index.ts
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Trace Hierarchy
|
|
133
|
+
|
|
134
|
+
With the OtelBridge, your traces maintain proper hierarchy across OTEL and Mastra boundaries:
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
HTTP POST /api/chat (from Hono middleware)
|
|
138
|
+
└── agent.assistant (from Mastra via OtelBridge)
|
|
139
|
+
├── chat gpt-4o (LLM call)
|
|
140
|
+
├── tool.execute search (tool execution)
|
|
141
|
+
│ └── HTTP GET api.example.com (from OTEL auto-instrumentation)
|
|
142
|
+
└── chat gpt-4o (follow-up LLM call)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Multi-Service Distributed Tracing
|
|
146
|
+
|
|
147
|
+
The OtelBridge enables trace propagation across service boundaries. When Service A calls Service B via HTTP, trace context propagates automatically:
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
Service A: HTTP POST /api/process
|
|
151
|
+
└── HTTP POST service-b/api/analyze (outgoing call)
|
|
152
|
+
|
|
153
|
+
Service B: HTTP POST /api/analyze (incoming call - same trace!)
|
|
154
|
+
└── agent.analyzer (Mastra agent inherits trace context)
|
|
155
|
+
└── chat gpt-4o
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Both services must have:
|
|
159
|
+
1. OTEL instrumentation configured
|
|
160
|
+
2. W3C Trace Context propagator enabled
|
|
161
|
+
3. Mastra with OtelBridge configured
|
|
162
|
+
|
|
163
|
+
## Troubleshooting
|
|
164
|
+
|
|
165
|
+
If traces aren't appearing or connecting as expected:
|
|
166
|
+
|
|
167
|
+
- Verify OTEL SDK is initialized before Mastra (use `--import` flag or import at top of entry point)
|
|
168
|
+
- Ensure the OtelBridge is added to your observability config
|
|
169
|
+
- Check that your OTEL backend is running and accessible
|
|
170
|
+
|
|
171
|
+
## Related
|
|
172
|
+
|
|
173
|
+
- [Tracing Overview](/docs/v1/observability/tracing/overview)
|
|
174
|
+
- [OpenTelemetry Exporter](/docs/v1/observability/tracing/exporters/otel) - For sending traces to OTEL backends
|
|
175
|
+
- [OtelBridge Reference](/reference/v1/observability/tracing/bridges/otel) - API documentation
|
|
176
|
+
- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
|
|
@@ -182,6 +182,23 @@ new ArizeExporter({
|
|
|
182
182
|
});
|
|
183
183
|
```
|
|
184
184
|
|
|
185
|
+
### Custom metadata
|
|
186
|
+
|
|
187
|
+
Non-reserved span attributes are serialized into the OpenInference `metadata` payload and surface in Arize/Phoenix. You can add them via `tracingOptions.metadata`:
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
await agent.generate(input, {
|
|
191
|
+
tracingOptions: {
|
|
192
|
+
metadata: {
|
|
193
|
+
companyId: "acme-co",
|
|
194
|
+
tier: "enterprise",
|
|
195
|
+
},
|
|
196
|
+
},
|
|
197
|
+
});
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and OpenInference IDs are excluded automatically.
|
|
201
|
+
|
|
185
202
|
## OpenInference Semantic Conventions
|
|
186
203
|
|
|
187
204
|
This exporter implements the [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
|
|
@@ -65,6 +65,25 @@ new BraintrustExporter({
|
|
|
65
65
|
});
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
+
## Using Tags
|
|
69
|
+
|
|
70
|
+
Tags help you categorize and filter traces in the Braintrust dashboard. Add tags when executing agents or workflows:
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
const result = await agent.generate({
|
|
74
|
+
messages: [{ role: "user", content: "Hello" }],
|
|
75
|
+
tracingOptions: {
|
|
76
|
+
tags: ["production", "experiment-v2", "user-request"],
|
|
77
|
+
},
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Tags appear in Braintrust's trace view and can be used to filter and search traces. Common use cases include:
|
|
82
|
+
|
|
83
|
+
- Environment labels: `"production"`, `"staging"`
|
|
84
|
+
- Experiment tracking: `"experiment-v1"`, `"control-group"`
|
|
85
|
+
- Priority levels: `"priority-high"`, `"batch-job"`
|
|
86
|
+
|
|
68
87
|
## Related
|
|
69
88
|
|
|
70
89
|
- [Tracing Overview](/docs/v1/observability/tracing/overview)
|
|
@@ -107,6 +107,26 @@ new LangfuseExporter({
|
|
|
107
107
|
});
|
|
108
108
|
```
|
|
109
109
|
|
|
110
|
+
## Using Tags
|
|
111
|
+
|
|
112
|
+
Tags help you categorize and filter traces in the Langfuse dashboard. Add tags when executing agents or workflows:
|
|
113
|
+
|
|
114
|
+
```typescript
|
|
115
|
+
const result = await agent.generate({
|
|
116
|
+
messages: [{ role: "user", content: "Hello" }],
|
|
117
|
+
tracingOptions: {
|
|
118
|
+
tags: ["production", "experiment-v2", "user-request"],
|
|
119
|
+
},
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Tags appear in Langfuse's trace view and can be used to filter and search traces. Common use cases include:
|
|
124
|
+
|
|
125
|
+
- Environment labels: `"production"`, `"staging"`
|
|
126
|
+
- Experiment tracking: `"experiment-v1"`, `"control-group"`
|
|
127
|
+
- Priority levels: `"priority-high"`, `"batch-job"`
|
|
128
|
+
- User segments: `"beta-user"`, `"enterprise"`
|
|
129
|
+
|
|
110
130
|
## Related
|
|
111
131
|
|
|
112
132
|
- [Tracing Overview](/docs/v1/observability/tracing/overview)
|
|
@@ -23,6 +23,7 @@ npm install @mastra/langsmith@beta
|
|
|
23
23
|
|
|
24
24
|
```bash title=".env"
|
|
25
25
|
LANGSMITH_API_KEY=ls-xxxxxxxxxxxx
|
|
26
|
+
LANGCHAIN_PROJECT=my-project # Optional: default project for traces
|
|
26
27
|
LANGSMITH_BASE_URL=https://api.smith.langchain.com # Optional for self-hosted
|
|
27
28
|
```
|
|
28
29
|
|
|
@@ -60,6 +61,7 @@ new LangSmithExporter({
|
|
|
60
61
|
|
|
61
62
|
// Optional settings
|
|
62
63
|
apiUrl: process.env.LANGSMITH_BASE_URL, // Default: https://api.smith.langchain.com
|
|
64
|
+
projectName: "my-project", // Project to send traces to (overrides LANGCHAIN_PROJECT env var)
|
|
63
65
|
callerOptions: {
|
|
64
66
|
// HTTP client options
|
|
65
67
|
timeout: 30000, // Request timeout in ms
|
|
@@ -73,6 +75,16 @@ new LangSmithExporter({
|
|
|
73
75
|
});
|
|
74
76
|
```
|
|
75
77
|
|
|
78
|
+
### Environment Variables
|
|
79
|
+
|
|
80
|
+
| Variable | Description |
|
|
81
|
+
|----------|-------------|
|
|
82
|
+
| `LANGSMITH_API_KEY` | Your LangSmith API key (required) |
|
|
83
|
+
| `LANGCHAIN_PROJECT` | Default project name for traces (optional, defaults to "default") |
|
|
84
|
+
| `LANGSMITH_BASE_URL` | API URL for self-hosted instances (optional) |
|
|
85
|
+
|
|
86
|
+
The `projectName` config option takes precedence over the `LANGCHAIN_PROJECT` environment variable, allowing you to programmatically route traces to different projects.
|
|
87
|
+
|
|
76
88
|
## Related
|
|
77
89
|
|
|
78
90
|
- [Tracing Overview](/docs/v1/observability/tracing/overview)
|
|
@@ -5,19 +5,19 @@ description: "Send traces to any OpenTelemetry-compatible observability platform
|
|
|
5
5
|
|
|
6
6
|
# OpenTelemetry Exporter
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
:::info Looking for bidirectional OTEL integration?
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel) instead.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
:::
|
|
15
15
|
|
|
16
16
|
## Installation
|
|
17
17
|
|
|
18
18
|
Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:
|
|
19
19
|
|
|
20
|
-
### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar)
|
|
20
|
+
### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow)
|
|
21
21
|
|
|
22
22
|
```bash npm2yarn
|
|
23
23
|
npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-proto
|
|
@@ -37,6 +37,25 @@ npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-http
|
|
|
37
37
|
|
|
38
38
|
## Provider Configurations
|
|
39
39
|
|
|
40
|
+
|
|
41
|
+
### MLflow
|
|
42
|
+
|
|
43
|
+
[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces land in the correct MLflow experiment:
|
|
44
|
+
|
|
45
|
+
```typescript title="src/mastra/index.ts"
|
|
46
|
+
new OtelExporter({
|
|
47
|
+
provider: {
|
|
48
|
+
custom: {
|
|
49
|
+
endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
|
|
50
|
+
protocol: "http/protobuf",
|
|
51
|
+
headers: {
|
|
52
|
+
"x-mlflow-experiment-id": process.env.MLFLOW_EXPERIMENT_ID,
|
|
53
|
+
},
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
})
|
|
57
|
+
```
|
|
58
|
+
|
|
40
59
|
### Dash0
|
|
41
60
|
|
|
42
61
|
[Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.
|
|
@@ -250,5 +269,6 @@ Install the suggested package for your provider.
|
|
|
250
269
|
## Related
|
|
251
270
|
|
|
252
271
|
- [Tracing Overview](/docs/v1/observability/tracing/overview)
|
|
272
|
+
- [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel) - For bidirectional OTEL context integration
|
|
253
273
|
- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
|
|
254
274
|
- [OTEL Exporter Reference](/reference/v1/observability/tracing/exporters/otel)
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "PostHog Exporter | Tracing | Observability"
|
|
3
|
+
description: "Send traces to PostHog for AI observability and analytics"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PostHog Exporter
|
|
7
|
+
|
|
8
|
+
[PostHog](https://posthog.com/) is an analytics platform with AI observability features for monitoring LLM applications. The PostHog exporter sends your traces to PostHog as structured events, providing insights into token usage, costs, latency, and conversation flows.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```bash npm2yarn
|
|
13
|
+
npm install @mastra/posthog@beta
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Configuration
|
|
17
|
+
|
|
18
|
+
### Prerequisites
|
|
19
|
+
|
|
20
|
+
1. **PostHog Account**: Sign up at [posthog.com](https://posthog.com/)
|
|
21
|
+
2. **Project API Key**: Get your project API key from PostHog Settings → Project API Key
|
|
22
|
+
3. **Environment Variables**: Set your credentials
|
|
23
|
+
|
|
24
|
+
```bash title=".env"
|
|
25
|
+
POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxx
|
|
26
|
+
POSTHOG_HOST=https://us.i.posthog.com # Optional: EU region or self-hosted URL
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Basic Setup
|
|
30
|
+
|
|
31
|
+
```typescript title="src/mastra/index.ts"
|
|
32
|
+
import { Mastra } from "@mastra/core";
|
|
33
|
+
import { Observability } from "@mastra/observability";
|
|
34
|
+
import { PosthogExporter } from "@mastra/posthog";
|
|
35
|
+
|
|
36
|
+
export const mastra = new Mastra({
|
|
37
|
+
observability: new Observability({
|
|
38
|
+
configs: {
|
|
39
|
+
posthog: {
|
|
40
|
+
serviceName: "my-service",
|
|
41
|
+
exporters: [
|
|
42
|
+
new PosthogExporter({
|
|
43
|
+
apiKey: process.env.POSTHOG_API_KEY,
|
|
44
|
+
}),
|
|
45
|
+
],
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
}),
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Configuration Options
|
|
53
|
+
|
|
54
|
+
### Complete Configuration
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
new PosthogExporter({
|
|
58
|
+
// Required credentials
|
|
59
|
+
apiKey: process.env.POSTHOG_API_KEY!,
|
|
60
|
+
|
|
61
|
+
// Optional settings
|
|
62
|
+
host: "https://us.i.posthog.com", // Default: US region
|
|
63
|
+
// or "https://eu.i.posthog.com" for EU region
|
|
64
|
+
// or your self-hosted URL
|
|
65
|
+
|
|
66
|
+
// Batching configuration
|
|
67
|
+
flushAt: 20, // Batch size (default: 20)
|
|
68
|
+
flushInterval: 10000, // Flush interval in ms (default: 10000)
|
|
69
|
+
serverless: false, // Serverless mode: flushAt=10, flushInterval=2000
|
|
70
|
+
|
|
71
|
+
// User identification
|
|
72
|
+
defaultDistinctId: "anonymous", // Fallback if no userId in metadata
|
|
73
|
+
|
|
74
|
+
// Privacy settings
|
|
75
|
+
enablePrivacyMode: false, // Excludes input/output from generation events
|
|
76
|
+
|
|
77
|
+
// Diagnostic logging
|
|
78
|
+
logLevel: "info", // debug | info | warn | error
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Serverless Mode
|
|
83
|
+
|
|
84
|
+
Optimized batching for serverless environments:
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
new PosthogExporter({
|
|
88
|
+
apiKey: process.env.POSTHOG_API_KEY!,
|
|
89
|
+
serverless: true, // Configures smaller batches for faster flushing
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Privacy Mode
|
|
94
|
+
|
|
95
|
+
Exclude input/output data from generation events while preserving token metrics:
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
new PosthogExporter({
|
|
99
|
+
apiKey: process.env.POSTHOG_API_KEY!,
|
|
100
|
+
enablePrivacyMode: true, // Removes $ai_input and $ai_output_choices
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Related
|
|
105
|
+
|
|
106
|
+
- [Tracing Overview](/docs/v1/observability/tracing/overview)
|
|
107
|
+
- [PostHog Documentation](https://posthog.com/docs)
|
|
@@ -97,7 +97,24 @@ In addition to the internal exporters, Mastra supports integration with popular
|
|
|
97
97
|
- **[Langfuse](/docs/v1/observability/tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
|
|
98
98
|
- **[LangSmith](/docs/v1/observability/tracing/exporters/langsmith)** - Pushes traces into LangSmith's observability and evaluation toolkit
|
|
99
99
|
- **[OpenTelemetry](/docs/v1/observability/tracing/exporters/otel)** - Deliver traces to any OpenTelemetry-compatible observability system
|
|
100
|
-
- Supports: Dash0, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
|
|
100
|
+
- Supports: Dash0, MLflow, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
|
|
101
|
+
|
|
102
|
+
## Bridges
|
|
103
|
+
|
|
104
|
+
Bridges provide bidirectional integration with external tracing systems. Unlike exporters that send trace data to external platforms, bridges create native spans in external systems and inherit context from them. This enables Mastra operations to participate in existing distributed traces.
|
|
105
|
+
|
|
106
|
+
- **[OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel)** - Integrate with existing OpenTelemetry infrastructure
|
|
107
|
+
|
|
108
|
+
### Bridges vs Exporters
|
|
109
|
+
|
|
110
|
+
| Feature | Bridges | Exporters |
|
|
111
|
+
| --- | --- | --- |
|
|
112
|
+
| Creates native spans in external systems | Yes | No |
|
|
113
|
+
| Inherits context from external systems | Yes | No |
|
|
114
|
+
| Sends data to backends | Via external SDK | Directly |
|
|
115
|
+
| Use case | Existing distributed tracing | Standalone Mastra tracing |
|
|
116
|
+
|
|
117
|
+
You can use both together — a bridge for context propagation and exporters to send traces to additional destinations.
|
|
101
118
|
|
|
102
119
|
## Sampling Strategies
|
|
103
120
|
|
|
@@ -200,7 +217,6 @@ Use `configSelector` to choose the appropriate tracing configuration based on re
|
|
|
200
217
|
```ts title="src/mastra/index.ts" showLineNumbers copy
|
|
201
218
|
export const mastra = new Mastra({
|
|
202
219
|
observability: new Observability({
|
|
203
|
-
default: { enabled: true }, // Provides 'default' instance
|
|
204
220
|
configs: {
|
|
205
221
|
langfuse: {
|
|
206
222
|
serviceName: "langfuse-service",
|
|
@@ -233,7 +249,7 @@ export const mastra = new Mastra({
|
|
|
233
249
|
return "langfuse";
|
|
234
250
|
}
|
|
235
251
|
|
|
236
|
-
|
|
252
|
+
throw new Error('no config found')
|
|
237
253
|
},
|
|
238
254
|
}),
|
|
239
255
|
});
|
|
@@ -448,6 +464,55 @@ requestContext.set("session", { data: { experimentId: "exp-999" } });
|
|
|
448
464
|
3. **Child Span Extraction**: Child spans can also extract metadata if you pass `requestContext` when creating them
|
|
449
465
|
4. **Metadata Precedence**: Explicit metadata passed to span options always takes precedence over extracted metadata
|
|
450
466
|
|
|
467
|
+
### Adding Tags to Traces
|
|
468
|
+
|
|
469
|
+
Tags are string labels that help you categorize and filter traces. Unlike metadata (which contains structured key-value data), tags are simple strings designed for quick filtering and organization.
|
|
470
|
+
|
|
471
|
+
Use `tracingOptions.tags` to add tags when executing agents or workflows:
|
|
472
|
+
|
|
473
|
+
```ts showLineNumbers copy
|
|
474
|
+
// With agents
|
|
475
|
+
const result = await agent.generate({
|
|
476
|
+
messages: [{ role: "user", content: "Hello" }],
|
|
477
|
+
tracingOptions: {
|
|
478
|
+
tags: ["production", "experiment-v2", "user-request"],
|
|
479
|
+
},
|
|
480
|
+
});
|
|
481
|
+
|
|
482
|
+
// With workflows
|
|
483
|
+
const run = await mastra.getWorkflow("myWorkflow").createRun();
|
|
484
|
+
const result = await run.start({
|
|
485
|
+
inputData: { data: "process this" },
|
|
486
|
+
tracingOptions: {
|
|
487
|
+
tags: ["batch-processing", "priority-high"],
|
|
488
|
+
},
|
|
489
|
+
});
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
#### How Tags Work
|
|
493
|
+
|
|
494
|
+
- **Root span only**: Tags are applied only to the root span of a trace (the agent run or workflow run span)
|
|
495
|
+
- **Platform-specific**: Tags appear in Braintrust and Langfuse dashboards for filtering and searching
|
|
496
|
+
- **Combinable with metadata**: You can use both `tags` and `metadata` in the same `tracingOptions`
|
|
497
|
+
|
|
498
|
+
```ts showLineNumbers copy
|
|
499
|
+
const result = await agent.generate({
|
|
500
|
+
messages: [{ role: "user", content: "Analyze this" }],
|
|
501
|
+
tracingOptions: {
|
|
502
|
+
tags: ["production", "analytics"],
|
|
503
|
+
metadata: { userId: "user-123", experimentId: "exp-456" },
|
|
504
|
+
},
|
|
505
|
+
});
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
#### Common Tag Patterns
|
|
509
|
+
|
|
510
|
+
- **Environment**: `"production"`, `"staging"`, `"development"`
|
|
511
|
+
- **Feature flags**: `"feature-x-enabled"`, `"beta-user"`
|
|
512
|
+
- **Request types**: `"user-request"`, `"batch-job"`, `"scheduled-task"`
|
|
513
|
+
- **Priority levels**: `"priority-high"`, `"priority-low"`
|
|
514
|
+
- **Experiments**: `"experiment-v1"`, `"control-group"`, `"treatment-a"`
|
|
515
|
+
|
|
451
516
|
#### Child Spans and Metadata Extraction
|
|
452
517
|
|
|
453
518
|
When creating child spans within tools or workflow steps, you can pass the `requestContext` parameter to enable metadata extraction:
|
|
@@ -619,7 +684,7 @@ console.log("Trace ID:", finalState.traceId);
|
|
|
619
684
|
Once you have a trace ID, you can:
|
|
620
685
|
|
|
621
686
|
1. **Look up traces in Studio**: Navigate to the traces view and search by ID
|
|
622
|
-
2. **Query traces in external platforms**: Use the ID in Langfuse, Braintrust, or your observability platform
|
|
687
|
+
2. **Query traces in external platforms**: Use the ID in Langfuse, Braintrust, MLflow, or your observability platform
|
|
623
688
|
3. **Correlate with logs**: Include the trace ID in your application logs for cross-referencing
|
|
624
689
|
4. **Share for debugging**: Provide trace IDs to support teams or developers for investigation
|
|
625
690
|
|
|
@@ -751,10 +816,6 @@ Mastra automatically creates spans for:
|
|
|
751
816
|
|
|
752
817
|
## See Also
|
|
753
818
|
|
|
754
|
-
### Examples
|
|
755
|
-
|
|
756
|
-
- [Basic Tracing Example](/examples/v1/observability/basic-ai-tracing) - Working implementation
|
|
757
|
-
|
|
758
819
|
### Reference Documentation
|
|
759
820
|
|
|
760
821
|
- [Configuration API](/reference/v1/observability/tracing/configuration) - ObservabilityConfig details
|
|
@@ -770,8 +831,13 @@ Mastra automatically creates spans for:
|
|
|
770
831
|
- [Arize](/reference/v1/observability/tracing/exporters/arize) - Arize Phoenix and Arize AX integration
|
|
771
832
|
- [Braintrust](/reference/v1/observability/tracing/exporters/braintrust) - Braintrust integration
|
|
772
833
|
- [Langfuse](/reference/v1/observability/tracing/exporters/langfuse) - Langfuse integration
|
|
834
|
+
- [MLflow](/reference/v1/observability/tracing/exporters/otel#mlflow) - MLflow OTLP endpoint setup
|
|
773
835
|
- [OpenTelemetry](/reference/v1/observability/tracing/exporters/otel) - OTEL-compatible platforms
|
|
774
836
|
|
|
837
|
+
### Bridges
|
|
838
|
+
|
|
839
|
+
- [OpenTelemetry Bridge](/reference/v1/observability/tracing/bridges/otel) - OTEL context integration
|
|
840
|
+
|
|
775
841
|
### Processors
|
|
776
842
|
|
|
777
843
|
- [Sensitive Data Filter](/docs/v1/observability/tracing/processors/sensitive-data-filter) - Data redaction
|
|
@@ -293,4 +293,3 @@ This ensures that processing errors don't prevent traces from being exported or
|
|
|
293
293
|
## Related
|
|
294
294
|
|
|
295
295
|
- [SensitiveDataFilter API](/reference/v1/observability/tracing/processors/sensitive-data-filter)
|
|
296
|
-
- [Basic Tracing Example](/examples/v1/observability/basic-ai-tracing)
|