tracetana

Trace your application's journey with the flexibility it deserves. Fork when operations split. Stage as they progress. Discover a user ID three steps in? Apply it retroactively to everything that came before. Build immutable trace contexts that adapt to how your code actually runs—not how you wish it did.

This is probably not the ideal way to do any of these things, but it's something that worked for me for a specifc use-case.

Installation

npm install @notdaniel/tracetana

Compatibility: Works with both CommonJS and ESM projects. Node.js >= 16.0.0 required.

Quick Start

// Works in both CommonJS and ESM projects
import { Tracer, Publisher } from "@notdaniel/tracetana";
// Or: const { Tracer, Publisher } = require("@notdaniel/tracetana");
import Redis from "ioredis";

const publisher = new Publisher({ redis: new Redis() });

let trace = new Tracer()
  .setPublisher(publisher)
  .stage("request.start", { path: "/api/users" });

await trace.publish();

// Add context discovered later - applies retroactively to all stages
const userId = await authenticate();
trace = trace.withGlobal({ userId });

trace = trace.stage("db.query", { table: "users" });
await trace.publish();

// Fork to track parallel operations
const cacheCheck = trace.fork("cache.lookup");
await cacheCheck.publish();

console.log(`Duration: ${trace.totalDuration}ms`);

Features

• Immutable contexts - Functional API with no mutation, safe to pass around
• Retroactive metadata - Use .withGlobal() to add context that applies to all past and future stages
• Fork for parallelism - Track concurrent operations while maintaining correlation
• Stage-based flow - Build traces incrementally with .stage() as operations progress
• Time series analysis - Built-in duration tracking and percentile stats
• Redis-backed - Streams, hashes, indexes, and stats with configurable TTLs
• Latency monitoring - Track publisher performance with .getLatencyStats()

Documentation

• Usage Examples - Common patterns and use cases

Requirements

Node.js ≥22.0.0 (ESM only)

License

MIT