compare_usage_periods
Analyze and contrast Claude usage metrics across two distinct timeframes to identify trends and monitor changes in token consumption and tool patterns.
Instructions
Compare usage between different time periods
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period1_days | No | Days back for first period (default: 7) | |
| period2_days | No | Days back for second period (default: 14) |
Implementation Reference
- src/index.ts:357-374 (handler)The main execution handler for the 'compare_usage_periods' tool. It extracts period parameters from input arguments, fetches usage trends for both periods using TelemetryService, and returns a formatted comparison text response.case 'compare_usage_periods': { const period1Days = typeof args?.period1_days === 'number' ? args.period1_days : 7; const period2Days = typeof args?.period2_days === 'number' ? args.period2_days : 14; const [trends1, trends2] = await Promise.all([ this.telemetryService.getUsageTrends(period1Days), this.telemetryService.getUsageTrends(period2Days) ]); return { content: [ { type: 'text', text: this.formatPeriodComparison(trends1, trends2, period1Days, period2Days), }, ], }; }
- src/index.ts:166-180 (schema)Input schema definition for the 'compare_usage_periods' tool, specifying optional parameters for the two comparison periods with defaults.inputSchema: { type: 'object', properties: { period1_days: { type: 'number', description: 'Days back for first period (default: 7)', default: 7, }, period2_days: { type: 'number', description: 'Days back for second period (default: 14)', default: 14, }, }, },
- src/index.ts:163-181 (registration)Tool registration entry in the ListTools response, including name, description, and input schema.{ name: 'compare_usage_periods', description: 'Compare usage between different time periods', inputSchema: { type: 'object', properties: { period1_days: { type: 'number', description: 'Days back for first period (default: 7)', default: 7, }, period2_days: { type: 'number', description: 'Days back for second period (default: 14)', default: 14, }, }, }, },
- src/index.ts:492-503 (helper)Helper method to format the comparison results between two usage periods, calculating totals, change, and percentage difference.private formatPeriodComparison(trends1: UsageTrend[], trends2: UsageTrend[], period1: number, period2: number): string { const total1 = trends1.reduce((sum, t) => sum + t.tokens, 0); const total2 = trends2.reduce((sum, t) => sum + t.tokens, 0); const change = total1 - total2; const changePercent = total2 > 0 ? ((change / total2) * 100) : 0; return `## Usage Comparison\n\n` + `**Last ${period1} days**: ${total1.toLocaleString()} tokens\n` + `**Previous ${period2} days**: ${total2.toLocaleString()} tokens\n` + `**Change**: ${change > 0 ? '+' : ''}${change.toLocaleString()} tokens (${changePercent > 0 ? '+' : ''}${changePercent.toFixed(1)}%)`; }
- src/telemetry-service.ts:103-129 (helper)Supporting method in TelemetryService that queries Prometheus for usage trends over a specified number of days, used by the tool handler for both periods.async getUsageTrends(daysBack: number = 7): Promise<UsageTrend[]> { const endTime = new Date(); const startTime = new Date(endTime.getTime() - (daysBack * 24 * 60 * 60 * 1000)); const [tokensResult, costResult, sessionsResult] = await Promise.all([ this.prometheus.queryRange('claude_code_token_usage_tokens_total', startTime, endTime, '1h'), this.prometheus.queryRange('claude_code_cost_usage_USD_total', startTime, endTime, '1h'), this.prometheus.queryRange('claude_code_session_count_total', startTime, endTime, '1h') ]); const tokensSeries = this.prometheus.getTimeSeries(tokensResult); const costSeries = this.prometheus.getTimeSeries(costResult); const sessionsSeries = this.prometheus.getTimeSeries(sessionsResult); // Combine the series data const trends: UsageTrend[] = []; for (let i = 0; i < tokensSeries.length; i++) { trends.push({ timestamp: tokensSeries[i].timestamp.toISOString(), tokens: tokensSeries[i].value, cost: costSeries[i]?.value || 0, sessions: sessionsSeries[i]?.value || 0 }); } return trends; }