Add yearly request heatmap drilldown

Author: k0ngk0ng

README.md

@@ -93,6 +93,7 @@ All endpoints are mounted under `<APP_BASE_PATH>/api/v1`. Protected endpoints re
 | GET | `/status` | drain status (last pop, errors, totals) |
 | POST | `/sync` | trigger metadata refresh |
 | GET | `/usage/overview` | summary + hourly + daily + range-sized 15-minute health grid |
+| GET | `/usage/health` | year request matrix + optional selected-day 5-minute detail |
 | GET | `/usage/analysis` | aggregations by API / model / both |
 | GET | `/usage/events` | paginated raw events |
 | GET | `/usage/events/filters` | distinct models + sources |

internal/api/usage_handler.go

@@ -64,7 +64,7 @@ func usageHealthHandler(deps UsageDeps) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		out, err := deps.Service.Health(c.Request.Context(), f, c.Query("month"), time.Now().In(time.Local))
+		out, err := deps.Service.Health(c.Request.Context(), f, c.Query("year"), c.Query("day"), time.Now().In(time.Local))
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return

internal/storage/sqlite/usage.go

@@ -594,35 +594,70 @@ func (s *Store) healthGrid(ctx context.Context, f storage.UsageFilter, now time.
 	return s.healthGridRange(ctx, healthFilter)
 }
 
