get-trace-stats
Retrieve trace statistics by specifying project ID, name, date range, or workspace for efficient analysis and monitoring on the Opik platform.
Instructions
Get statistics for traces
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | No | End date in ISO format (YYYY-MM-DD) | |
| projectId | No | Project ID to filter traces | |
| projectName | No | Project name to filter traces | |
| startDate | No | Start date in ISO format (YYYY-MM-DD) | |
| workspaceName | No | Workspace name to use instead of the default |
Implementation Reference
- src/tools/trace.ts:193-262 (handler)The main handler function for 'get-trace-stats' tool. Constructs API URL with project filtering, date ranges, fetches stats from /v1/private/traces/stats, handles no-project case by fetching first project, formats and returns response as content array.
async (args: any) => { const { projectId, projectName, startDate, endDate, workspaceName } = args; let url = `/v1/private/traces/stats`; // Build query parameters const queryParams = []; // Add project filtering - API requires either project_id or project_name if (projectId) { queryParams.push(`project_id=${projectId}`); } else if (projectName) { queryParams.push(`project_name=${encodeURIComponent(projectName)}`); } else { // If no project specified, we need to find one for the API to work const projectsResponse = await makeApiRequest<ProjectResponse>( `/v1/private/projects?page=1&size=1`, {}, workspaceName ); if ( projectsResponse.data && projectsResponse.data.content && projectsResponse.data.content.length > 0 ) { const firstProject = projectsResponse.data.content[0]; queryParams.push(`project_id=${firstProject.id}`); logToFile( `No project specified, using first available: ${firstProject.name} (${firstProject.id})` ); } else { return { content: [ { type: 'text', text: 'Error: No project ID or name provided, and no projects found', }, ], }; } } if (startDate) queryParams.push(`start_date=${startDate}`); if (endDate) queryParams.push(`end_date=${endDate}`); if (queryParams.length > 0) { url += `?${queryParams.join('&')}`; } const response = await makeApiRequest<TraceStatsResponse>(url, {}, workspaceName); if (!response.data) { return { content: [{ type: 'text', text: response.error || 'Failed to fetch trace statistics' }], }; } return { content: [ { type: 'text', text: `Trace Statistics:`, }, { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], }; } - src/tools/trace.ts:169-192 (schema)Input parameters schema defined with Zod validators for projectId, projectName, startDate, endDate, workspaceName.
{ projectId: z .string() .optional() .describe( 'Project ID to filter traces. If not provided, will use the first available project' ), projectName: z .string() .optional() .describe('Project name to filter traces (alternative to projectId)'), startDate: z .string() .optional() .describe('Start date in ISO format (YYYY-MM-DD). Example: "2024-01-01"'), endDate: z .string() .optional() .describe('End date in ISO format (YYYY-MM-DD). Example: "2024-01-31"'), workspaceName: z .string() .optional() .describe('Workspace name to use instead of the default workspace'), }, - src/tools/trace.ts:166-263 (registration)Registers the 'get-trace-stats' tool on the MCP server with name, description, input schema, and handler function.
server.tool( 'get-trace-stats', 'Get aggregated statistics for traces including counts, costs, token usage, and performance metrics over time', { projectId: z .string() .optional() .describe( 'Project ID to filter traces. If not provided, will use the first available project' ), projectName: z .string() .optional() .describe('Project name to filter traces (alternative to projectId)'), startDate: z .string() .optional() .describe('Start date in ISO format (YYYY-MM-DD). Example: "2024-01-01"'), endDate: z .string() .optional() .describe('End date in ISO format (YYYY-MM-DD). Example: "2024-01-31"'), workspaceName: z .string() .optional() .describe('Workspace name to use instead of the default workspace'), }, async (args: any) => { const { projectId, projectName, startDate, endDate, workspaceName } = args; let url = `/v1/private/traces/stats`; // Build query parameters const queryParams = []; // Add project filtering - API requires either project_id or project_name if (projectId) { queryParams.push(`project_id=${projectId}`); } else if (projectName) { queryParams.push(`project_name=${encodeURIComponent(projectName)}`); } else { // If no project specified, we need to find one for the API to work const projectsResponse = await makeApiRequest<ProjectResponse>( `/v1/private/projects?page=1&size=1`, {}, workspaceName ); if ( projectsResponse.data && projectsResponse.data.content && projectsResponse.data.content.length > 0 ) { const firstProject = projectsResponse.data.content[0]; queryParams.push(`project_id=${firstProject.id}`); logToFile( `No project specified, using first available: ${firstProject.name} (${firstProject.id})` ); } else { return { content: [ { type: 'text', text: 'Error: No project ID or name provided, and no projects found', }, ], }; } } if (startDate) queryParams.push(`start_date=${startDate}`); if (endDate) queryParams.push(`end_date=${endDate}`); if (queryParams.length > 0) { url += `?${queryParams.join('&')}`; } const response = await makeApiRequest<TraceStatsResponse>(url, {}, workspaceName); if (!response.data) { return { content: [{ type: 'text', text: response.error || 'Failed to fetch trace statistics' }], }; } return { content: [ { type: 'text', text: `Trace Statistics:`, }, { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], }; } ); - src/index.ts:91-94 (registration)Conditional registration of trace tools (including get-trace-stats) by calling loadTraceTools when 'traces' toolset is enabled.
if (config.enabledToolsets.includes('traces')) { server = loadTraceTools(server); logToFile('Loaded traces toolset'); }