@trap_stevo/metrictide/README.md

Unlock powerful analytics through this modular, event-driven solution built for real-time metric tracking, aggregation, and forecasting. Capture actionable trends, segment data with flexible tag structures, and generate predictive insights using built-in

# 📈 MetricTide

Unlock powerful analytics through this modular, event-driven solution built for real-time metric tracking, aggregation, and forecasting. Capture actionable trends, segment data with flexible tag structures, and generate predictive insights using built-in time series intelligence. From monitoring product usage and tracking system health to analyzing campaign performance and observing key operational metrics, this solution adapts fluidly to diverse analytic demands. Scale effortlessly with persistent storage, plugin extensibility, and full event hook integration across any application environment.

## Features

- 🔍 **Track Custom Metrics** – Log events, counters, gauges, or custom inputs in real time.
- 📊 **Aggregate Data** – Instantly calculate sum, average, min, max, and count across metrics.
- ⏳ **Time Series Analysis** – Group and visualize metrics over custom time intervals.
- 🔮 **Forecasting** – Predict future trends using linear regression over recent data.
- 🏷️ **Tag & Metadata Support** – Assign tags and metadata to enhance filtering and analysis.
- 💾 **Persistent Storage** – Optionally store metrics with auto-rehydration.
- 🧩 **Plugin System** – Extend functionality using custom logic via lifecycle hooks.
- 📡 **Event-Driven** – Respond to metric events (E.g. creation, updates, expiration, etc.).

---


## ⚙️ System Requirements

| Requirement    | Version            |
|----------------|--------------------|
| **Node.js**    | ≥ 19.x             |
| **npm**        | ≥ 9.x (recommended)|
| **OS**         | Windows, macOS, Linux |

---


## ⚙️ Configurations

The following shows the available configuration options for initializing `MetricTide` and its related components.

### ⚙️ `MetricTide` Constructor Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dbPath` | `string` | — | Path to database or storage file used to store the analytics. |
| `persistence` | `object` | `{}` | Persistence settings (e.g. TTL rules, domains). |
| `onTrack` | `Function \| null` | `null` | Optional callback called whenever a new metric got tracked. |
| `loadMetricsOnLaunch` | `boolean` | `false` | Whether to load stored metrics when the instance starts. |
| `enableMetricRouter` | `boolean` | `false` | Whether to enable HTTP(S) routing support for remote metrics. |
| `routerOptions` | `object` | `{}` | Optional settings passed to configure the MetricRouter. |

---


### 🧭 `routerOptions.metricRouterOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `restoreSessionsPaths` | `boolean` | `true` | Whether to automatically restore session-based routing paths. |
| `persistSessionKey` | `boolean` | `false` | Whether to persist the session key across restarts. |
| `persistSessionID` | `boolean` | `false` | Whether to persist the session ID across restarts. |
| `mutator` | `string` | `"m-mutator"` | Identifier used for the VeriLink mutator module. |
| `vaultSGN` | `string` | `"m-vault"` | Identifier for the secure vault group name. |
| `linkSGN` | `string` | `"m-link"` | Identifier for the secure link group name. |
| `sessionIDExtractor` | `Function \| null` | `null` | Optional function to extract session ID from a request. |
| `veriAuthConfigurations` | `object` | `{}` | VeriAuth configuration object (empty by default). |
| `enablePairing` | `boolean` | `true` | Enables device pairing support. |
| `pairingGuard` | `Function \| null` | `null` | Optional function to guard pairing logic. |
| `pairingPath` | `string` | `"/metric-device/pair"` | Endpoint path for device pairing. |

Use these parameters when initializing `MetricTide`.

```js
new MetricTide({
     dbPath : "./.app-metrics",
     persistence : {
          alwaysOn : true
     },
     onTrack : (record) => {
          console.log("Tracked:", record.name, record.value)
     },
     loadMetricsOnLaunch : true
})
```

---


# 📜 API Specifications

## 📈 MetricTide Methods

The primary tracking, aggregation, and metric interaction methods.

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `track(name, input = 1)` | Tracks a new metric with the specified name. `input` accepts any data type (default 1). | ✅ Sync |
| `getMetricsSince(interval = "1d", source = "storage", filter = {})` | Retrieves metrics recorded since a given time interval. | 🔄 Async |
| `getMetricsBetween(start, end, source = "storage", filter = {})` | Retrieves metrics recorded between two timestamps. | 🔄 Async |
| `getStoredMetrics(filter = {})` | Fetches all persisted metrics matching the filter. | 🔄 Async |
| `getMetrics(filter = {})` | Retrieves current (in-memory) metrics matching the given filter. | ✅ Sync |
| `getMetricsFromDomains(domains = [], options = {})` | Retrieves metrics across multiple domains. | 🔄 Async |
| `getMetricsInDomain(domain, options = {})` | Retrieves metrics within a specific domain. | 🔄 Async |
| `getMetricByID(id)` | Returns a specific metric by its ID. | ✅ Sync |
| `updateMetric(id, updates)` | Updates a metric’s properties by ID. | ✅ Sync |
| `searchByTagValue(key, match)` | Searches for metrics that match a specific tag key-value. | ✅ Sync |
| `getAggregate(name)` | Returns aggregate data for a given metric name (e.g., total, average). | ✅ Sync |
| `getAggregateByType(type)` | Returns aggregates grouped by metric type. | ✅ Sync |
| `groupByTag(tagKey)` | Groups metrics by a specific tag key. | ✅ Sync |
| `getTimeSeries(name, { interval = "minute", range = 3600000, aggregate = "sum" })` | Returns a time series of a metric grouped by interval. | ✅ Sync |
| `predictMetric(name, config = {})` | Predicts future metric values based on historical trends. | ✅ Sync |
| `usePlugin(plugin)` | Registers a plugin to extend tracking or processing behavior. | ✅ Sync |
| `clearMetricsInDomain(domain, options = {})` | Removes all metrics within a specific domain. | 🔄 Async |
| `clearAllMetrics()` | Clears all tracked metrics in memory. | ✅ Sync |
| `loadPersisted()` | Loads metrics from storage into memory. | 🔄 Async |

