---

name: metrics-tracking description: Custom metrics system, metric definitions, data ingestion, and aggregation. Use when working with metric tracking, data collection, or the metrics API.

Metrics Tracking Skill

Overview

LifeOS allows users to track any quantifiable data through custom metrics linked to dimensions with targets and aggregation.

Core Requirements

Metric Definition Properties

• Code: Unique identifier (snake_case)
• Name: Display name
• Unit: Measurement unit (steps, hours, kg, %)
• ValueType: integer, decimal, boolean, duration
• TargetValue/TargetDirection: higher_is_better, lower_is_better, in_range
• DimensionId: Link to life dimension (optional)
• AggregationType: sum, avg, min, max, count, latest, first
• IsActive: Currently tracked

Metric Record Properties

• MetricDefinitionId, Value, RecordedAt
• Source: manual, api, import
• Notes (optional)

API Endpoints

Method	Endpoint	Purpose
GET	/api/metrics/definitions	List definitions
POST	/api/metrics/definitions	Create metric
GET	/api/metrics/records	List records (filter by metric, date)
POST	/api/metrics/records	Create single record
POST	/api/collect	Batch ingestion (API key auth)

User Flows

Create Metric

1. Navigate to /metrics → "Add Metric"
2. Fill: name, code, unit, target, aggregation
3. Link to dimension (optional)
4. Save

Record Metric (Manual)

1. Dashboard/Metrics → Quick Log
2. Enter value and notes
3. Submit → Real-time SignalR update

Record via API

curl -X POST https://lifeos.app/api/collect \
  -H "X-API-Key: lifeos_abc_123" \
  -d '{"metrics": [{"code": "daily_steps", "value": 8432}]}'

Batch Ingestion

• Max 1000 records per request
• Auth: X-API-Key header
• Supports external integrations (Apple Health, Fitbit, etc.)

Testing (Playwright MCP)

• Test metric creation modal
• Verify sparkline renders
• Test API playground
• Verify real-time updates

Design Doc References

• Architecture: .gaia/designs/architecture.md - Metrics flow
• API: .gaia/designs/api.md - Collect endpoint

When to Invoke

Use when: metric types, data ingestion, aggregation, visualizations, external integrations.