-// BuildUsageHealthGrid returns an uncapped day/hour matrix for an explicit
-// range. The request matrix uses this for natural months, including 31-day
-// months, while the overview summary keeps its compact rolling-window grid.
-func (s *Store) BuildUsageHealthGrid(ctx context.Context, f storage.UsageFilter, start, end time.Time) ([][]storage.HealthCell, error) {
+func (s *Store) BuildUsageHealthDays(ctx context.Context, f storage.UsageFilter, start, end time.Time) ([]storage.UsageHealthDay, error) {
 	healthFilter := f
 	healthFilter.Start = start
 	healthFilter.End = end
-	return s.healthGridRange(ctx, healthFilter)
+	type row struct {
+		Date   string
+		Total  int64
+		Failed int64
+	}
+	var rows []row
+	if err := s.applyFilter(ctx, healthFilter).
+		Select(`strftime('%Y-%m-%d', timestamp, 'localtime') AS date,
+			COUNT(*) AS total,
+			SUM(CASE WHEN failed = 1 THEN 1 ELSE 0 END) AS failed`).
+		Group("date").
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	byDate := make(map[string]storage.UsageHealthDay, len(rows))
+	for _, r := range rows {
+		t, err := time.ParseInLocation("2006-01-02", r.Date, time.Local)
+		if err != nil {
+			continue
+		}
+		byDate[r.Date] = storage.UsageHealthDay{Date: r.Date, Bucket: t, Total: r.Total, Failed: r.Failed}
+	}
+	days := make([]storage.UsageHealthDay, 0, int(end.Sub(start).Hours()/24))
+	for day := start; day.Before(end); day = day.AddDate(0, 0, 1) {
+		key := day.Format("2006-01-02")
+		if cell, ok := byDate[key]; ok {
+			days = append(days, cell)
+		} else {
+			days = append(days, storage.UsageHealthDay{Date: key, Bucket: day})
+		}
+	}
+	return days, nil
 }
 
-func (s *Store) ListUsageEventMonths(ctx context.Context, f storage.UsageFilter) ([]storage.UsageHealthMonth, error) {
+func (s *Store) BuildUsageHealthDetail(ctx context.Context, f storage.UsageFilter, day time.Time) ([][]storage.HealthCell, error) {
+	healthFilter := f
+	healthFilter.Start = day
+	healthFilter.End = day.AddDate(0, 0, 1)
+	return s.healthDetailRange(ctx, healthFilter)
+}
+
+func (s *Store) ListUsageEventYears(ctx context.Context, f storage.UsageFilter) ([]storage.UsageHealthYear, error) {
 	type row struct {
-		Month string
+		Year  int
 		Total int64
 	}
 	var rows []row
 	if err := s.applyFilter(ctx, f).
-		Select(`strftime('%Y-%m', timestamp, 'localtime') AS month, COUNT(*) AS total`).
-		Group("month").
-		Order("month DESC").
+		Select(`CAST(strftime('%Y', timestamp, 'localtime') AS INTEGER) AS year, COUNT(*) AS total`).
+		Group("year").
+		Order("year DESC").
 		Scan(&rows).Error; err != nil {
 		return nil, err
 	}
-	out := make([]storage.UsageHealthMonth, 0, len(rows))
+	out := make([]storage.UsageHealthYear, 0, len(rows))
 	for _, r := range rows {
-		if r.Month == "" {
+		if r.Year <= 0 {
 			continue
 		}
-		out = append(out, storage.UsageHealthMonth{Month: r.Month, Total: r.Total})
+		out = append(out, storage.UsageHealthYear{Year: r.Year, Total: r.Total})
 	}
 	return out, nil
 }
@@ -672,6 +707,46 @@ func (s *Store) healthGridRange(ctx context.Context, healthFilter storage.UsageF
 	return grid, nil
 }
 
+func (s *Store) healthDetailRange(ctx context.Context, healthFilter storage.UsageFilter) ([][]storage.HealthCell, error) {
+	type row struct {
+		Bucket string
+		Total  int64
+		Failed int64
+	}
+	var rows []row
+	if err := s.applyFilter(ctx, healthFilter).
+		Select(`strftime('%Y-%m-%d %H:%M', datetime((strftime('%s', timestamp) / 300) * 300, 'unixepoch')) AS bucket,
+			COUNT(*) AS total,
+			SUM(CASE WHEN failed = 1 THEN 1 ELSE 0 END) AS failed`).
+		Group("bucket").
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	bucketMap := make(map[time.Time]storage.HealthCell, len(rows))
+	for _, r := range rows {
+		t, err := time.Parse("2006-01-02 15:04", r.Bucket)
+		if err != nil {
+			continue
+		}
+		bucketMap[t.UTC()] = storage.HealthCell{Bucket: t.UTC(), Total: r.Total, Failed: r.Failed}
+	}
+
+	grid := make([][]storage.HealthCell, 6)
+	for row := 0; row < 6; row++ {
+		grid[row] = make([]storage.HealthCell, 48)
+		for col := 0; col < 48; col++ {
+			offset := time.Duration(row*48+col) * 5 * time.Minute
+			b := healthFilter.Start.Add(offset).UTC()
+			if cell, ok := bucketMap[b]; ok {
+				grid[row][col] = cell
+			} else {
+				grid[row][col] = storage.HealthCell{Bucket: b}
+			}
+		}
+	}
+	return grid, nil
+}
+
 func foldBuckets(rows []bucketRow, start, end time.Time, step time.Duration, prices map[string]storage.ModelPriceSetting) []storage.UsageBucket {
 	merged := make(map[time.Time]*storage.UsageBucket)
 	for _, r := range rows {

internal/storage/store.go

@@ -26,8 +26,9 @@ type Store interface {
 
 	// Aggregations
 	BuildUsageOverview(ctx context.Context, f UsageFilter, prices map[string]ModelPriceSetting) (*UsageOverview, error)
-	BuildUsageHealthGrid(ctx context.Context, f UsageFilter, start, end time.Time) ([][]HealthCell, error)
-	ListUsageEventMonths(ctx context.Context, f UsageFilter) ([]UsageHealthMonth, error)
+	BuildUsageHealthDays(ctx context.Context, f UsageFilter, start, end time.Time) ([]UsageHealthDay, error)
+	BuildUsageHealthDetail(ctx context.Context, f UsageFilter, day time.Time) ([][]HealthCell, error)
+	ListUsageEventYears(ctx context.Context, f UsageFilter) ([]UsageHealthYear, error)
 	ListUsageEvents(ctx context.Context, f UsageFilter, p Page, prices map[string]ModelPriceSetting) (*UsageEventsPage, error)
 	ListUsageEventFilterOptions(ctx context.Context, f UsageFilter) (*UsageEventFilterOptions, error)
 	ListUsageEventAPIKeys(ctx context.Context, f UsageFilter) ([]string, error)

internal/storage/types.go

@@ -199,19 +199,30 @@ type UsageOverview struct {
 	GeneratedAt  time.Time      `json:"generated_at"`
 }
 
-// UsageHealthMonth is one month option available for the request matrix.
-type UsageHealthMonth struct {
-	Month string `json:"month"`
-	Total int64  `json:"total"`
+// UsageHealthYear is one year option available for the request matrix.
+type UsageHealthYear struct {
+	Year  int   `json:"year"`
+	Total int64 `json:"total"`
 }
 
-// UsageHealthMatrix is the month-sized request matrix payload.
+// UsageHealthDay is one day cell in the year-sized request matrix.
+type UsageHealthDay struct {
+	Date   string    `json:"date"`
+	Bucket time.Time `json:"bucket"`
+	Total  int64     `json:"total"`
+	Failed int64     `json:"failed"`
+}
+
+// UsageHealthMatrix is the year-sized request matrix payload plus optional
+// selected-day 5-minute detail rows.
 type UsageHealthMatrix struct {
-	Month  string             `json:"month"`
-	Start  time.Time          `json:"start"`
-	End    time.Time          `json:"end"`
-	Grid   [][]HealthCell     `json:"grid"`
-	Months []UsageHealthMonth `json:"months"`
+	Year        int               `json:"year"`
+	Start       time.Time         `json:"start"`
+	End         time.Time         `json:"end"`
+	Days        []UsageHealthDay  `json:"days"`
+	Years       []UsageHealthYear `json:"years"`
+	SelectedDay string            `json:"selected_day,omitempty"`
+	Detail      [][]HealthCell    `json:"detail,omitempty"`
 }
 
 // UsageSummary is the aggregated totals shown in the overview header.

internal/usage/service.go

@@ -134,37 +134,42 @@ func (s *Service) Overview(ctx context.Context, f Filter) (*storage.UsageOvervie
 	return s.store.BuildUsageOverview(ctx, f.toStorage(), prices)
 }
 
-// Health returns the month-sized request matrix and the available month list.
-func (s *Service) Health(ctx context.Context, f Filter, monthKey string, now time.Time) (*storage.UsageHealthMatrix, error) {
-	start, err := parseMonth(monthKey, now)
+// Health returns the year-sized request matrix and optional selected-day detail.
+func (s *Service) Health(ctx context.Context, f Filter, yearKey, dayKey string, now time.Time) (*storage.UsageHealthMatrix, error) {
+	year, err := parseYear(yearKey, now)
 	if err != nil {
 		return nil, err
 	}
-	end := start.AddDate(0, 1, 0)
+	start := time.Date(year, time.January, 1, 0, 0, 0, 0, time.Local)
+	end := start.AddDate(1, 0, 0)
 	sf := f.toStorage()
 	sf.Range = ""
 	sf.Start = time.Time{}
 	sf.End = time.Time{}
 
-	months, err := s.store.ListUsageEventMonths(ctx, sf)
+	years, err := s.store.ListUsageEventYears(ctx, sf)
 	if err != nil {
 		return nil, err
 	}
-	month := start.Format("2006-01")
 	localNow := now.In(time.Local)
-	currentMonth := time.Date(localNow.Year(), localNow.Month(), 1, 0, 0, 0, 0, time.Local).Format("2006-01")
-	months = ensureMonthOption(ensureMonthOption(months, month), currentMonth)
+	years = ensureYearOption(ensureYearOption(years, year), localNow.Year())
 
-	grid, err := s.store.BuildUsageHealthGrid(ctx, sf, start, end)
+	days, err := s.store.BuildUsageHealthDays(ctx, sf, start, end)
+	if err != nil {
+		return nil, err
+	}
+	selectedDay, detail, err := s.healthDetail(ctx, sf, start, end, dayKey)
 	if err != nil {
 		return nil, err
 	}
 	return &storage.UsageHealthMatrix{
-		Month:  month,
-		Start:  start,
-		End:    end,
-		Grid:   grid,
-		Months: months,
+		Year:        year,
+		Start:       start,
+		End:         end,
+		Days:        days,
+		Years:       years,
+		SelectedDay: selectedDay,
+		Detail:      detail,
 	}, nil
 }
 
@@ -358,27 +363,54 @@ func parseTime(in string) (time.Time, error) {
 	return time.Time{}, fmt.Errorf("unrecognized time %q", in)
 }
 
-func parseMonth(in string, now time.Time) (time.Time, error) {
+func (s *Service) healthDetail(ctx context.Context, f storage.UsageFilter, yearStart, yearEnd time.Time, dayKey string) (string, [][]storage.HealthCell, error) {
+	dayKey = strings.TrimSpace(dayKey)
+	if dayKey == "" {
+		return "", nil, nil
+	}
+	day, err := parseDay(dayKey)
+	if err != nil {
+		return "", nil, err
+	}
+	if day.Before(yearStart) || !day.Before(yearEnd) {
+		return "", nil, fmt.Errorf("day %q is outside selected year", dayKey)
+	}
+	detail, err := s.store.BuildUsageHealthDetail(ctx, f, day)
+	if err != nil {
+		return "", nil, err
+	}
+	return day.Format("2006-01-02"), detail, nil
+}
+
+func parseYear(in string, now time.Time) (int, error) {
 	in = strings.TrimSpace(in)
 	if in == "" {
-		local := now.In(time.Local)
-		return time.Date(local.Year(), local.Month(), 1, 0, 0, 0, 0, time.Local), nil
+		return now.In(time.Local).Year(), nil
+	}
+	t, err := time.ParseInLocation("2006", in, time.Local)
+	if err != nil {
+		return 0, fmt.Errorf("parse year: %w", err)
 	}
-	t, err := time.ParseInLocation("2006-01", in, time.Local)
+	return t.Year(), nil
+}
+
+func parseDay(in string) (time.Time, error) {
+	in = strings.TrimSpace(in)
+	t, err := time.ParseInLocation("2006-01-02", in, time.Local)
 	if err != nil {
-		return time.Time{}, fmt.Errorf("parse month: %w", err)
+		return time.Time{}, fmt.Errorf("parse day: %w", err)
 	}
-	return time.Date(t.Year(), t.Month(), 1, 0, 0, 0, 0, time.Local), nil
+	return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, time.Local), nil
 }
 
-func ensureMonthOption(months []storage.UsageHealthMonth, month string) []storage.UsageHealthMonth {
-	for _, m := range months {
-		if m.Month == month {
-			return months
+func ensureYearOption(years []storage.UsageHealthYear, year int) []storage.UsageHealthYear {
+	for _, y := range years {
+		if y.Year == year {
+			return years
 		}
 	}
-	out := append([]storage.UsageHealthMonth{{Month: month}}, months...)
-	sort.SliceStable(out, func(i, j int) bool { return out[i].Month > out[j].Month })
+	out := append([]storage.UsageHealthYear{{Year: year}}, years...)
+	sort.SliceStable(out, func(i, j int) bool { return out[i].Year > out[j].Year })
 	return out
 }
 

web/src/api/client.ts

@@ -138,9 +138,9 @@ export const api = {
   async overview(filter: Filter): Promise<UsageOverview> {
     return request<UsageOverview>("/usage/overview" + buildQuery(filter));
   },
-  async health(filter: Filter, month?: string): Promise<UsageHealthMatrix> {
+  async health(filter: Filter, year?: string, day?: string): Promise<UsageHealthMatrix> {
     return request<UsageHealthMatrix>(
-      "/usage/health" + buildFacetQuery(filter, { month }),
+      "/usage/health" + buildFacetQuery(filter, { year, day }),
     );
   },
   async analysis(filter: Filter): Promise<UsageAnalysis> {

web/src/api/types.ts

@@ -74,17 +74,26 @@ export interface UsageOverview {
   generated_at: string;
 }
 
-export interface UsageHealthMonth {
-  month: string;
+export interface UsageHealthYear {
+  year: number;
   total: number;
 }
 
+export interface UsageHealthDay {
+  date: string;
+  bucket: string;
+  total: number;
+  failed: number;
+}
+
 export interface UsageHealthMatrix {
-  month: string;
+  year: number;
   start: string;
   end: string;
-  grid: HealthCell[][];
-  months: UsageHealthMonth[];
+  days: UsageHealthDay[];
+  years: UsageHealthYear[];
+  selected_day?: string;
+  detail?: HealthCell[][];
 }
 
 export interface UsageEventRecord {