All projects

Project 04 / Open-source npm package

Traxx

Route analytics for Express in one line of middleware: every request's latency, status, payload and errors — with the database write kept off the request path.

Year
2025
Role
Author & maintainer
Type
npm package
Status
v2.0.3 on npm
Line of setup
1
app.use(traxx.middleware())
Releases
11
Published on npm
Alert channels
3
Slack, Teams, Google Chat
Write batches
3s
Bulk inserts to MongoDB

01

The problem

Most Express apps start with no visibility. When a route gets slow or starts throwing 500s, the first to notice is a user. The usual fixes are heavy — an APM agent, a hosted vendor, a dashboard to configure — when a small team really wants one row per request that it can query.

Traxx is that row. It stores every request as its own MongoDB document, with no pre-aggregation, so any question — the slowest routes for one tenant, the errors since a deploy — is just a query. The one rule: tracking must never make the request slower.

02

How it works

The life of a tracked request
  1. 01

    Middleware

    Starts a process.hrtime() timer and wraps res.json, res.send and next() to capture the response body and any error.

  2. 02

    On finish

    Once the response is flushed, it computes latency, resolves the route pattern (/shop/:id, not /shop/42) and builds the log.

  3. 03

    BullMQ queue

    The log is pushed to a Redis-backed queue. The user already has their response — nothing waits on the database.

  4. 04

    Worker

    Drains the queue into a buffer and sends an alert for every status code you configured.

  5. 05

    Bulk insert

    Every 3 seconds the buffer goes to MongoDB in a single insertMany.

03

Key decisions

  • Queue the write, don't await it

    Writing to MongoDB inline adds a network round-trip to every request. A BullMQ queue takes it off the critical path and absorbs bursts.

    Ruled outInline database writes inside the middleware

  • Raw rows, not aggregates

    One document per request keeps every question answerable later. Aggregation becomes a query, not a schema decision made up front.

    Ruled outPre-aggregated counters per route

  • Batch the inserts

    An insertMany every few seconds turns thousands of tiny writes into a handful of bulk ones.

    Ruled outOne insert per queued job

  • Custom fields per middleware

    Pass { tenantId } and every log carries it — multi-tenant analytics without a schema change.

  • Pluggable alert channels

    Slack, Teams and Google Chat sit behind one notifier, and the trigger is either a list of status codes or a { min, max } range.

  • Ship the types

    The package ships its own index.d.ts, so TypeScript users need no @types install.

04

In the code

Setting it up — tracking, per-tenant tags and 5xx alerts to Slack
const express = require("express");
const Traxx = require("traxx");

const app = express();

const traxx = new Traxx({
  mongoUri: process.env.MONGO_URI,
  redisUri: process.env.REDIS_URI,
  notifications: {
    statusCodes: { min: 500, max: 599 },
    channels: [{ type: "slack", options: { webhookUrl: process.env.SLACK_WEBHOOK_URL } }],
  },
});

// Every request on every route is now tracked
app.use(traxx.middleware());

// Tag logs per tenant for multi-tenant analytics
app.use((req, res, next) => traxx.middleware({ tenantId: req.tenantId })(req, res, next));

app.listen(8080, async () => {
  await traxx.init(); // connects Mongo + Redis, starts the worker
});

05

What I'd do next

  • Close the crash window. The worker acknowledges a job as soon as it's buffered, so a crash before the next flush loses up to 3 seconds of logs. Acknowledging after the bulk write fixes it.

  • Redact by default. Request and response bodies are stored as-is. Before it sees personal data, it needs a redaction list for fields like password and token.

  • Cap the storage. Logs are kept forever today; a TTL index on timestamp would bound the collection.

  • Run the worker apart. The worker starts inside the app process. Under heavy traffic it should run as its own service.

06

Stack

Runtime
Node.js ≥ 16Express.js
Queue
BullMQRedis (ioredis)
Storage
MongoDBMongoose
Alerts
SlackMicrosoft TeamsGoogle Chat
Distribution
npmTypeScript declarations