tracksolid_timescale_grafana_prod/260410_baseline_report.md

# Tracksolid Fleet — Baseline Status Report
**Generated:** 2026-04-10 (post-migration 04 + 05, ~03:00 EAT)  
**Database:** tracksolid_db on TimescaleDB  
**Report scope:** All tables, all 63 registered devices, live data as of query time

---

## 1. Migration Status

All four migrations applied and recorded in `tracksolid.schema_migrations`:

| Migration File | Applied At (UTC) |
|---|---|
| `02_tracksolid_full_schema_rev.sql` | 2026-04-10 23:45 |
| `03_webhook_schema_migration.sql` | 2026-04-10 23:45 |
| `04_bug_fix_migration.sql` | 2026-04-10 23:45 |
| `05_enhancement_migration.sql` | 2026-04-10 23:45 |

Schema is fully current. All 13 critical tables verified present.

---

## 2. Table Row Counts

| Table | Row Count | Notes |
|---|---|---|
| `tracksolid.devices` | **63** | Full fleet registry |
| `tracksolid.live_positions` | **19** | Devices with a known current position |
| `tracksolid.position_history` | **132** | All historical GPS fixes |
| `tracksolid.alarms` | **2** | Vibration alerts recorded overnight |
| `tracksolid.trips` | **0** | Fleet parked overnight — expected |
| `tracksolid.parking_events` | **0** | POLL-02 fix deployed; will populate when vehicles move |
| `tracksolid.obd_readings` | **0** | Awaiting OBD webhook registration |
| `tracksolid.device_events` | **0** | Awaiting `/pushevent` webhook registration |
| `tracksolid.fuel_readings` | **0** | Awaiting `/pushoil` webhook registration |
| `tracksolid.temperature_readings` | **0** | Awaiting `/pushtem` webhook registration |
| `tracksolid.lbs_readings` | **0** | Awaiting `/pushlbs` webhook registration |
| `tracksolid.geofences` | **0** | Not yet configured |
| `tracksolid.api_token_cache` | Active | Auth token caching operational |
| `tracksolid.ingestion_log` | Active | Polling audit trail present |

---

## 3. Fleet Composition

**Total registered devices: 63**

| Device Model | Count | Typical Use |
|---|---|---|
| AT4 | 23 | Asset/cargo tracker — hardwired |
| JC400P | 23 | Camera-capable tracker — larger vehicles |
| X3 | 10 | Compact vehicle tracker |
| GT06E | 7 | Entry-level OBD port tracker |
| **Total** | **63** | |

---

## 4. Device Registry — Notable Devices

All 63 devices have model and IMEI populated. As of this report, **vehicle_name, vehicle_number, and driver_name are blank for all 63 devices** — this is the primary data quality gap blocking driver-level reporting.

| Platform Device Name | Model | Odometer (km) | Notes |
|---|---|---|---|
| FRED KMGW 538W HULETI | — | — | Most active overnight; 2 alarms |
| X3-63282 | X3 | — | Last seen Uganda — **anomalous location** |
| KDK 829A GP | — | 238,643 | **High mileage — service flag** |
| Belta KCU-647D | — | ~234,000 | **High mileage — service flag** |
| KMGR 409U | — | — | 1 fix in last 24h — low activity |

---

## 5. Live Position Coverage

**19 of 63 devices (30%)** have a position in `live_positions`.  
**44 devices have no position** — offline, SIM issue, or never activated.

### Freshness Breakdown

| Freshness Band | Device Count |
|---|---|
| < 1 hour old | ~4 |
| 1–6 hours old | ~8 |
| 6–24 hours old | ~7 |
| **Total with position** | **19** |

### Geographic Clusters

All 19 devices with positions fall into two clusters:

| Cluster | Approximate Area | Devices |
|---|---|---|
| Primary | Nairobi metro (-1.2° to -1.4°N, 36.7° to 37.0°E) | ~17 |
| Secondary | Thika / peri-urban north of Nairobi | ~1 |
| **Outlier** | **Kampala, Uganda (~0.3°N, 32.5°E)** | **1 (X3-63282)** |

---

## 6. Position History Analysis

**Total fixes in `position_history`: 132**

### By Ingestion Source

| Source | Fixes | Description |
|---|---|---|
| `poll` | 119 | 60-second fleet-wide sweep |
| `track_list` | 13 | High-res per-device trail via `jimi.device.track.list` (POLL-01) |
| **Total** | **132** | |

The `track_list` source is new as of this deployment. 13 fixes from 15 poll cycles (30-min schedule) is low but expected overnight with few active devices; volume will grow with daytime operations.

### Per-Device Fix Count — Last 24 Hours

