@mastra/observability 1.17.5-alpha.0 → 1.17.5-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.
Files changed (2) hide show
  1. package/README.md +14 -85
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # Mastra Observability
1
+ # @mastra/observability
2
2
 
3
- Tracing, metrics, and structured logging for AI operations in Mastra.
3
+ Monitor Mastra agents, workflows, tools, and model calls with hierarchical traces, automatically extracted metrics, and structured logs correlated to the active trace.
4
4
 
5
5
  ## Installation
6
6
 
@@ -8,7 +8,7 @@ Tracing, metrics, and structured logging for AI operations in Mastra.
8
8
  npm install @mastra/observability
9
9
  ```
10
10
 
11
- ## Quick Start
11
+ ## Usage
12
12
 
13
13
  ```typescript
14
14
  import { Mastra } from '@mastra/core';
@@ -19,100 +19,29 @@ export const mastra = new Mastra({
19
19
  configs: {
20
20
  default: {
21
21
  serviceName: 'my-app',
22
- exporters: [
23
- new MastraStorageExporter(), // Persists observability events to Mastra Storage
24
- new MastraPlatformExporter(), // Sends observability events to Mastra Platform
25
- ],
22
+ exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
26
23
  },
27
24
  },
28
25
  }),
29
26
  });
30
27
  ```
31
28
 
32
- A `SensitiveDataFilter` span output processor is auto-applied to every configured instance by default, redacting secrets (API keys, tokens, passwords, etc.) before they reach exporters. Set `sensitiveDataFilter: false` on the `Observability` config to opt out, or pass a `SensitiveDataFilterOptions` object to customize it.
33
-
34
- ## Features
35
-
36
- - **Auto-instrumentation** - Traces agent runs, LLM calls, tool executions, and workflows
37
- - **Pluggable Exporters** - Exporters for Studio, plus integrations for Arize, Braintrust, Langfuse, LangSmith, and OpenTelemetry
38
- - **Sampling Strategies** - Always, ratio-based, or custom sampling
39
- - **Span Processors** - Transform or filter span data before export
40
- - **OpenTelemetry Compatible** - Standard trace/span ID formats for integration
41
-
42
- ## Architecture
43
-
44
- ### ObservabilityBus
45
-
46
- Central event router that dispatches tracing, metric, and log events to registered exporters. All handler promises are tracked for reliable flush and shutdown — no events are silently dropped.
47
-
48
- Exporters register via `registerExporter()` and can optionally implement `onLogEvent` and `onMetricEvent` handlers alongside the existing `exportTracingEvent`.
49
-
50
- ### Auto-extracted metrics
51
-
52
- Metrics are automatically extracted from span lifecycle events by `AutoExtractedMetrics`:
53
-
54
- - `mastra_agent_duration_ms`
55
- - `mastra_tool_duration_ms`
56
- - `mastra_workflow_duration_ms`
57
- - `mastra_model_duration_ms`
58
- - `mastra_model_total_input_tokens` / `mastra_model_total_output_tokens`
59
- - `mastra_model_input_text_tokens` / `mastra_model_input_cache_read_tokens` / `mastra_model_input_cache_write_tokens` / `mastra_model_input_cache_write_5m_tokens` / `mastra_model_input_cache_write_1h_tokens` / `mastra_model_input_audio_tokens` / `mastra_model_input_image_tokens`
60
- - `mastra_model_output_text_tokens` / `mastra_model_output_reasoning_tokens` / `mastra_model_output_audio_tokens` / `mastra_model_output_image_tokens`
61
-
62
- For Anthropic models, the aggregate cache-write metric remains available while the 5-minute and 1-hour metrics preserve the provider's TTL-specific token counts and pricing.
63
-
64
- Auto-extracted metrics carry labels: `entity_type`, `entity_name`, `status`, plus `model` and `provider` on model generation spans.
65
-
66
- ### Structured logging
67
-
68
- `LoggerContextImpl` emits log events with automatic trace correlation (traceId, spanId), inherited tags, and entity metadata. Supports minimum log level filtering (debug/info/warn/error/fatal).
69
-
70
- ### Metrics context
71
-
72
- `MetricsContextImpl` provides counter, gauge, and histogram instruments. All labels pass through a `CardinalityFilter` that blocks high-cardinality keys (trace_id, user_id, etc.) to protect metric backends.
73
-
74
- ## Span Types
75
-
76
- - `WORKFLOW_RUN` - Workflow execution
77
- - `WORKFLOW_STEP` - Individual workflow step
78
- - `AGENT_RUN` - Agent processing
79
- - `MODEL_GENERATION` - LLM API calls
80
- - `TOOL_CALL` - Tool execution
81
- - `MCP_TOOL_CALL` - MCP tool execution
82
- - `PROCESSOR_RUN` - Processor execution
83
- - `GENERIC` - Custom operations
84
-
85
- ## Metrics Labels
29
+ ## Documentation
86
30
 
87
- ### Auto-extracted metric labels
31
+ `Observability` instruments agent runs, model generations, tool and MCP calls, processor execution, workflow runs, and workflow steps. Each configured observability instance has its own service name, exporters, sampling strategy, and span processors.
88
32
 
89
- | Label | Description | Cardinality |
90
- | ------------- | -------------------------------------------------------------------- | --------------------------- |
91
- | `entity_type` | What is being measured (e.g., `agent`, `tool`, `workflow_run`) | Small enum (~9 values) |
92
- | `entity_name` | Name of the entity (e.g., `researcher`, `search`) | Bounded by defined entities |
93
- | `model` | LLM model ID (only on model generation spans) | Bounded by LLM providers |
94
- | `provider` | LLM provider (only on model generation spans) | Bounded by LLM providers |
95
- | `status` | Outcome of the operation (`ok` or `error`), on `_ended` metrics only | 2 values |
33
+ Exporters receive tracing events through the central observability bus. `MastraStorageExporter` persists them to the configured Mastra storage so Studio can query them, while `MastraPlatformExporter` sends them to Mastra Platform. Additional packages provide exporters for services such as Arize, Braintrust, Langfuse, LangSmith, Sentry, and OpenTelemetry-compatible backends.
96
34
 
97
- ### User-emitted metric labels (via MetricsContext)
35
+ A `SensitiveDataFilter` output processor is enabled by default and redacts common secrets before spans reach exporters. Set `sensitiveDataFilter: false` to disable it, or provide filter options to customize its behavior. Sampling can retain every trace, use a ratio, or apply application-specific logic.
98
36
 
99
- User-emitted metrics inherit additional context labels from the active span:
37
+ The package automatically derives duration, status, model token, and cache token metrics from span lifecycle events. Structured logs inherit trace and span IDs, tags, and entity metadata, while metric labels pass through cardinality filtering to prevent user IDs, trace IDs, and other unbounded values from overwhelming metrics backends.
100
38
 
101
- | Label | Description | Cardinality |
102
- | -------------- | --------------------------------------------------------------------------- | --------------------------- |
103
- | `parent_type` | Entity type of the nearest parent | Same small enum |
104
- | `parent_name` | Name of the nearest parent entity | Bounded by defined entities |
105
- | `root_type` | Entity type of the outermost ancestor (only set when different from parent) | Same small enum |
106
- | `root_name` | Name of the outermost ancestor entity | Bounded by defined entities |
107
- | `service_name` | Service name from observability config | Single value per deployment |
39
+ - [Observability documentation](https://mastra.ai/docs/studio/observability)
108
40
 
109
- ### Common query patterns
41
+ ## Changelog
110
42
 
111
- - **Which agent is expensive?** → group by `entity_name` where `entity_type=agent`
112
- - **Why is this tool slow only sometimes?** → group by `parent_name`
113
- - **What's the total cost of this user-facing flow?** → group by `root_name`
114
- - **Which model is cheapest for this agent?** → group by `model` where `entity_name=X`
43
+ See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/observability/mastra/CHANGELOG.md) for version history and release notes.
115
44
 
116
- ## Documentation
45
+ ## Support
117
46
 
118
- For configuration options, exporters, sampling strategies, and more, see the [full documentation](https://mastra.ai/docs/v1/observability/overview).
47
+ We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/observability",
3
- "version": "1.17.5-alpha.0",
3
+ "version": "1.17.5-alpha.1",
4
4
  "description": "Core observability package for Mastra - includes tracing and scoring features",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -32,10 +32,10 @@
32
32
  "vitest": "4.1.10",
33
33
  "zod": "^4.4.3",
34
34
  "@internal/ai-sdk-v5": "0.0.76",
35
- "@internal/ai-sdk-v4": "0.0.76",
36
- "@internal/lint": "0.0.129",
37
35
  "@internal/types-builder": "0.0.104",
38
- "@mastra/core": "1.64.0-alpha.2"
36
+ "@internal/ai-sdk-v4": "0.0.76",
37
+ "@mastra/core": "1.64.0-alpha.7",
38
+ "@internal/lint": "0.0.129"
39
39
  },
40
40
  "peerDependencies": {
41
41
  "@mastra/core": ">=1.16.0-0 <2.0.0-0",