---


## 📡 Metric Events

`MetricTide` emits rich lifecycle events to allow external listeners (e.g., plugins, observers) to react to tracking, updates, and clearing of metrics or storage.

### 📥 Creation Events

| Event | Payload | Description |
|-------|---------|-------------|
| `metric:created` | `record` | Emitted on the creation of any metric. |
| `metric:created:{metricName}` | `record` | Emitted on the creation of a metric with a specific name. |
| `metric:created:{category}` | `record` | Emitted on the creation of a metric belonging to a category. |
| `metric:created:*` | `record` | Wildcard for all metric creation events. |
| `metric:*:{metricName}` | `record` | Wildcard creation/update event for a specific metric name. |
| `metric:*:*` | `record` | Fully wildcarded metric event, used for all creations/updates. |

### ✏️ Update Events

| Event | Payload | Description |
|-------|---------|-------------|
| `metric:updated` | `metric` | Emitted when any metric updates. |
| `metric:updated:{metricName}` | `metric` | Emitted when a specific metric updates. |
| `metric:*:updated` | `metric` | Wildcard update event for any metric update. |

### 🧹 Clearing Events

| Event | Payload | Description |
|-------|---------|-------------|
| `metric:domain:cleared` | `domain` | Emitted when metrics get cleared in a specific domain. |
| `storage:domain:cleared` | `domain` | Emitted when storage clears in a specific domain. |
| `metric:cleared` | `void` | Emitted all metrics clear. |
| `storage:cleared` | `void` | Emitted when all storage clears. |

### 🔄 Sync Events

| Event | Payload | Description |
|-------|---------|-------------|
| `sync:update` | `[]` | Emitted during synchronization or flush. Placeholder for future enhancements. |

---


## Installation

```bash
npm install @trap_stevo/metrictide
```

## Basic Usage

```js
const MetricTide = require("@trap_stevo/metrictide");

const analytics = new MetricTide({
     dbPath : "./.demo-metrics-db",
     persistence : {
          alwaysOn : true
     },
     onTrack : (record) => {
          console.log("Tracked:", record.name, record.value)
     },
     loadMetricsOnLaunch : true
});

analytics.track("signup", 1);

analytics.track("purchase", { value : 300, tags : { user : "user456" } });
```

---


### Aggregating & Forecasting

```js
const agg = analytics.getAggregate("purchase");

console.log("Aggregate:", agg);

const timeseries = analytics.getTimeSeries("purchase", {
     interval : "1m",
     range : "5m",
     aggregate : "sum"
});

console.log("Time Series:", timeseries);

const forecast = analytics.predictMetric("purchase", {
     interval : "1m",
     range : "5m",
     stepsAhead : 3
});

console.log("Forecast:", forecast);
```

---


### Filtering by Tag

```js
const filtered = analytics.searchByTagValue("user", "user");

console.log("Filtered by Tag:", filtered);
```

---


### Using Plugins

```js
analytics.usePlugin({
     onTrack(record) {
          console.log("[Plugin] New metric tracked:", record.name)
     },
     onClear() {
          console.log("[Plugin] Metrics cleared.")
     }
});
```

---


### Events

```js
analytics.events.on("metric:created", (record) => {
     console.log("[Event] Metric Created:", record.name)
});

analytics.events.on("metric:expired", (records) => {
     console.log("[Event] Expired:", records.length)
});
```

---


### Querying Metrics

#### Use `getMetricsSince()` with Human-Readable Intervals

```js
const recent = await analytics.getMetricsSince("5m");

console.log("Recent Metrics (last 5 minutes):", recent);
```

---


#### Optionally Filter by Tag or Metadata

```js
const recentPurchases = await analytics.getMetricsSince("1h", "storage", {
     name : "purchase",
     tags : { user : "user123" },
     metadata : { env : "prod" }
});

console.log("Recent Purchases (1h):", recentPurchases);
```

---


#### Use In-Memory Source Instead of Persistent Storage

```js
const inMemory = analytics.getMetricsSince("30s", "memory");

console.log("In-Memory Metrics (30s):", inMemory);
```

---


## License

See license in [LICENSE.md](./LICENSE.md)