@mastra/client-js 1.59.0-alpha.0 → 1.59.0-alpha.1
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/dist/docs/SKILL.md +1 -1
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/reference-client-js-observability.md +2 -0
- package/dist/docs/references/reference-observability-tracing-advanced-queries.md +58 -14
- package/dist/route-types.generated.d.ts +6 -4
- package/dist/route-types.generated.d.ts.map +1 -1
- package/package.json +2 -2
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-client-js
|
|
|
3
3
|
description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/client-js"
|
|
6
|
-
version: "1.59.0-alpha.
|
|
6
|
+
version: "1.59.0-alpha.1"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -115,6 +115,8 @@ if (capabilities.spanAggregate) {
|
|
|
115
115
|
|
|
116
116
|
The request and response structure follows `aggregateTraces()`, with direct span predicates and span dimensions such as `spanType`, `name`, and `parentEntityName`. Token and cost measures belong to the span that recorded the usage and aren't added to parent spans. Check `capabilities.spanAggregate` before calling, and `capabilities.spanAggregateModelDimensions` before grouping or counting distinct values by `model` or `provider`. With an older adapter, those requests return `501`.
|
|
117
117
|
|
|
118
|
+
Both `aggregateTraces()` and `aggregateSpans()` accept `timeToFirstToken.*` and `timeToFirstChunk.*` measures when `capabilities.aggregateTimeToFirstMeasures` is `true`. Spans and traces without a recorded value are skipped, never counted as 0. See [Time to first token and chunk measures](https://mastra.ai/reference/observability/tracing/advanced-queries).
|
|
119
|
+
|
|
118
120
|
See [Aggregate spans](https://mastra.ai/reference/observability/tracing/advanced-queries) for selection, dimensions, per-span usage, and how to list the spans behind a group.
|
|
119
121
|
|
|
120
122
|
## Querying threads
|
|
@@ -44,6 +44,7 @@ The configured observability store must support each API. Call `getObservability
|
|
|
44
44
|
| `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs` |
|
|
45
45
|
| `traceQueryTimeToFirstToken` | `trace-query-time-to-first-token` | `timeToFirstTokenMs` predicates and results |
|
|
46
46
|
| `traceQueryTimeToFirstTokenSort` | `trace-query-time-to-first-token-sort` | `orderBy` on `timeToFirstTokenMs` |
|
|
47
|
+
| `aggregateTimeToFirstMeasures` | `aggregate-time-to-first-measures` | `timeToFirstToken.*` and `timeToFirstChunk.*` measures in `aggregateTraces()` and `aggregateSpans()` |
|
|
47
48
|
| `traceQueryContextIds` | `trace-query-context-ids` | `runId`, `sessionId`, `userId`, and `organizationId` predicates |
|
|
48
49
|
| `traceQueryRootSpanFields` | `trace-query-root-span-fields` | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
|
|
49
50
|
| `traceQueryRootEntityId` | `trace-query-root-entity-id` | Trace-scope `entityId` predicates, dimensions, and `countDistinct` measures |
|
|
@@ -811,20 +812,26 @@ Every dimension except `serviceName`, `executionSource`, and `experimentId` is a
|
|
|
811
812
|
|
|
812
813
|
### Measures
|
|
813
814
|
|
|
814
|
-
| Measure
|
|
815
|
-
|
|
|
816
|
-
| `count`
|
|
817
|
-
| `countDistinct.<field>`
|
|
818
|
-
| `duration.avg`, `duration.min`, `duration.max`
|
|
819
|
-
| `duration.p50`, `duration.p90`, `duration.p95`, `duration.p99`
|
|
820
|
-
| `errorCount`
|
|
821
|
-
| `errorRate`
|
|
822
|
-
| `tokens.input.sum`, `tokens.input.avg`
|
|
823
|
-
| `tokens.output.sum`, `tokens.output.avg`
|
|
824
|
-
| `tokens.total.sum`, `tokens.total.avg`
|
|
825
|
-
| `tokens.reasoning.sum`, `tokens.reasoning.avg`
|
|
826
|
-
| `tokens.cached.sum`, `tokens.cached.avg`
|
|
827
|
-
| `cost.sum`, `cost.avg`
|
|
815
|
+
| Measure | Value |
|
|
816
|
+
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
817
|
+
| `count` | Number of selected traces. |
|
|
818
|
+
| `countDistinct.<field>` | Number of distinct non-null values of a dimension or `traceId`, such as `countDistinct.userId`. |
|
|
819
|
+
| `duration.avg`, `duration.min`, `duration.max` | Root span duration in milliseconds. |
|
|
820
|
+
| `duration.p50`, `duration.p90`, `duration.p95`, `duration.p99` | Root span duration percentile in milliseconds. Percentiles can be approximate, depending on the store. |
|
|
821
|
+
| `errorCount` | Number of traces whose root span recorded an error. |
|
|
822
|
+
| `errorRate` | `errorCount` divided by `count`, from 0 to 1. |
|
|
823
|
+
| `tokens.input.sum`, `tokens.input.avg` | Input tokens. |
|
|
824
|
+
| `tokens.output.sum`, `tokens.output.avg` | Output tokens. |
|
|
825
|
+
| `tokens.total.sum`, `tokens.total.avg` | Input plus output tokens. |
|
|
826
|
+
| `tokens.reasoning.sum`, `tokens.reasoning.avg` | Reasoning output tokens. |
|
|
827
|
+
| `tokens.cached.sum`, `tokens.cached.avg` | Input tokens read from the provider's cache. |
|
|
828
|
+
| `cost.sum`, `cost.avg` | Estimated model cost. |
|
|
829
|
+
| `timeToFirstToken.avg`, `timeToFirstToken.min`, `timeToFirstToken.max` | Root span time to first token in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
830
|
+
| `timeToFirstToken.p50`, `timeToFirstToken.p90`, `timeToFirstToken.p95`, `timeToFirstToken.p99` | Root span time to first token percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
831
|
+
| `timeToFirstToken.count` | Number of traces whose root span recorded a time to first token. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
832
|
+
| `timeToFirstChunk.avg`, `timeToFirstChunk.min`, `timeToFirstChunk.max` | Root span time to first chunk in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
833
|
+
| `timeToFirstChunk.p50`, `timeToFirstChunk.p90`, `timeToFirstChunk.p95`, `timeToFirstChunk.p99` | Root span time to first chunk percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
834
|
+
| `timeToFirstChunk.count` | Number of traces whose root span recorded a time to first chunk. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
828
835
|
|
|
829
836
|
Numeric measures over metadata aren't supported.
|
|
830
837
|
|
|
@@ -845,6 +852,34 @@ When you request any `cost.*` measure, every row also includes a `cost` object:
|
|
|
845
852
|
|
|
846
853
|
`cost.sum` and `cost.avg` are `null` when the group has no priced traces or `unit` is `'mixed'`. A coverage below 1 means the cost understates the group's spend. The `cost` object isn't a measure, so `having` and `orderBy` can't reference it.
|
|
847
854
|
|
|
855
|
+
#### Time to first token and chunk measures
|
|
856
|
+
|
|
857
|
+
`timeToFirstToken.*` and `timeToFirstChunk.*` read the root span's `timeToFirstTokenMs` and `timeToFirstChunkMs`, the same values [`queryTraces()`](#query-traces) returns. An agent run copies them from the first model generation of its own loop:
|
|
858
|
+
|
|
859
|
+
- `timeToFirstChunk.*` is measured from the agent run's start, so it includes work done before the first model call, such as input processors and memory recall.
|
|
860
|
+
- `timeToFirstToken.*` is the time to first token of the model call that streamed that first chunk.
|
|
861
|
+
|
|
862
|
+
Traces without a value are skipped, never counted as 0. This includes traces whose agent run didn't stream, and traces rooted in a workflow, since a workflow run records neither value. `avg`, `min`, `max`, and the percentiles are `null` for a group where no trace has a value, and `.count` is the number of traces that do have one. Percentiles can be approximate, depending on the store.
|
|
863
|
+
|
|
864
|
+
Stores advertise support through the `aggregate-time-to-first-measures` feature, and the server reports it as the `aggregateTimeToFirstMeasures` capability. Against an older store, a request for any of these measures returns `501` before storage runs, and [field discovery](#discover-fields-and-values) omits them.
|
|
865
|
+
|
|
866
|
+
```typescript
|
|
867
|
+
const { capabilities } = await mastraClient.getObservabilityCapabilities()
|
|
868
|
+
|
|
869
|
+
if (capabilities.traceAggregate && capabilities.aggregateTimeToFirstMeasures) {
|
|
870
|
+
const { rows } = await mastraClient.aggregateTraces({
|
|
871
|
+
timeRange: {
|
|
872
|
+
from: '2026-08-01T00:00:00.000Z',
|
|
873
|
+
to: '2026-08-02T00:00:00.000Z',
|
|
874
|
+
},
|
|
875
|
+
where: { op: 'eq', left: { path: 'entityType' }, right: { literal: 'agent' } },
|
|
876
|
+
groupBy: ['entityName'],
|
|
877
|
+
measures: ['timeToFirstChunk.p50', 'timeToFirstChunk.p95', 'timeToFirstChunk.count'],
|
|
878
|
+
orderBy: { field: 'timeToFirstChunk.p95', direction: 'desc' },
|
|
879
|
+
})
|
|
880
|
+
}
|
|
881
|
+
```
|
|
882
|
+
|
|
848
883
|
### Filter and order groups
|
|
849
884
|
|
|
850
885
|
A group is one distinct combination of `groupBy` values. `having`, `orderBy`, and `limit` operate on groups and use each group's measures over the whole time range, even when `interval` is set. The server applies `having` first, then orders the remaining groups and keeps the first `limit`. `truncated` is `true` when more groups remained than `limit`.
|
|
@@ -976,6 +1011,15 @@ Aggregation uses the same span predicates as [`querySpans()`](#query-spans), wit
|
|
|
976
1011
|
|
|
977
1012
|
`count` counts selected spans in each group or time bucket. Buckets use each span's `startedAt`. `duration.*` measures read the span's own duration, and `errorCount` and `errorRate` read whether the span itself recorded an error.
|
|
978
1013
|
|
|
1014
|
+
`timeToFirstToken.*` and `timeToFirstChunk.*` read the span's own `timeToFirstTokenMs` and `timeToFirstChunkMs`, and skip spans without a value. Several span types record them:
|
|
1015
|
+
|
|
1016
|
+
- `model_inference`: each provider call. Filter to this type for per-call time to first token.
|
|
1017
|
+
- `model_step`: each step of a generation, with the values of the inference that streamed the step's first chunk.
|
|
1018
|
+
- `model_generation`: the whole generation, with the values of its first streamed inference only. A multi-step generation, such as a tool loop, reports only its first call.
|
|
1019
|
+
- `agent_run`: the agent run, with time to first chunk measured from the run's start. Filter to this type for latency as the caller of each agent sees it.
|
|
1020
|
+
|
|
1021
|
+
Without a `spanType` filter, one agent call contributes its agent run, its model generation, and every model step and model inference.
|
|
1022
|
+
|
|
979
1023
|
On ClickHouse, a direct `spanType` `eq` or `in` predicate, or one immediately inside an `and`, can select the smaller branch table. All selected types must be branch types: `agent_run`, `workflow_run`, `processor_run`, `scorer_run`, `rag_ingestion`, `tool_call`, or `mcp_tool_call`. Every requested field must be available in that table. An equivalent `or` predicate doesn't select this optimization. The branch path can differ from `querySpans()`:
|
|
980
1024
|
|
|
981
1025
|
- Spans written before an upgrade from `@mastra/clickhouse` 1.4, 1.5, or 1.6 aren't in the branch table, so older windows can count fewer spans.
|
|
@@ -384,7 +384,7 @@ type InputShared_Type_13 = {
|
|
|
384
384
|
};
|
|
385
385
|
type InputShared_Type_14 = 'agent_run' | 'scorer_run' | 'classifier_evaluation' | 'scorer_step' | 'generic' | 'model_generation' | 'model_step' | 'model_inference' | 'model_chunk' | 'mcp_tool_call' | 'mcp_server_request' | 'processor_run' | 'tool_call' | 'client_tool_call' | 'provider_tool_call' | 'workflow_run' | 'workflow_step' | 'workflow_conditional' | 'workflow_conditional_eval' | 'workflow_parallel' | 'workflow_loop' | 'workflow_sleep' | 'workflow_wait_event' | 'memory_operation' | 'workspace_action' | 'rag_ingestion' | 'rag_embedding' | 'rag_vector_operation' | 'rag_action' | 'graph_action' | 'mapping' | 'skill_resolution' | 'skill_action' | 'agent_signal';
|
|
386
386
|
type InputShared_Type_15 = 'agent' | 'scorer' | 'rag_ingestion' | 'trajectory' | 'input_processor' | 'input_step_processor' | 'output_processor' | 'output_step_processor' | 'tool_result_processor' | 'workflow_step' | 'tool' | 'mcp_server' | 'workflow_run' | 'memory' | 'classifier';
|
|
387
|
-
type InputShared_Type_16 = 'count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg';
|
|
387
|
+
type InputShared_Type_16 = 'count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg' | 'timeToFirstToken.avg' | 'timeToFirstToken.min' | 'timeToFirstToken.max' | 'timeToFirstToken.p50' | 'timeToFirstToken.p90' | 'timeToFirstToken.p95' | 'timeToFirstToken.p99' | 'timeToFirstToken.count' | 'timeToFirstChunk.avg' | 'timeToFirstChunk.min' | 'timeToFirstChunk.max' | 'timeToFirstChunk.p50' | 'timeToFirstChunk.p90' | 'timeToFirstChunk.p95' | 'timeToFirstChunk.p99' | 'timeToFirstChunk.count';
|
|
388
388
|
type InputShared_Type_17 = {
|
|
389
389
|
/** Filter by timestamp range */
|
|
390
390
|
timestamp?: InputShared_Type_13 | undefined;
|
|
@@ -2857,6 +2857,8 @@ type Shared_Type_67 = {
|
|
|
2857
2857
|
spanQueryModelFields: boolean;
|
|
2858
2858
|
/** `model` and `provider` in span aggregate `groupBy` and `countDistinct`. Treat a missing value as unavailable. */
|
|
2859
2859
|
spanAggregateModelDimensions: boolean;
|
|
2860
|
+
/** `timeToFirstToken.*` and `timeToFirstChunk.*` measures in trace and span aggregates. Treat a missing value as unavailable. */
|
|
2861
|
+
aggregateTimeToFirstMeasures: boolean;
|
|
2860
2862
|
/** `outcome` and `stopReason` predicates in span queries and span aggregates (including `groupBy` and `countDistinct`), and `outcome`, `stopReason` and `stopReasonContext` on span rows. Treat a missing value as unavailable. */
|
|
2861
2863
|
spanQueryOutcomeFields: boolean;
|
|
2862
2864
|
/** The root span's `outcome` and `stopReason` in trace-scope predicates and trace aggregates, both fields in `spans.some`/`spans.none` predicates and value discovery, and the root span's `outcome`, `stopReason` and `stopReasonContext` on trace rows. Treat a missing value as unavailable. */
|
|
@@ -8280,7 +8282,7 @@ export type PostObservabilityTracesAggregate_Response = {
|
|
|
8280
8282
|
} | undefined;
|
|
8281
8283
|
bucket?: string | undefined;
|
|
8282
8284
|
measures: {
|
|
8283
|
-
[K in ('count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg') | `countDistinct.${string}`]?: number | null;
|
|
8285
|
+
[K in ('count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg' | 'timeToFirstToken.avg' | 'timeToFirstToken.min' | 'timeToFirstToken.max' | 'timeToFirstToken.p50' | 'timeToFirstToken.p90' | 'timeToFirstToken.p95' | 'timeToFirstToken.p99' | 'timeToFirstToken.count' | 'timeToFirstChunk.avg' | 'timeToFirstChunk.min' | 'timeToFirstChunk.max' | 'timeToFirstChunk.p50' | 'timeToFirstChunk.p90' | 'timeToFirstChunk.p95' | 'timeToFirstChunk.p99' | 'timeToFirstChunk.count') | `countDistinct.${string}`]?: number | null;
|
|
8284
8286
|
};
|
|
8285
8287
|
cost?: {
|
|
8286
8288
|
coverage: number | null;
|
|
@@ -8556,8 +8558,8 @@ export type PostObservabilityTracesQueryFields_Response = {
|
|
|
8556
8558
|
}[];
|
|
8557
8559
|
measures: {
|
|
8558
8560
|
name: string;
|
|
8559
|
-
kind: 'count' | 'duration' | 'error' | 'tokens' | 'cost';
|
|
8560
|
-
statistic?: ('avg' | 'min' | 'max' | 'p50' | 'p90' | 'p95' | 'p99' | 'sum') | undefined;
|
|
8561
|
+
kind: 'count' | 'duration' | 'error' | 'tokens' | 'cost' | 'timeToFirstToken' | 'timeToFirstChunk';
|
|
8562
|
+
statistic?: ('avg' | 'min' | 'max' | 'p50' | 'p90' | 'p95' | 'p99' | 'sum' | 'count') | undefined;
|
|
8561
8563
|
unit: 'count' | 'milliseconds' | 'ratio' | 'tokens' | 'currency';
|
|
8562
8564
|
approximate: boolean;
|
|
8563
8565
|
}[];
|