| Device | Fixes | Notes |
|---|---|---|
| FRED KMGW 538W HULETI | 38 | Parked/idling overnight; most data-rich |
| X3-63282 | 28 | Active — location in Uganda |
| KDK 829A GP | 15 | Moderate activity |
| KMGR 409U | 1 | Near-silent — check device health |
| All others | 0 | No fixes recorded in last 24h |

Only **4 of 63 devices** generated `position_history` records in the last 24 hours.

---

## 7. Alarm Summary

**Total alarms: 2** — both from overnight, both on the same device.

| # | Device | Alarm Type | Type ID | Time (EAT) | Location |
|---|---|---|---|---|---|
| 1 | FRED KMGW 538W HULETI | Vibration Alert | 3 | 2026-04-10 00:57 | Nairobi |
| 2 | FRED KMGW 538W HULETI | Vibration Alert | 3 | 2026-04-10 02:58 | Nairobi |

**Observations:**
- Both alarms 2 hours apart while vehicle is parked overnight
- Vibration type 3 while stationary could indicate vehicle tamper, attempted break-in, or sensor false positive
- `alarm_type` and `alarm_name` now correctly populated — **BUG-01 fix confirmed working**
- No speed or overspeed alarms (fleet parked as expected)

---

## 8. Trips

**Trips recorded: 0** — Expected. Fleet is parked overnight.

Post-migration schema confirmed:
- `distance_km` column present — **BUG-02 distance correction applied** (historical values normalised from mm to km; column renamed from `distance_m`)
- `max_speed_kmh` column present — **BUG-03 fix deployed** (will populate on next trip poll)

First trips expected to appear from ~06:30 EAT when vehicles start moving.

---

## 9. Parking Events

**Parking events recorded: 0**

POLL-02 fix deployed (`acc_type=0`, corrected `durSecond` field mapping). Events will populate when vehicles begin moving and stop. Validate after morning operations.

---

## 10. Ingestion Log — Polling Health

Cumulative totals from `tracksolid.ingestion_log`:

| Poll Type | API Calls | Rows Upserted / Inserted | Notes |
|---|---|---|---|
| Location (live positions) | 297 | 5,643 | ~19 devices/sweep — healthy |
| Track list (position_history) | 15 | 80 waypoints | 30-min schedule running ✓ |
| Parking events | 58 | 0 | API responding; fix deployed |
| Alarms | 11 | 11 | Clean 1:1 ratio |
| Trips | — | 0 | No trips yet (overnight) |

**Polling pipeline is healthy.** All schedulers running. Location sweep averaging ~19 device positions per call, consistent with the 19 devices in `live_positions`.

---

## 11. Odometer Leaders — Service Flags

| Device | Odometer (km) | Status |
|---|---|---|
| KDK 829A GP | 238,643 | **SERVICE DUE** |
| Belta KCU-647D | ~234,000 | **SERVICE DUE** |

Both exceed 200,000 km. Recommend immediate physical inspection. Verify odometer values against dashboard — API-reported odometer can drift if the device was replaced or reset.

---

## 12. Geographic Anomaly — X3-63282

**X3-63282 is reporting from Uganda (~0.3°N, 32.5°E — approximately Kampala region).**

This device has been consistently reporting 28 fixes from this location in the last 24 hours, confirming it is not a one-off GPS error.

**Possible explanations:**
1. Vehicle on a legitimate cross-border trip to Uganda
2. Device removed from vehicle and in independent transit
3. Device installed in a non-fleet vehicle
4. GPS spoofing

**Action required:** Contact responsible driver/fleet manager immediately to confirm vehicle status and mission.

---

## 13. Schema Health Post-Migration

### Columns Added (Migration 04 + 05)

**`tracksolid.trips`:**
- `distance_km` ✓ — renamed from `distance_m`, values corrected (÷1,000,000)
- `max_speed_kmh` ✓ — will populate from next trip poll

**`tracksolid.obd_readings`** — normalized scalar columns added:
- `engine_rpm`, `coolant_temp_c`, `fuel_level_pct`, `battery_voltage` ✓
- `intake_pressure`, `throttle_pct`, `vehicle_speed`, `engine_load_pct` ✓

**`tracksolid.alarms`** — enrichment columns added:
- `severity`, `geofence_id`, `geofence_name` ✓
- `acknowledged_at`, `acknowledged_by` ✓

**`tracksolid.devices`** — vehicle enrichment columns added:
- `vehicle_category`, `cost_centre`, `assigned_route` ✓
- `depot_geom`, `depot_address` ✓

### New Tables (all present, empty — awaiting data)

| Table | Type | Populated By |
|---|---|---|
| `tracksolid.device_events` | Regular | `/pushevent` webhook |
| `tracksolid.fuel_readings` | Hypertable | `/pushoil` webhook |
| `tracksolid.temperature_readings` | Hypertable | `/pushtem` webhook |
| `tracksolid.lbs_readings` | Regular | `/pushlbs` webhook |
| `tracksolid.geofences` | Regular | Manual / API sync |

