📦 TraceManager – High-Precision Node.js Tracing Utility

A modular tracing and logging utility for Node.js with plug-and-play performance diagnostics:

• 🔹 Console & file logging
• 🔹 Unit-based and flow-based timing
• 🔹 Custom outputs: DB, HTTP, broker (Kafka/RabbitMQ)
• 🔹 Stream-based piping
• 🔹 JSON config with NODE_ENV targeting

📚 Table of Contents

• 🔧 Setup
• ✅ Basic Console Tracing
• 📁 File Logging
• 🔁 Flow Tracing
• 🧪 Unit Test Example
• 🔌 Pipe to Database
• 🌐 Pipe to HTTP Endpoint
• 🐇 Pipe to Broker
• 🧪 Custom Log File
• 🔧 Pipe to Writable Stream
• 🧠 Access Recent Entries
• 🗂️ Keywords
• 🎯 Summary

🔧 Setup

🌍 Environment Support

TraceManager respects NODE_ENV. You can control when traces run using the env key inside each tag.

"ExampleTag": {
  "enabled": true,
  "writeTo": "console",
  "unit": "ms",
  "logSamplePercent": 100,
  "env": ["development", "production"]
}

To define the environment:

# Cross-platform (recommended)
cross-env NODE_ENV=production node app.js

# Unix-style only
NODE_ENV=production node app.js

Only tags matching the current environment will trigger output.

📦 Install dependencies

npm install uuid

⚙️ Config Setup

Auto-generated at config/trace.config.json if missing:

{
  "env": "development",
  "minDurationMs": 0,
  "maxEntries": 200,
  "defaultWriteTo": "console",
  "activeTags": {
    "ExampleTag": {
      "enabled": true,
      "writeTo": "console",
      "unit": "ms",
      "logSamplePercent": 100,
      "env": ["development"]
    }
  }
}

✅ Basic Console Tracing

const Trace = require("./TraceManager");
const end = Trace.trace("Doing work", "ExampleTag");
// your logic
end();

Sample Output:

[ExampleTag] Doing work took 12.34 ms

📁 File Logging (to logs/tracer.log)

"FileTrace": {
  "enabled": true,
  "writeTo": "file",
  "unit": "ms",
  "env": ["development", "production"]
}

Trace.trace("Write to file", "FileTrace")();

🔁 Flow Tracing

const flow = Trace.createFlow("UserSignupFlow", "FileTrace");

const validate = flow.step("Validation");
// validation logic
validate();

const save = flow.step("DB Save");
// DB logic
save();

flow.done();

Sample:

[FileTrace] Flow "UserSignupFlow" (ID: ...) — Total: 80.00 ms
├─ Validation       — 20.00 ms
└─ DB Save          — 60.00 ms

🧪 Unit Test Example

const Trace = require("./TraceManager");

test("basic trace logs within range", () => {
  const end = Trace.trace("TestOperation", "ExampleTag");
  for (let i = 0; i < 100000; i++) Math.sqrt(i);
  end();

  const logs = Trace.getRecentTraces();
  expect(logs.at(-1)?.message).toBe("TestOperation");
});

🔌 Pipe to Database

const db = require("./dbClient");
Trace.pipeTo(async (trace) => {
  await db.saveTrace(trace);
});

🌐 Pipe to HTTP Endpoint

const axios = require("axios");
Trace.pipeTo(async (trace) => {
  await axios.post("https://api.example.com/trace", trace);
});

🐇 Pipe to Broker (RabbitMQ/Kafka)

const rabbit = require("./rabbitmqClient");
Trace.pipeTo(trace => {
  rabbit.channel.sendToQueue("trace-logs", Buffer.from(JSON.stringify(trace)));
});

🧪 Custom Log File

Trace.pipeToFile("logs/custom.log");

🔧 Advanced: Pipe to Writable Stream

const { Writable } = require("stream");
const stream = new Writable({
  write(chunk, _, cb) {
    console.log("TRACE:", chunk.toString());
    cb();
  }
});
Trace.pipeToWritable(stream);

🧠 Access Recent Entries

const recent = Trace.getRecentTraces();
console.log(recent);

🗂️ Keywords (for documentation indexing)

• trace manager
• node.js performance
• observability
• custom logging
• flow-based tracing
• distributed trace
• devops tracing
• performance analysis
• in-memory log buffer
• stream traces

🎯 Summary

| Method | Use Case | | ------------------- | ------------------------------- | | trace() | One-off measurements | | createFlow() | Step-by-step timing | | pipeTo(fn) | Custom handler (DB, HTTP, etc.) | | pipeToFile(path) | Save as JSON lines | | pipeToWritable() | Any Node.js stream | | getRecentTraces() | Inspect recent N traces |