Metrics you capture now, stored wherever you want

A small TypeScript library that counts things, records events and times operations. It hands you finished rows and lets you decide where they go.

Get started

What it is

Examples

🧮

Five kinds of metric

Counters for things you tally, gauges for values you sample, events and logs for records you keep whole, timers for how long work takes.

Compare them

🔌

No database built in

MetricHouse writes no SQL and opens no connections. You supply one function that takes rows, and it can put them anywhere.

Write a sink

📈

Read the numbers before they ship

Ask a metric what it holds right now, without waiting for a flush and without querying your database.

Live reads

🛡️

A failed write loses nothing

Data is only deleted after your function succeeds. If it throws, the same rows come back on the next attempt with the same row ids.

How it recovers

In one file

import { counter, createHouse, str } from 'metrichouse/core'
import { memory } from 'metrichouse/memory'

// 1. Say what you want to measure.
const pageViews = counter('page_views', {
  dims: { path: str() },
  resolution: '1m',                       // keep one row per minute
  flush: '5m',                            // ship no more than once every 5 minutes
  write: async (rows) => {
    await db.insertInto('page_views').values(rows).execute()
  },
})

// 2. Connect it to somewhere that holds the running totals.
const house = createHouse({ driver: memory(), schema: { pageViews } })
house.start()

// 3. Count.
pageViews.add({ path: '/pricing' })

// 4. Read it back straight away, before anything reaches the database.
await pageViews.current({ path: '/pricing' })   // 1

Your code calls add, MetricHouse counts it, a driver holds it, then your write function puts it in your database. — Your code adds to a metric. MetricHouse keeps the running totals and hands them to the function you wrote.

What it is for

Some information is gone forever if you do not record it as it happens. How many requests arrived in a given second. How many were errors. How long each one took. You cannot go back and work those out later.

MetricHouse captures that information cheaply, groups it into time windows, and hands you the finished rows. It does not query, chart or store anything itself.

If you want a full explanation of the idea before writing code, read What MetricHouse is. If you would rather see it running, go to Getting started.

Install

bash

npm install metrichouse

Node 20 or newer. The ioredis package is optional and only needed if you use the Redis driver.