Traces provide a hierarchical view of your agent's execution, showing the sequence of LLM calls, tool invocations, and state transitions.
```typescript theme={null}
// Add tracing to your Mastra agents
export const agent = new Agent({
name: 'Research Assistant',
instructions: 'You are a helpful research assistant.',
model: {
id: 'openai/@YOUR_PROVIDER_SLUG@gpt-4o',
url: 'https://api.portkey.ai/v1',
apiKey: process.env.PORTKEY_API_KEY,
headers: {
'x-portkey-trace-id': 'unique_execution_trace_id', // Add unique trace ID
'x-portkey-metadata': JSON.stringify({
agent_type: 'research_agent'
})
}
}
});
```
Portkey logs every interaction with LLMs, including:
* Complete request and response payloads
* Latency and token usage metrics
* Cost calculations
* Tool calls and function executions
All logs can be filtered by metadata, trace IDs, models, and more, making it easy to debug specific agent runs.
Portkey provides built-in dashboards that help you:
* Track cost and token usage across all agent runs
* Analyze performance metrics like latency and success rates
* Identify bottlenecks in your agent workflows
* Compare different agent configurations and LLMs
You can filter and segment all metrics by custom metadata to analyze specific agent types, user groups, or use cases.
Add custom metadata to your Mastra agent calls to enable powerful filtering and segmentation:
```typescript theme={null}
export const agent = new Agent({
name: 'Assistant',
instructions: 'You are a helpful assistant.',
model: {
id: 'openai/@YOUR_PROVIDER_SLUG@gpt-4o',
url: 'https://api.portkey.ai/v1',
apiKey: process.env.PORTKEY_API_KEY,
headers: {
'x-portkey-metadata': JSON.stringify({
agent_type: 'research_agent',
environment: 'production',
_user: 'user_123', // Special _user field for user analytics
team: 'engineering'
})
}
}
});
```
This metadata can be used to filter logs, traces, and metrics on the Portkey dashboard, allowing you to analyze specific agent runs, users, or environments.
This enables:
* Per-user cost tracking and budgeting
* Personalized user analytics
* Team or organization-level metrics
* Environment-specific monitoring (staging vs. production)
