@mastra/mcp-docs-server 1.3.8-alpha.2 → 1.3.8-alpha.3
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/docs/agents/tools.md +2 -1
- package/.docs/docs/connections/mcp.md +2 -0
- package/.docs/docs/mastra-platform/connect/providers.md +28 -113
- package/.docs/docs/mastra-platform/observability.md +23 -2
- package/.docs/integrations/databases/clickhouse.md +1 -1
- package/.docs/reference/cli/mastra.md +2 -2
- package/.docs/reference/client-js/observability.md +10 -91
- package/.docs/reference/index.md +1 -1
- package/.docs/reference/observability/tracing/trace-query.md +188 -437
- package/package.json +4 -4
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Tools
|
|
6
6
|
|
|
7
|
-
Agents use tools to call APIs or query databases. They can also run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/connections/mcp) to expand an agent's capabilities.
|
|
7
|
+
Agents use tools to call APIs or query databases. They can also run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/connections/mcp) to expand an agent's capabilities. For services like Linear, Slack, and GitHub, [Connect](https://mastra.ai/docs/mastra-platform/connect/tools) on Mastra platform supplies ready-made tools with managed credentials, which you can combine with your own.
|
|
8
8
|
|
|
9
9
|
**For AI agents:** `execute` has exactly one signature: `execute(inputData, context)`. The first parameter is validated against `inputSchema`. The runtime always provides the second parameter with `requestContext`, `tracingContext`, `abortSignal`, and other execution metadata. You may omit it when unused. Other shapes are outdated. Run `npx mastra api tool execute weather-tool '{"location":"San Francisco"}'` to test this tool directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api tool execute --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
|
|
10
10
|
|
|
@@ -698,6 +698,7 @@ The [AgentController](https://mastra.ai/docs/harness/agent-controller) automatic
|
|
|
698
698
|
- [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
|
|
699
699
|
- [Background tasks](https://mastra.ai/docs/harness/background-tasks): Run long-running tools without blocking the agent loop
|
|
700
700
|
- [MCP overview](https://mastra.ai/docs/connections/mcp)
|
|
701
|
+
- [Connect tools](https://mastra.ai/docs/mastra-platform/connect/tools): Ready-made tools for providers connected to a Mastra platform project
|
|
701
702
|
- [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
|
|
702
703
|
- [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output
|
|
703
704
|
- [Agent approval](https://mastra.ai/docs/agents/human-in-the-loop)
|
|
@@ -8,6 +8,8 @@ Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.
|
|
|
8
8
|
|
|
9
9
|
Use [`MCPClient`](https://mastra.ai/reference/tools/mcp-client) to connect to MCP servers. Use [`MCPServer`](https://mastra.ai/reference/tools/mcp-server) to expose Mastra agents, tools, workflows, prompts, and resources to other MCP-compatible systems. Both speak the MCP `2026-07-28` revision over stdio and Streamable HTTP.
|
|
10
10
|
|
|
11
|
+
For hosted MCP servers such as Neon and Canva, [Connect](https://mastra.ai/docs/mastra-platform/connect/providers) on Mastra platform can manage the OAuth flow and credentials for you, so agents get the server's tools through [`tools()`](https://mastra.ai/docs/mastra-platform/connect/tools) without a hand-configured `MCPClient`.
|
|
12
|
+
|
|
11
13
|
> **Note:** Upgrading from `@mastra/mcp` 1.x? See the [migration guide](https://mastra.ai/reference/migrations/mcp-v2).
|
|
12
14
|
|
|
13
15
|
For credential choices and permission boundaries, see [Authentication and authorization with MCP](https://mastra.ai/docs/guides/mcp-authentication-authorization).
|
|
@@ -10,31 +10,31 @@ A provider is a service you can connect to your project, identified by a provide
|
|
|
10
10
|
|
|
11
11
|
This directory covers the generated toolsets and channel setup documented here, rather than every provider in the platform catalog. Run [`mastra connect list`](https://mastra.ai/reference/cli/mastra) to see providers available to your project and their connection status.
|
|
12
12
|
|
|
13
|
-
| Provider ID | Provider
|
|
14
|
-
| ----------------- |
|
|
15
|
-
| `clerk` |  Clerk
|
|
16
|
-
| `discord` |  Discord
|
|
17
|
-
| `fireflies` |  Fireflies.ai
|
|
18
|
-
| `github` |  GitHub
|
|
19
|
-
| `google-calendar` |  Google Calendar
|
|
20
|
-
| `google-docs` |  Google Docs
|
|
21
|
-
| `google-drive` |  Google Drive
|
|
22
|
-
| `google-mail` |  Gmail
|
|
23
|
-
| `google-sheet` |  Google Sheets
|
|
24
|
-
| `hubspot` |  HubSpot
|
|
25
|
-
| `incident-io` | 
|
|
26
|
-
| `jira` |  Jira
|
|
27
|
-
| `linear` |  Linear
|
|
28
|
-
| `notion` |  Notion
|
|
29
|
-
| `openai` |  OpenAI
|
|
30
|
-
| `posthog` | 
|
|
31
|
-
| `resend` | 
|
|
32
|
-
| `slack` |  Slack
|
|
33
|
-
| `slack-channels` |  Slack channels
|
|
34
|
-
| `snowflake` |  Snowflake
|
|
35
|
-
| `supabase` |  Supabase
|
|
36
|
-
| `telegram` |  Telegram
|
|
37
|
-
| `workos` |  WorkOS
|
|
13
|
+
| Provider ID | Provider | Gives you |
|
|
14
|
+
| ----------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| `clerk` |  Clerk | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
16
|
+
| `discord` |  Discord | [Tools](https://mastra.ai/reference/connect/providers), [Channels](https://mastra.ai/docs/mastra-platform/connect/channels) |
|
|
17
|
+
| `fireflies` |  Fireflies.ai | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
18
|
+
| `github` |  GitHub | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
19
|
+
| `google-calendar` |  Google Calendar | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
20
|
+
| `google-docs` |  Google Docs | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
21
|
+
| `google-drive` |  Google Drive | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
22
|
+
| `google-mail` |  Gmail | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
23
|
+
| `google-sheet` |  Google Sheets | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
24
|
+
| `hubspot` |  HubSpot | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
25
|
+
| `incident-io` |  incident.io | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
26
|
+
| `jira` |  Jira | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
27
|
+
| `linear` |  Linear | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
28
|
+
| `notion` |  Notion | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
29
|
+
| `openai` |  OpenAI | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
30
|
+
| `posthog` |  PostHog | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
31
|
+
| `resend` |  Resend | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
32
|
+
| `slack` |  Slack | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
33
|
+
| `slack-channels` |  Slack channels | [Channels](https://mastra.ai/docs/mastra-platform/connect/channels) |
|
|
34
|
+
| `snowflake` |  Snowflake | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
35
|
+
| `supabase` |  Supabase | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
36
|
+
| `telegram` |  Telegram | [Channels](https://mastra.ai/docs/mastra-platform/connect/channels) |
|
|
37
|
+
| `workos` |  WorkOS | [Tools](https://mastra.ai/reference/connect/providers) |
|
|
38
38
|
|
|
39
39
|
Generated toolsets are included in `@mastra/connect`. Upgrading the package gives you toolsets added in newer releases, but provider availability depends on the platform catalog. The [provider toolsets reference](https://mastra.ai/reference/connect/providers) lists the generated tools.
|
|
40
40
|
|
|
@@ -52,98 +52,13 @@ These providers serve their tools from a hosted Model Context Protocol (MCP) ser
|
|
|
52
52
|
| `robinhood-mcp` |  Robinhood | [Agentic Trading](https://robinhood.com/us/en/support/agentic-trading) |
|
|
53
53
|
| `sanity-mcp` |  Sanity | [Sanity MCP server](https://www.sanity.io/docs/ai/mcp-server) |
|
|
54
54
|
|
|
55
|
-
##
|
|
55
|
+
## Troubleshoot a connection
|
|
56
56
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
### Set up Resend
|
|
60
|
-
|
|
61
|
-
The `resend` toolset sends and reads email and manages domains, contacts, segments, broadcasts, templates, and webhooks. To send from your own domain, [verify it in Resend](https://resend.com/docs/dashboard/domains/introduction).
|
|
62
|
-
|
|
63
|
-
1. In Resend, open [**API Keys**](https://resend.com/api-keys) and select **Create API Key**.
|
|
64
|
-
2. Enter a name, such as `mastra-agents`, and set **Permission** to **Full access**.
|
|
65
|
-
3. Select **Add** and copy the key. It starts with `re_`, and Resend shows it only once.
|
|
66
|
-
4. Run `mastra connect add resend` and paste the key when it asks for **API Key**.
|
|
67
|
-
|
|
68
|
-
A **Sending access** key fails to connect. Mastra checks a new key by listing your domains, which sending access keys can't do. To expose only the sending tool to an agent, use `allowTools`:
|
|
69
|
-
|
|
70
|
-
```typescript
|
|
71
|
-
tools({
|
|
72
|
-
providers: {
|
|
73
|
-
resend: { allowTools: ['resend_send_email'] },
|
|
74
|
-
},
|
|
75
|
-
})
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
This filter controls which tools the agent receives. It doesn't reduce the Resend key's **Full access** permissions.
|
|
79
|
-
|
|
80
|
-
#### Sending safely
|
|
81
|
-
|
|
82
|
-
`resend_send_email` retries a failed send up to three times only when the call includes an `idempotency_key`. Without one it doesn't retry automatically, but a retry elsewhere in your app can still duplicate an email that failed after Resend accepted it. When duplicates matter, tell the agent to set a stable key per logical email, such as `confirmation/order-1234`. Resend answers a reused key with the original response, and rejects a reused key with a different payload with a `409`.
|
|
83
|
-
|
|
84
|
-
If a send fails with a `proxy_error` and status `403`, check that the `from` address uses a domain verified in Resend.
|
|
85
|
-
|
|
86
|
-
### Set up PostHog
|
|
87
|
-
|
|
88
|
-
The `posthog` toolset runs HogQL queries and reads and edits insights, dashboards, feature flags, experiments, surveys, cohorts, and persons. It works with PostHog Cloud in either region. Self-hosted PostHog isn't supported.
|
|
89
|
-
|
|
90
|
-
1. Check your region in PostHog's address bar: `us.posthog.com` or `eu.posthog.com`.
|
|
91
|
-
2. Open [**Settings** > **Personal API keys**](https://us.posthog.com/settings/user-api-keys) on your region's host and select **Create personal API key**.
|
|
92
|
-
3. Limit the key to the organization or projects the agent should see, and choose scopes from the following table.
|
|
93
|
-
4. Create the key and copy it. It starts with `phx_`, and PostHog shows it only once.
|
|
94
|
-
5. Run `mastra connect add posthog`. Choose `us` or `eu` for **Subdomain** and paste the key when it asks for **API Key**.
|
|
95
|
-
|
|
96
|
-
| Scope | Read gives the agent | Write also allows |
|
|
97
|
-
| ------------------- | --------------------------------------------------------------- | ------------------------------------ |
|
|
98
|
-
| `project` | `posthog_list_projects`, `posthog_get_project` | |
|
|
99
|
-
| `query` | `posthog_run_query`, `posthog_list_events`, `posthog_get_event` | |
|
|
100
|
-
| `insight` | List and get insights | Create, update, delete insights |
|
|
101
|
-
| `dashboard` | List and get dashboards | Create, update, delete dashboards |
|
|
102
|
-
| `feature_flag` | List and get feature flags | Create, update, delete feature flags |
|
|
103
|
-
| `experiment` | List and get experiments | Create and update experiments |
|
|
104
|
-
| `survey` | List and get surveys | Create, update, delete surveys |
|
|
105
|
-
| `cohort` | List and get cohorts | Create, update, delete cohorts |
|
|
106
|
-
| `person` | List and get persons | Update and delete persons |
|
|
107
|
-
| `session_recording` | `posthog_list_session_recordings` | |
|
|
108
|
-
|
|
109
|
-
Most PostHog tools take a `project_id`, so give every key `project:read`. Agents call `posthog_list_projects` to find the ID. A read-only analytics agent needs `project:read`, `query:read`, `insight:read`, and `dashboard:read`.
|
|
110
|
-
|
|
111
|
-
Avoid the `us.i` and `eu.i` subdomains. Those hosts only serve PostHog's event ingestion endpoints, so most tools fail with them. The form also rejects project API keys (`phc_`) and project secret API keys (`phs_`).
|
|
112
|
-
|
|
113
|
-
#### Query limits
|
|
114
|
-
|
|
115
|
-
`posthog_run_query` queries count against PostHog's hourly query budget for personal API keys. Prefer aggregated results over raw event exports.
|
|
116
|
-
|
|
117
|
-
### Set up incident.io
|
|
118
|
-
|
|
119
|
-
The `incident-io` toolset reads and updates incidents, posts incident updates, manages actions and follow-ups, and reads alerts, schedules, the catalog, and postmortems. Tool keys start with `incident_io_`, with an underscore where the provider ID has a hyphen.
|
|
120
|
-
|
|
121
|
-
1. In incident.io, open [**Settings** > **API keys**](https://app.incident.io/~/settings/api-keys) and create a key named `mastra-agents` or similar.
|
|
122
|
-
2. Select permissions from the following table. You can only grant permissions you already have.
|
|
123
|
-
3. Create the key and copy it. It starts with `inc_`, and incident.io shows it only once.
|
|
124
|
-
4. Run `mastra connect add incident-io` and paste the key when it asks for **API Key**.
|
|
125
|
-
|
|
126
|
-
| Agent task | Permission |
|
|
127
|
-
| ------------------------------------------------------------------------- | -------------------------- |
|
|
128
|
-
| Read incidents, updates, timelines, actions, follow-ups, users, and teams | **View data** |
|
|
129
|
-
| Read private incidents too | **View all incident data** |
|
|
130
|
-
| Read the catalog | **View catalog** |
|
|
131
|
-
| Read alerts, schedules, and overrides | **View on-call resources** |
|
|
132
|
-
| Open incidents | **Create incidents** |
|
|
133
|
-
| Update incidents, post updates, and manage actions and follow-ups | **Edit incidents** |
|
|
134
|
-
|
|
135
|
-
A triage agent that reads incidents and posts updates needs **View data** and **Edit incidents**, and the incident.io [permissions reference](https://docs.incident.io/admin/api-keys#permissions-reference) describes each permission.
|
|
136
|
-
|
|
137
|
-
#### Creation and rate limits
|
|
138
|
-
|
|
139
|
-
`incident_io_create_incident` requires an `idempotency_key`, and incident.io rejects a second incident with the same key. An API key can open 10 incidents an hour that create a chat channel. Listing incidents is limited to 60 requests a minute. If the agent hits `429` errors, tell it to filter incidents instead of paging through all of them.
|
|
140
|
-
|
|
141
|
-
## Fix a failing provider
|
|
142
|
-
|
|
143
|
-
A `proxy_error` carries the provider's response in its `status` and `detail` properties.
|
|
57
|
+
Most provider call failures come from the connection's credential or configuration. A `proxy_error` carries the provider's response in its `status` and `detail` properties.
|
|
144
58
|
|
|
145
59
|
- **Status `401`:** Check whether the credential has expired, been revoked, or been rotated. If it needs replacing, [reauthorize the connection](https://mastra.ai/reference/cli/mastra).
|
|
146
60
|
- **Status `403`:** Check the provider's response for missing scopes, resource-access restrictions, or account requirements. Grant only the access the agent needs. You can exclude unsupported operations with `allowTools`, but filtering tools doesn't change the credential's permissions.
|
|
147
61
|
- **No tools from a provider:** Run `mastra connect list` to check the project and connection status. Check provider selection and tool filters, and confirm that your installed `@mastra/connect` version includes the toolset. Connection changes follow the resolver's [caching behavior](https://mastra.ai/reference/connect/tools). Check app logs for `[@mastra/connect] Skipping` warnings when a connection can't be resolved.
|
|
62
|
+
- **Resend won't connect:** Use an API key with **Full access** permission. A **Sending access** key fails to connect because Mastra checks a new key by listing your domains, which sending access keys can't do.
|
|
148
63
|
|
|
149
64
|
See [errors](https://mastra.ai/reference/connect/tools) for every error code.
|
|
@@ -138,7 +138,7 @@ Use a consistent `serviceName` to filter data from a specific application or dep
|
|
|
138
138
|
|
|
139
139
|
## Query observability data
|
|
140
140
|
|
|
141
|
-
|
|
141
|
+
Browse hosted traces from the terminal with the Mastra CLI:
|
|
142
142
|
|
|
143
143
|
**npm**:
|
|
144
144
|
|
|
@@ -164,7 +164,28 @@ yarn dlx mastra api trace list
|
|
|
164
164
|
bun x mastra api trace list
|
|
165
165
|
```
|
|
166
166
|
|
|
167
|
-
The CLI
|
|
167
|
+
The CLI reads `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your project environment and targets the US observability endpoint by default. See [CLI target resolution](https://mastra.ai/reference/cli/mastra) for other authentication options and regional endpoints.
|
|
168
|
+
|
|
169
|
+
Use `mastra api trace query` to find completed traces by their fields or related spans. For example, find traces whose root span took more than five seconds:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
npx mastra api trace query '{
|
|
173
|
+
"timeRange": {
|
|
174
|
+
"from": "2026-08-01T00:00:00.000Z",
|
|
175
|
+
"to": "2026-08-08T00:00:00.000Z"
|
|
176
|
+
},
|
|
177
|
+
"where": {
|
|
178
|
+
"op": "gt",
|
|
179
|
+
"left": { "path": "durationMs" },
|
|
180
|
+
"right": { "literal": 5000 }
|
|
181
|
+
},
|
|
182
|
+
"page": { "limit": 25 }
|
|
183
|
+
}'
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Choose a time range containing your exported traces, up to 31 days. Results appear in `data.traces`.
|
|
187
|
+
|
|
188
|
+
Mastra Platform uses the same trace-query endpoints and request format as Mastra Server. Use the [Trace queries API reference](https://mastra.ai/reference/observability/tracing/trace-query) for HTTP requests, supported filters, pagination, polling, and field discovery.
|
|
168
189
|
|
|
169
190
|
You can query exported feedback over HTTP. See the [Feedback API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, project scoping, and supported query parameters such as `traceId` and `environment`.
|
|
170
191
|
|
|
@@ -290,7 +290,7 @@ Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `Shar
|
|
|
290
290
|
|
|
291
291
|
### Observability domain options
|
|
292
292
|
|
|
293
|
-
`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`). `ObservabilityStorageClickhouseVNext` also accepts `retention`, the per-signal TTL in days described in [ClickHouse native TTL](https://mastra.ai/reference/storage/retention), and `traceQuery`, the execution limits for [
|
|
293
|
+
`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`). `ObservabilityStorageClickhouseVNext` also accepts `retention`, the per-signal TTL in days described in [ClickHouse native TTL](https://mastra.ai/reference/storage/retention), and `traceQuery`, the execution limits for [trace queries](https://mastra.ai/reference/observability/tracing/trace-query).
|
|
294
294
|
|
|
295
295
|
## Hosting options
|
|
296
296
|
|
|
@@ -1648,7 +1648,7 @@ mastra api trace list '{"page":0,"perPage":20}' --verbose
|
|
|
1648
1648
|
|
|
1649
1649
|
#### `mastra api trace query`
|
|
1650
1650
|
|
|
1651
|
-
Queries completed observability traces with recursive predicates over trace and related
|
|
1651
|
+
Queries completed observability traces with recursive predicates over trace fields and related spans. The inline JSON input is required and uses the same query structure as the SDK and HTTP API. Like other observability commands, it targets `https://observability.mastra.ai` by default. Pass `--url http://localhost:4111` to query a local server.
|
|
1652
1652
|
|
|
1653
1653
|
```bash
|
|
1654
1654
|
mastra api trace query <input>
|
|
@@ -1672,7 +1672,7 @@ The response remains nested under `data` to preserve cursor pagination:
|
|
|
1672
1672
|
}
|
|
1673
1673
|
```
|
|
1674
1674
|
|
|
1675
|
-
Pass a non-null `page.next` value back as `page.after` in the next query. See [
|
|
1675
|
+
Each invocation makes one query. Pass a non-null `data.page.next` value back as `page.after` in the next query. See [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for supported fields and operators, recursive predicates, limits, pagination, and errors. `--schema` describes the request structure, while the reference lists supported predicate paths and operators.
|
|
1676
1676
|
|
|
1677
1677
|
To load a numbered page and then poll, keep the same time range and predicate in both requests:
|
|
1678
1678
|
|
|
@@ -65,9 +65,9 @@ const selected = await mastraClient.getTrace(list.spans[0].traceId)
|
|
|
65
65
|
|
|
66
66
|
It accepts the same filtering, ordering and delta-polling arguments as `listTraces()`. Use `listTraces()` when you actually need the full span payloads.
|
|
67
67
|
|
|
68
|
-
## Querying traces
|
|
68
|
+
## Querying traces
|
|
69
69
|
|
|
70
|
-
`queryTraces()` finds completed logical traces using trace fields and conditions over related spans
|
|
70
|
+
`queryTraces()` finds completed logical traces using trace fields and conditions over related spans. Every query requires an ISO timestamp range of at most 31 days.
|
|
71
71
|
|
|
72
72
|
```typescript
|
|
73
73
|
const result = await mastraClient.queryTraces({
|
|
@@ -76,12 +76,12 @@ const result = await mastraClient.queryTraces({
|
|
|
76
76
|
to: '2026-08-08T00:00:00.000Z',
|
|
77
77
|
},
|
|
78
78
|
where: {
|
|
79
|
-
|
|
79
|
+
spans: {
|
|
80
80
|
some: {
|
|
81
81
|
op: 'and',
|
|
82
82
|
args: [
|
|
83
|
-
{ op: 'eq', left: { path: '
|
|
84
|
-
{ op: '
|
|
83
|
+
{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'tool_call' } },
|
|
84
|
+
{ op: 'exists', path: 'error' },
|
|
85
85
|
],
|
|
86
86
|
},
|
|
87
87
|
},
|
|
@@ -89,6 +89,8 @@ const result = await mastraClient.queryTraces({
|
|
|
89
89
|
})
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
+
See [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for request fields, predicates, limits, response shapes, and errors.
|
|
93
|
+
|
|
92
94
|
### Load a page and poll for traces
|
|
93
95
|
|
|
94
96
|
`queryTraces()` supports keyset traversal with `page`, numbered pages with `pagination`, and delta polling with `mode: 'delta'`. Use one mode per request. To migrate from `listTracesLight()`, read `traces` instead of `spans` and retain the numbered page's `deltaCursor`:
|
|
@@ -114,7 +116,7 @@ const changes = await mastraClient.queryTraces({
|
|
|
114
116
|
|
|
115
117
|
Merge `changes.traces` by `traceId`, retain `changes.deltaCursor`, and continue while `changes.delta.hasMore` is `true`. Keep the same time range and predicate across polls. Only completed traces are returned; polling doesn't guarantee notifications for related-record updates, deletions, or traces that stop matching.
|
|
116
118
|
|
|
117
|
-
See [Delta polling](https://mastra.ai/reference/observability/tracing/trace-query) for bootstrap behavior, cursor lifetime, retention, and a complete polling loop.
|
|
119
|
+
See [Delta polling](https://mastra.ai/reference/observability/tracing/trace-query) for bootstrap behavior, cursor lifetime, retention, and a complete polling loop.
|
|
118
120
|
|
|
119
121
|
### Discover trace-query fields and values
|
|
120
122
|
|
|
@@ -134,7 +136,7 @@ const fields = await mastraClient.getTraceQueryFields({
|
|
|
134
136
|
})
|
|
135
137
|
```
|
|
136
138
|
|
|
137
|
-
Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A
|
|
139
|
+
Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A field picker can fetch the `trace` and `spans` scopes in parallel.
|
|
138
140
|
|
|
139
141
|
Call `getTraceQueryValues()` only after selecting a field with `valueSuggestions: true`:
|
|
140
142
|
|
|
@@ -162,89 +164,6 @@ Suggestions are bounded and advisory. Manual values remain valid when suggestion
|
|
|
162
164
|
|
|
163
165
|
A discovery timeout rejects with `504 TRACE_QUERY_EXECUTION_TIMEOUT`. Backend memory or resource exhaustion rejects with `503 TRACE_QUERY_RESOURCE_LIMIT`. Neither error contains partial suggestions; truncation flags are only present on successful, completely ranked responses.
|
|
164
166
|
|
|
165
|
-
`queryTraceThreads()` returns thread identities derived from observability traces after applying eligibility and cross-trace conditions. It doesn't read or return memory thread records or messages. In this example, one production trace can have the low factuality score while another production trace in the same thread has the clinician correction:
|
|
166
|
-
|
|
167
|
-
```typescript
|
|
168
|
-
const result = await mastraClient.queryTraceThreads({
|
|
169
|
-
traces: {
|
|
170
|
-
timeRange: {
|
|
171
|
-
from: '2026-08-01T00:00:00.000Z',
|
|
172
|
-
to: '2026-08-08T00:00:00.000Z',
|
|
173
|
-
},
|
|
174
|
-
where: {
|
|
175
|
-
op: 'eq',
|
|
176
|
-
left: { path: 'environment' },
|
|
177
|
-
right: { literal: 'production' },
|
|
178
|
-
},
|
|
179
|
-
},
|
|
180
|
-
where: {
|
|
181
|
-
op: 'and',
|
|
182
|
-
args: [
|
|
183
|
-
{
|
|
184
|
-
traces: {
|
|
185
|
-
some: {
|
|
186
|
-
scores: {
|
|
187
|
-
some: {
|
|
188
|
-
op: 'lt',
|
|
189
|
-
left: { path: 'score' },
|
|
190
|
-
right: { literal: 0.6 },
|
|
191
|
-
},
|
|
192
|
-
},
|
|
193
|
-
},
|
|
194
|
-
},
|
|
195
|
-
},
|
|
196
|
-
{
|
|
197
|
-
traces: {
|
|
198
|
-
some: {
|
|
199
|
-
feedback: {
|
|
200
|
-
some: {
|
|
201
|
-
op: 'eq',
|
|
202
|
-
left: { path: 'feedbackType' },
|
|
203
|
-
right: { literal: 'clinician-correction' },
|
|
204
|
-
},
|
|
205
|
-
},
|
|
206
|
-
},
|
|
207
|
-
},
|
|
208
|
-
},
|
|
209
|
-
],
|
|
210
|
-
},
|
|
211
|
-
})
|
|
212
|
-
|
|
213
|
-
// { threads: [{ threadId: 'thread-123' }], page: { next: null } }
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse trace and thread queries have a configurable 15-second execution timeout.
|
|
217
|
-
|
|
218
|
-
See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, thread qualification semantics, cursor pagination, response shapes, and errors.
|
|
219
|
-
|
|
220
|
-
## Querying spans
|
|
221
|
-
|
|
222
|
-
`querySpans()` returns one row per matching completed span across traces. Use it to list the spans themselves. `queryTraces()` with a `spans.some` predicate returns the traces that contain a matching span instead. Every query requires an ISO timestamp range of at most 31 days.
|
|
223
|
-
|
|
224
|
-
```typescript
|
|
225
|
-
const result = await mastraClient.querySpans({
|
|
226
|
-
timeRange: {
|
|
227
|
-
from: '2026-10-01T00:00:00.000Z',
|
|
228
|
-
to: '2026-10-02T00:00:00.000Z',
|
|
229
|
-
},
|
|
230
|
-
where: {
|
|
231
|
-
op: 'eq',
|
|
232
|
-
left: { path: 'spanType' },
|
|
233
|
-
right: { literal: 'tool_call' },
|
|
234
|
-
},
|
|
235
|
-
orderBy: [{ field: 'startedAt', direction: 'desc' }],
|
|
236
|
-
page: { limit: 50 },
|
|
237
|
-
})
|
|
238
|
-
|
|
239
|
-
// { spans: [{ traceId, spanId, name, spanType, status, durationMs, cost, ... }], page: { next } }
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
Pass `result.page.next` back as `page.after` with the same time range, filter, and ordering to load the next page. Each row contains identifiers, display fields, input and output previews, and the span's model cost. Use `getSpan()` to load the full span.
|
|
243
|
-
|
|
244
|
-
Span queries are optional for observability stores. Check `capabilities.spanQuery` from `getObservabilityCapabilities()` before calling `querySpans()`, and treat a missing value as unsupported. Unsupported servers reject with `501 SPAN_QUERY_UNSUPPORTED`.
|
|
245
|
-
|
|
246
|
-
See [Query individual spans](https://mastra.ai/reference/observability/tracing/trace-query) for filters, ordering, cursors, cost states, limits, and errors.
|
|
247
|
-
|
|
248
167
|
## Deleting traces
|
|
249
168
|
|
|
250
169
|
Delete traces and their associated spans, metrics, logs, scores, and feedback:
|
|
@@ -393,7 +312,7 @@ const ratingPercentiles = await mastraClient.getFeedbackPercentiles({
|
|
|
393
312
|
|
|
394
313
|
## Related
|
|
395
314
|
|
|
396
|
-
- [
|
|
315
|
+
- [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query): Query completed traces with recursive predicates
|
|
397
316
|
- [Feedback guide](https://mastra.ai/docs/observability/feedback): Learn how to create, list, and query feedback
|
|
398
317
|
- [Feedback reference](https://mastra.ai/reference/observability/feedback): Review feedback schemas and HTTP routes
|
|
399
318
|
- [Agents API](https://mastra.ai/reference/client-js/agents): Learn about agent interactions that generate traces
|
package/.docs/reference/index.md
CHANGED
|
@@ -266,11 +266,11 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
266
266
|
- [Automatic Metrics](https://mastra.ai/reference/observability/metrics/automatic-metrics)
|
|
267
267
|
- [Metric queries](https://mastra.ai/reference/observability/metrics/queries)
|
|
268
268
|
- [Configuration](https://mastra.ai/reference/observability/tracing/configuration)
|
|
269
|
-
- [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query)
|
|
270
269
|
- [Instances](https://mastra.ai/reference/observability/tracing/instances)
|
|
271
270
|
- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces)
|
|
272
271
|
- [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering)
|
|
273
272
|
- [Spans](https://mastra.ai/reference/observability/tracing/spans)
|
|
273
|
+
- [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query)
|
|
274
274
|
- [AgentsMDInjector](https://mastra.ai/reference/processors/agents-md-injector)
|
|
275
275
|
- [BatchPartsProcessor](https://mastra.ai/reference/processors/batch-parts-processor)
|
|
276
276
|
- [ClassifierProcessor](https://mastra.ai/reference/processors/classifier-processor)
|