feat: add activity history, insights, and cat usage events
- Add activity history collection for cat usage events - Add insight metrics (total cycles, average cycles, cycles today) - Add cat usage events with weight for LR4 - Add intermediate state events (cycle started, cycle complete, etc.) - Add pet visits_24h metric from weight history - Add new LR4 metrics: lifetime_cycles, dfi_trigger_count, cat_detected - Add configurable activity lookback window to prevent duplicate events - Add API call delays to avoid rate limiting - Update default poll interval to 5 minutes - Update documentation with new metrics and events
This commit is contained in:
Tanishq Dubey
97
README.md
97
README.md
@@ -12,10 +12,12 @@ Datacat connects to the Whisker API (used by Litter-Robot and Feeder-Robot devic
|
||||
|
||||
## Features
|
||||
|
||||
- Collects metrics from all connected robots every 2 minutes (configurable)
|
||||
- Collects metrics from all connected robots every 5 minutes (configurable)
|
||||
- Fetches activity history to detect cat usage events
|
||||
- Collects insight data (cycle counts, daily averages)
|
||||
- Submits metrics to Datadog via DogStatsD
|
||||
- Emits Datadog events for state changes (drawer full, offline, errors)
|
||||
- Supports pet profile metrics (weight, health status)
|
||||
- Emits Datadog events for state changes (cat usage, drawer full, offline, errors)
|
||||
- Supports pet profile metrics (weight, health status, visit count)
|
||||
- Dry-run mode for testing without submitting metrics
|
||||
- Configuration via environment variables or YAML file
|
||||
|
||||
@@ -69,9 +71,13 @@ Datacat can be configured via environment variables, a YAML config file, or both
|
||||
| `DATADOG_API_KEY` | Datadog API key | Yes |
|
||||
| `DATADOG_APP_KEY` | Datadog application key | No |
|
||||
| `DATADOG_SITE` | Datadog site (default: `datadoghq.com`) | No |
|
||||
| `DATACAT_POLL_INTERVAL` | Polling interval in seconds (default: `120`) | No |
|
||||
| `DATACAT_POLL_INTERVAL` | Polling interval in seconds (default: `300`) | No |
|
||||
| `DATACAT_INCLUDE_PETS` | Include pet metrics (default: `true`) | No |
|
||||
| `DATACAT_EMIT_EVENTS` | Emit Datadog events (default: `true`) | No |
|
||||
| `DATACAT_COLLECT_ACTIVITY` | Fetch activity history (default: `true`) | No |
|
||||
| `DATACAT_COLLECT_INSIGHTS` | Fetch insight data (default: `true`) | No |
|
||||
| `DATACAT_API_DELAY` | Delay between API calls in seconds (default: `1.0`) | No |
|
||||
| `DATACAT_ACTIVITY_LOOKBACK` | Only emit events for activities within N minutes (default: `10`) | No |
|
||||
| `DATACAT_METRIC_PREFIX` | Metric prefix (default: `litterrobot`) | No |
|
||||
| `DATACAT_CONFIG_FILE` | Path to YAML config file | No |
|
||||
|
||||
@@ -89,9 +95,13 @@ datadog:
|
||||
metric_prefix: "litterrobot"
|
||||
|
||||
collector:
|
||||
poll_interval_seconds: 120
|
||||
poll_interval_seconds: 300
|
||||
include_pets: true
|
||||
emit_events: true
|
||||
collect_activity_history: true
|
||||
collect_insights: true
|
||||
api_call_delay_seconds: 1.0
|
||||
activity_lookback_minutes: 10
|
||||
```
|
||||
|
||||
## Usage
|
||||
@@ -130,16 +140,30 @@ datacat -v
|
||||
| `litterrobot.panel_lock_enabled` | Gauge | Panel lock status |
|
||||
| `litterrobot.power_status` | Gauge | 2=AC, 1=DC, 0=NC |
|
||||
|
||||
### Insight Metrics (from Activity History)
|
||||
|
||||
| Metric | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `litterrobot.insight.total_cycles` | Gauge | Total cycles in last 30 days |
|
||||
| `litterrobot.insight.average_cycles` | Gauge | Average daily cycles |
|
||||
| `litterrobot.insight.cycles_today` | Gauge | Cycles completed today |
|
||||
|
||||
### Litter Robot 4 Additional Metrics
|
||||
|
||||
| Metric | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `litterrobot.litter_level` | Gauge | Litter level (0-100%) |
|
||||
| `litterrobot.pet_weight` | Gauge | Last recorded weight (lbs) |
|
||||
| `litterrobot.scoops_saved` | Gauge | Environmental counter |
|
||||
| `litterrobot.wifi_rssi` | Gauge | WiFi signal strength |
|
||||
| `litterrobot.litter_level_calculated` | Gauge | Calculated litter level from ToF sensor |
|
||||
| `litterrobot.pet_weight` | Gauge | Last recorded cat weight (lbs) from robot scale |
|
||||
| `litterrobot.scoops_saved` | Gauge | Environmental savings counter |
|
||||
| `litterrobot.wifi_rssi` | Gauge | WiFi signal strength (dBm) |
|
||||
| `litterrobot.night_light_brightness` | Gauge | Brightness level |
|
||||
| `litterrobot.hopper_enabled` | Gauge | Hopper status |
|
||||
| `litterrobot.lifetime_cycles` | Count | Total lifetime clean cycles |
|
||||
| `litterrobot.odometer_power_cycles` | Count | Total power cycles |
|
||||
| `litterrobot.odometer_empty_cycles` | Count | Total empty cycles |
|
||||
| `litterrobot.dfi_trigger_count` | Count | Drawer full indicator triggers |
|
||||
| `litterrobot.cat_detected` | Gauge | 1 if cat currently detected |
|
||||
|
||||
### Feeder Robot Metrics
|
||||
|
||||
@@ -153,10 +177,13 @@ datacat -v
|
||||
|
||||
| Metric | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `litterrobot.pet.weight` | Gauge | Pet weight (lbs) |
|
||||
| `litterrobot.pet.weight` | Gauge | Pet weight from profile (lbs) |
|
||||
| `litterrobot.pet.estimated_weight` | Gauge | User-entered estimated weight |
|
||||
| `litterrobot.pet.last_weight_reading` | Gauge | Last sensor weight reading |
|
||||
| `litterrobot.pet.is_healthy` | Gauge | Health status |
|
||||
| `litterrobot.pet.is_active` | Gauge | Active status |
|
||||
| `litterrobot.pet.age` | Gauge | Pet age |
|
||||
| `litterrobot.pet.visits_24h` | Gauge | Litter box visits in last 24 hours |
|
||||
|
||||
### Tags
|
||||
|
||||
@@ -168,14 +195,56 @@ All metrics include the following tags:
|
||||
- `robot_model` - Robot model (Litter-Robot 3, Litter-Robot 4, Feeder-Robot)
|
||||
- `status` - Current robot status (for litter robots)
|
||||
|
||||
Pet metrics include:
|
||||
- `pet_id` - Unique pet identifier
|
||||
- `pet_name` - Pet name
|
||||
- `pet_type` - Pet type (cat/dog)
|
||||
|
||||
## Events
|
||||
|
||||
Datacat emits Datadog events for important state changes:
|
||||
Datacat emits Datadog events for important state changes. Events are sourced from both real-time state changes and activity history polling.
|
||||
|
||||
- **Robot goes offline/online** - Warning/Success event
|
||||
- **Waste drawer full** - Warning event
|
||||
- **Robot errors** (sensor faults, pinch detect, etc.) - Error event
|
||||
- **Food level low** (Feeder Robot, <20%) - Warning event
|
||||
### Cat Usage Events
|
||||
|
||||
| Event | Alert Type | Description |
|
||||
|-------|------------|-------------|
|
||||
| Cat used litter box | Info | Cat detected and weighed (LR4 includes weight) |
|
||||
| Cat detected | Info | Cat is using the litter box |
|
||||
|
||||
### Cycle Events
|
||||
|
||||
| Event | Alert Type | Description |
|
||||
|-------|------------|-------------|
|
||||
| Clean cycle started | Info | Cleaning cycle has begun |
|
||||
| Clean cycle complete | Info | Cleaning cycle finished |
|
||||
| Litter dispensed | Info | Litter hopper dispensed (LR4 with hopper) |
|
||||
|
||||
### Warning Events
|
||||
|
||||
| Event | Alert Type | Description |
|
||||
|-------|------------|-------------|
|
||||
| Drawer full | Warning | Waste drawer needs emptying |
|
||||
| Drawer almost full | Warning | 1-2 cycles remaining |
|
||||
| Robot went offline | Warning | Lost connection to robot |
|
||||
| Bonnet removed | Warning | Bonnet has been removed |
|
||||
| On battery backup | Warning | Running on DC power |
|
||||
| Pinch detected | Warning | Pinch was detected |
|
||||
| Food level low | Warning | Feeder below 20% |
|
||||
|
||||
### Error Events
|
||||
|
||||
| Event | Alert Type | Description |
|
||||
|-------|------------|-------------|
|
||||
| Cat sensor fault | Error | Cat sensor has a fault |
|
||||
| Over torque fault | Error | Motor over torque detected |
|
||||
| Dump position fault | Error | Dump position fault |
|
||||
| Home position fault | Error | Home position fault |
|
||||
|
||||
### Success Events
|
||||
|
||||
| Event | Alert Type | Description |
|
||||
|-------|------------|-------------|
|
||||
| Robot back online | Success | Robot reconnected |
|
||||
|
||||
## Development
|
||||
|
||||
|
||||
Reference in New Issue
Block a user