### DWH Gold Layer

`dwh_gold.fact_daily_fleet_metrics` has been enhanced with new columns:

| Column Group | Columns |
|---|---|
| Volume | `total_distance_km`, `total_trips`, `total_drive_hours`, `total_idle_hours` |
| Cost | `fuel_consumed_l` |
| Safety | `alarm_count`, `overspeed_count` |
| Schedule | `day_start_time`, `day_end_time` |
| Performance | `avg_speed_kmh`, `peak_speed_kmh` |

---

## 14. Data Quality Gaps — Priority Ranking

### Critical (blocking all meaningful reporting)

| Gap | Impact | Owner Action |
|---|---|---|
| `vehicle_name`, `vehicle_number`, `driver_name` blank for all 63 devices | Cannot attribute trips, alarms, or KPIs to drivers or plates | Bulk populate via Tracksolid Pro or API |
| 44 of 63 devices (70%) have no position data | Most of fleet invisible | Investigate SIM status, device power, connectivity |
| No push webhooks registered | OBD, fuel, temperature, device events all empty | Register 6 endpoints in Tracksolid Pro |

### High (limiting analytics depth)

| Gap | Impact | Owner Action |
|---|---|---|
| `fuel_100km` not set per device | Cannot compute fuel cost or efficiency | Set per vehicle class |
| Parking: 0 rows despite 58 API calls | No idle time or utilisation rate data | Validate post-morning operations |
| No geofences configured | No zone entry/exit detection, no off-route alerts | Create depot + key-site geofences |

### Medium (enhancing analytics)

| Gap | Impact | Owner Action |
|---|---|---|
| `vehicle_category` blank | Cannot segment by vehicle type | Populate with enrichment data |
| `cost_centre` blank | Cannot allocate costs to business units | Populate with enrichment data |
| `depot_geom` blank | Cannot compute distance-from-base metrics | Set per depot |

---

## 15. Grafana Dashboard Readiness

| Panel | Status | Blocker |
|---|---|---|
| Fleet map (live positions) | **Partial** — 19/63 devices visible | 44 devices not reporting |
| Position trail / route playback | **Ready** — 132 fixes, growing | — |
| Alarm feed | **Ready** — live, will grow with operations | — |
| Trips today (distance, duration, speed) | **Not ready** | Fleet parked overnight; validate AM |
| Driver behaviour (speeding, harsh events) | **Not ready** | Trips + driver metadata required |
| Fuel efficiency | **Not ready** | fuel_100km + OBD/fuel webhooks |
| Device connectivity uptime | **Not ready** | `/pushevent` webhook registration |
| Temperature/cold chain | **Not ready** | `/pushtem` webhook registration |

**Fleet map and alarm feed can go live immediately.** Full operational dashboards require metadata population and webhook registration (see Section 14).

---

## 16. Recommended Next Actions (Priority Order)

1. **Populate vehicle metadata** — `vehicle_number`, `vehicle_name`, `driver_name` for all 63 devices. This single action unlocks driver behaviour reporting, trip attribution, and all KPIs in `01_BusinessAnalytics.md`.

2. **Register push webhooks** in Tracksolid Pro dashboard:
   - `/pushtripreport` — trip completion events
   - `/pushobd` — OBD diagnostics
   - `/pushoil` — fuel sensor
   - `/pushtem` — temperature/humidity
   - `/pushlbs` — LBS cell fallback
   - `/pushevent` — device login/logout

3. **Investigate 44 non-reporting devices** — Pull IMEI list; check SIM status and last-seen dates in Tracksolid Pro.

4. **Investigate X3-63282 in Uganda** — Confirm vehicle status and mission with fleet manager.

5. **Validate morning data (09:00 EAT check):**
   ```sql
   -- Trips
   SELECT imei, COUNT(*) trips, ROUND(SUM(distance_km)::numeric,2) total_km,
          MAX(max_speed_kmh) top_speed
   FROM tracksolid.trips
   WHERE start_time > now() - interval '12 hours'
   GROUP BY imei ORDER BY total_km DESC;

   -- Parking
   SELECT COUNT(*) FROM tracksolid.parking_events
   WHERE created_at > now() - interval '12 hours';

   -- Alarm types populated (BUG-01 validation)
   SELECT alarm_type, alarm_name, COUNT(*)
   FROM tracksolid.alarms
   GROUP BY 1, 2 ORDER BY 3 DESC;
   ```

6. **Configure geofences** — At minimum: main depot(s), fuel stations, key customer sites.

7. **Set `fuel_100km`** per vehicle class to enable cost per trip calculations.

---

*End of report. Next comprehensive refresh recommended: 2026-04-11 09:00 EAT after morning operations have populated trip and movement data.*