The FireBridge metrics system provides a comprehensive solution for tracking, aggregating, and analyzing events in your application. It’s designed to handle time-series data efficiently using Firebase Firestore as the backend.

​
Key Features

  • Flexible Event Tracking: Track any type of event with customizable counts and values
  • Time-based Aggregation: Automatically aggregate events by hour, day, week, month, or custom time units
  • Entity-based Organization: Group metrics by entities (users, products, etc.)
  • Real-time Updates: Increment metrics in real-time or batch update historical data
  • Timeline Views: Access aggregated data for any time period

​
Core Concepts

​
Metric Address

Every metric is identified by three components:
  • Noun: The entity type being tracked (e.g., “product”, “user”)
  • Action: The action being measured (e.g., “purchase”, “view”, “click”)
  • Entity: The specific entity ID (e.g., product ID, user ID)

​
Metric Structure

Metrics are stored in a hierarchical structure: 
metrics/
  └── {noun}-{action}/
      ├── config (units, settings)
      └── entities/
          └── {entity}/
              ├── summary (total count/value)
              └── timelines/
                  └── {unit}/
                      └── cursors/
                          └── {timestamp} (aggregated data)

​
Trackable Events

Events contain:
  • time: When the event occurred (Firestore Timestamp)
  • count: Number of occurrences (optional, defaults to 1)
  • value: Numerical value associated with the event (optional, defaults to 1)

​
Timezone Support

Metrics support timezone-aware aggregation for accurate daily, weekly, and monthly boundaries:
  • Configure timezone per metric using IANA timezone identifiers
  • Events are aggregated based on local time boundaries
  • Perfect for multi-region applications with location-specific reporting

​
Quick Start

​
Configure Metrics

First, configure your metric with time units and timezone: 
import { firebridgeMetric } from '@firebridge/cloud/metrics'

// Configure for UTC (default)
await firebridgeMetric('product', 'purchase').set({
  units: ['day', 'week', 'month'],
  dateUpdated: firestore.Timestamp.now()
})

// Configure with specific timezone for regional businesses
await firebridgeMetric('store', 'sale').set({
  units: ['hour', 'day', 'month'],
  timezone: 'America/New_York',  // Eastern Time
  dateUpdated: firestore.Timestamp.now()
})

​
Increment a Metric

Track a single event in real-time: 
import { incrementMetric } from '@firebridge/cloud/metrics'

// Track a product purchase - aggregated using configured timezone
await incrementMetric('product', 'purchase', 'product-123', {
  count: 1,
  value: 99.99,
  time: firestore.Timestamp.now()
})

​
Batch Update Metrics

Update historical data or import events: 
import { updateMetric } from '@firebridge/cloud/metrics'

// Import historical purchase events - respects configured timezone
await updateMetric('product', 'purchase', 'product-123', [
  { time: timestamp1, count: 5, value: 500 },
  { time: timestamp2, count: 3, value: 300 }
], {
  clean: true // Replace existing data
})

​
Next Steps