trace-me

Trace-Me: Comprehensive Request Tracing for Node.js Applications

Trace-Me is a lightweight Node.js package designed to simplify request tracing across your entire application stack. It provides seamless trace ID propagation through Express middleware, Axios requests, and Winston logging.

---

✨ Features

• 🌐 End-to-end tracing — Track requests across services
• 🛣️ Express middleware — Automatic trace ID generation and propagation
• 📡 Axios integration — Automatically inject trace IDs into outgoing requests
• 📝 Winston logger integration — Include trace IDs in your logs
• 🔍 Async context management — Uses AsyncLocalStorage for reliable context propagation
• ⚙️ Customizable — Configure trace ID header and logging levels

---

🚀 Use Cases

Trace-Me can be used in various parts of a Node.js ecosystem:

1. Microservices architectures — Propagate trace IDs across API calls between services.
2. Express applications — Log every HTTP request with a unique ID.
3. APIs — Add trace context to requests for better diagnostics.
4. Background jobs & schedulers — Set custom trace IDs for jobs.
5. Third-party API calls — Include trace IDs in outgoing HTTP requests.
6. CI/CD environments — Add traceable logs during deployment.
7. Error monitoring systems — Correlate alerts with traceable logs.

---

📦 Installation

npm install trace-me
# or
yarn add trace-me
# or
pnpm add trace-me

---

🧑‍💻 Quick Start

Basic Express Setup

import express from "express";
import { tracingMiddleware, logger } from "trace-me";

const app = express();
app.use(tracingMiddleware());

app.get("/", (req, res) => {
  logger.info("Handling request");
  res.send("Hello World!");
});

app.listen(3000, () => {
  logger.info("Server started on port 3000");
});

---

🧠 Core Concepts

1. Tracing Middleware

import { tracingMiddleware } from "trace-me";

// Default usage
app.use(tracingMiddleware());

// Custom configuration
app.use(tracingMiddleware("x-custom-trace-id", ["error", "warn", "info"]));

• headerName: Custom trace ID header (default: 'x-trace-id')
• levels: Array of log levels that include trace IDs (null = all)

2. Logger Integration

import { logger, updateLoggerTraceLevels } from "trace-me";

logger.info("This will include a trace ID if available");

updateLoggerTraceLevels(["error", "info"]);
updateLoggerTraceLevels(null); // Reverts to all levels

3. Axios Integration

import { getAxiosInstance, setAxiosInstance } from "trace-me";
import axios from "axios";

// Default instance
await getAxiosInstance().get("https://api.example.com");

// Custom instance
const customAxios = axios.create({ baseURL: "https://api.example.com" });
setAxiosInstance(customAxios);

4. Manual Context Management

import { runWithContext, setTraceId, getTraceId } from "trace-me";

runWithContext(() => {
  setTraceId("manual-trace-id");
  console.log(getTraceId()); // → 'manual-trace-id'
});

---

⚙️ Advanced Usage

Custom Header Name

import { setTraceIdHeader } from "trace-me";

setTraceIdHeader("x-custom-trace-id");

---

🔗 Real-World Microservices Example

Service A (service-a/index.ts)

import express from "express";
import { tracingMiddleware, getAxiosInstance, logger } from "trace-me";

const app = express();
app.use(tracingMiddleware());

app.get("/call-service-b", async (req, res) => {
  const response = await getAxiosInstance().get("http://localhost:4000/data");
  logger.info("Received response from Service B");
  res.json({ from: "Service A", serviceB: response.data });
});

app.listen(3000, () => logger.info("Service A running on port 3000"));

Service B (service-b/index.ts)

import express from "express";
import { tracingMiddleware, logger } from "trace-me";

const app = express();
app.use(tracingMiddleware());

app.get("/data", (req, res) => {
  logger.info("Handled request in Service B");
  res.json({
    message: "Hello from Service B",
    traceId: req.headers["x-trace-id"],
  });
});

app.listen(4000, () => logger.info("Service B running on port 4000"));

---

⏱ Scheduled Jobs / Background Tasks

import { runWithContext, setTraceId, logger } from "trace-me";

function runBackgroundJob() {
  runWithContext(() => {
    setTraceId(`job-${Date.now()}`);
    logger.info("Running background job");
    // Logic...
  });
}

---

🧪 Error Handling

import { logger } from "trace-me";

try {
  throw new Error("Something went wrong");
} catch (err) {
  logger.error("Caught error", { error: err });
}

---

⚙️ Configuration Summary

Function	Description	Default
tracingMiddleware(header, levels)	Apply trace ID middleware	'x-trace-id', all levels
updateLoggerTraceLevels(levels)	Control which log levels show trace IDs	null (all levels)
setTraceIdHeader(name)	Globally set the trace header name	'x-trace-id'
setAxiosInstance(instance)	Set a custom Axios instance	Default Axios instance

---

✅ Best Practices

• Use consistent trace ID headers across services
• Set up the middleware early in your Express stack
• Include trace IDs in logs and error monitoring
• Use custom trace IDs for background tasks
• Instrument outgoing requests via Axios

---

🐛 Troubleshooting

Trace IDs not showing in logs?

• Make sure tracingMiddleware is applied before route handlers
• Ensure you call runWithContext if working outside Express

Trace ID missing in Axios?

• Always use getAxiosInstance() or call setAxiosInstance(...)

Memory concerns?

• AsyncLocalStorage is designed to avoid leaks. Avoid long-running contexts in runWithContext.

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request with clear description

---

📄 License

MIT © Niraj Surve

---

Trace-Me helps bring full visibility to your Node.js applications with minimal setup. Whether you're building a monolith or microservices, this package adds traceability to every request, response, and log.