📊 Analytics: What We Track and Why

Purpose

Analytics provides summaries of system activity over configurable time ranges or per-day. For operations teams, it answers:

• How many camera frames did we process?
• What detections did the AI flag?
• How many events did operators review?
• How many events have annotations, and in which categories?

---

API Endpoints

UTC Datetime Range

Endpoint: GET /api/analytics

Parameters:

• ts_utc_start / ts_utc_end – UTC datetime range (optional; defaults to a sliding window defined by REDIS_TS_UTC_WINDOW_SECONDS)
• camera_id – Filter to a specific camera (optional)

Daily Summary

Endpoint: GET /api/analytics/day

Parameters:

• date – Date in YYYY-MM-DD format (optional; defaults to today UTC)
• camera_id – Filter to a specific camera (optional)

Both endpoints return the same Analytics response model.

---

What We Count

Metric	Field	Definition	Business Purpose
Total Events	total_events	Number of camera frames in the period	System load & uptime. More events = more monitoring coverage.
Active Cameras	active_cameras / active_camera_ids	Unique cameras that sent events	System health & coverage. Missing cameras indicate downtime.
AI Detections	counts_per_category	How many times AI flagged each detection type (fire, smoke, structure, etc.)	Detection frequency patterns. Helps identify problem areas.
Reviewed Events	reviewed_total_events	Number of events operators manually reviewed	Operator workload & review effort. Shows what operators prioritize.
Reviewed by Category	reviewed_counts_per_category	Among reviewed events, how many include at least one annotation of each category	Validates AI accuracy. Shows operator agreement with AI detections.
Annotated Events	annotated_total_events	Total number of events that have annotations	Annotation coverage — how much labeled data exists.
Annotated by Category	annotated_counts_per_category	Total annotation count per category across all events	Category-level annotation volume for training data insight.

---

Reading a Daily Report

Example API Response:

GET /api/analytics/day?date=2026-01-16

{
  "ts_utc_start": "2026-01-16T00:00:00+00:00",
  "ts_utc_end": "2026-01-16T23:59:59.999999+00:00",
  "total_events": 5000,
  "active_cameras": 4,
  "active_camera_ids": ["cam-001", "cam-002", "cam-003", "cam-005"],

  "counts_per_category": {
    "fire": 250,
    "smoke": 180,
    "structure": 40
  },

  "reviewed_total_events": 42,
  "reviewed_counts_per_category": {
    "fire": 24,
    "smoke": 14,
    "structure": 2
  },

  "annotated_total_events": 38,
  "annotated_counts_per_category": {
    "fire": 26,
    "smoke": 15,
    "structure": 3
  }
}

Interpretation:

• 5,000 frames processed across 4 cameras
• AI flagged potential detections 470 times total (250+180+40)
• Operators reviewed 42 events (0.8%)
  • 24 reviewed events contain fire annotations (9.6% of 250 AI fire flags)
  • 14 reviewed events contain smoke annotations (7.8% of 180 AI smoke flags)
  • 2 reviewed events contain structure annotations (5% of 40 AI structure flags)
• 38 events total have annotations (44 annotations across all categories)

What it means:

• System is active and monitoring well (4 cameras, 5k frames)
• AI flags detections regularly but operators confirm only a fraction
• Either: (a) AI has false positives, or (b) operators use selective review

---

Per-Camera Analytics

Example:

GET /api/analytics/day?date=2026-01-16&camera_id=cam-001

{
  "ts_utc_start": "2026-01-16T00:00:00+00:00",
  "ts_utc_end": "2026-01-16T23:59:59.999999+00:00",
  "total_events": 500,
  "active_cameras": 1,
  "active_camera_ids": ["cam-001"],

  "counts_per_category": {
    "fire": 25,
    "smoke": 18,
    "structure": 5
  },

  "reviewed_total_events": 4,
  "reviewed_counts_per_category": {
    "fire": 2,
    "smoke": 1,
    "structure": 0
  },

  "annotated_total_events": 3,
  "annotated_counts_per_category": {
    "fire": 2,
    "smoke": 1,
    "structure": 0
  }
}

Use Cases:

• Monitor performance of individual cameras
• Identify cameras with unusually high detection frequency
• Check if specific cameras are under-reviewed

---

Updates Don't Double-Count

When an operator changes an event (e.g., adds or removes an annotation):

Scenario: Operator initially marks event as "no detections", later changes to "has fire"

Before: Fire count = 0 After: Fire count = 1 Applied Change: +1 to fire count (not recounting everything)

This ensures edits update analytics accurately without inflating counts.

---

Key Principles

Principle	Meaning
Accuracy	Each event counted exactly once per day. Updates apply only the difference.
Consistency	Global + per-camera counts always match (same increments applied to both).
Isolation	One camera's data doesn't affect another. Easy to diagnose problems.
Atomic	All counts update together. No partial states visible.

---

Summary

Analytics provides:

1. System health – Total events, active cameras
2. Detection patterns – What AI detects and how often (counts_per_category)
3. Operator activity – Review volume and confirmation rates (reviewed_*)
4. Annotation coverage – Total annotations and per-category breakdown (annotated_*)

Use it to:

• Monitor system activity
• Validate AI performance
• Understand operator workload
• Identify problem cameras