docs/src/content/en/reference/client-js/observability.mdx
The Observability API provides methods to retrieve traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
Retrieve a specific trace by its ID, including all its spans and details:
const trace = await mastraClient.getTrace('trace-id-123')
Retrieve a paginated list of trace root spans with optional filtering:
const traces = await mastraClient.getTraces({
pagination: {
page: 1,
perPage: 20,
dateRange: {
start: new Date('2024-01-01'),
end: new Date('2024-01-31'),
},
},
filters: {
name: 'weather-agent', // Filter by trace name
spanType: 'agent', // Filter by span type
entityId: 'weather-agent-id', // Filter by entity ID
entityType: 'agent', // Filter by entity type
},
})
console.log(`Found ${traces.spans.length} root spans`)
console.log(`Total pages: ${traces.pagination.totalPages}`)
// To get the complete trace with all spans, use getTrace
const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId)
Score specific traces using registered scorers for evaluation:
const result = await mastraClient.score({
scorerName: 'answer-relevancy',
targets: [
{ traceId: 'trace-1', spanId: 'span-1' }, // Score specific span
{ traceId: 'trace-2' }, // Score specific span which defaults to the parent span
],
})
Retrieve scores for a specific span within a trace:
const scores = await mastraClient.listScoresBySpan({
traceId: 'trace-123',
spanId: 'span-456',
page: 1,
perPage: 20,
})