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 using LevelDB with auto-rehydration.
• 🧩 Plugin System – Extend functionality using custom logic via lifecycle hooks.
• 📡 Event-Driven – Respond to metric events like creation, updates, or expiration.

Installation

npm install @trap_stevo/metrictide

Basic Usage

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

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

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

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

Using Plugins

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

Events

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

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

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

Optionally Filter by Tag or Metadata

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

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

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

License

See license in LICENSE.md