Add Usage Analytics Tracking

[izadoesdev]

Overview

Track API key usage for analytics, debugging, and insights into how keys are being used.

Motivation

Understanding key usage patterns helps with security monitoring, debugging, and planning.

Proposed API

// Track key usage
await keys.trackUsage(keyId, {
  endpoint: '/api/users',
  method: 'GET',
  ipAddress: '1.2.3.4',
  responseTime: 123,
  statusCode: 200
})

// Get usage stats
const stats = await keys.getUsageStats(keyId, {
  startDate: '2025-01-01',
  endDate: '2025-12-31'
})

Implementation Details

Storage Requirements

• Create usage events table or extend audit logs
• Store: keyId, endpoint, method, ip, timestamp, responseTime, statusCode
• Add indexes for efficient querying

Analytics Features

• Usage count per time period
• Most used endpoints
• Peak usage times
• Error rates
• Response time statistics

Acceptance Criteria

• Implement usage tracking
• Add aggregation queries for stats
• Support time-based filtering
• Add usage data to audit logs or separate table
• Add tests for analytics
• Document analytics features
• Consider performance impact

Priority

Medium - Insights and monitoring