{"_id":"@alikhan-devs/traceify","name":"@alikhan-devs/traceify","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alikhan-devs/traceify","version":"1.0.0","description":"Intelligent request tracing middleware for Express.js with request IDs, performance insights, and structured logging","main":"index.js","type":"commonjs","keywords":["express","middleware","logging","tracing","debugging","observability","nodejs","traceify"],"author":{"name":"Ali Khan"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AliKhan-Devs/traceify.git"},"bugs":{"url":"https://github.com/AliKhan-Devs/traceify/issues"},"homepage":"https://github.com/AliKhan-Devs/traceify#readme","engines":{"node":">=16"},"scripts":{"start":"node example/app.js","dev":"nodemon example/app.js"},"dependencies":{"express":"^5.2.1"},"devDependencies":{"nodemon":"^3.0.0"},"gitHead":"fb894557f7c31627eee8d053286bc98bb7eed2a8","_id":"@alikhan-devs/traceify@1.0.0","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-zeTXPq4VTEw7rAYleHFs7zr4x4GY/1GLTrWBdBrw/e8w3VozghRX+MxO6lhPCvHTMj++NO84fxvyhvufqldA7Q==","shasum":"e8e434c6096af8aca7b853a4aef318cba7a14a75","tarball":"https://registry.npmjs.org/@alikhan-devs/traceify/-/traceify-1.0.0.tgz","fileCount":10,"unpackedSize":13504,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCS3UUTRf4JF6Bp2dN3+auDktiPRnrWqy/JJwbXBBzgXgIhAMPx6MkBMNFXPnD/NExc38J1H0AqJgm9dXrEeue0cnu9"}]},"_npmUser":{"name":"alikhan-devs","email":"alikhandevs@gmail.com"},"directories":{},"maintainers":[{"name":"alikhan-devs","email":"alikhandevs@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/traceify_1.0.0_1777718670234_0.10017012378637324"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-02T10:44:30.122Z","1.0.0":"2026-05-02T10:44:30.376Z","modified":"2026-05-02T10:44:30.632Z"},"maintainers":[{"name":"alikhan-devs","email":"alikhandevs@gmail.com"}],"description":"Intelligent request tracing middleware for Express.js with request IDs, performance insights, and structured logging","homepage":"https://github.com/AliKhan-Devs/traceify#readme","keywords":["express","middleware","logging","tracing","debugging","observability","nodejs","traceify"],"repository":{"type":"git","url":"git+https://github.com/AliKhan-Devs/traceify.git"},"author":{"name":"Ali Khan"},"bugs":{"url":"https://github.com/AliKhan-Devs/traceify/issues"},"license":"MIT","readme":"# 📡 Tracify\r\n\r\n<p align=\"center\">\r\n  <img src=\"https://img.shields.io/badge/tracify-v1.0.0-38bdf8?style=for-the-badge&labelColor=0b0f19\" />\r\n  <img src=\"https://img.shields.io/badge/express-middleware-22c55e?style=for-the-badge&labelColor=0b0f19\" />\r\n  <img src=\"https://img.shields.io/badge/zero_config-true-facc15?style=for-the-badge&labelColor=0b0f19\" />\r\n  <img src=\"https://img.shields.io/badge/local_first-observability-8b5cf6?style=for-the-badge&labelColor=0b0f19\" />\r\n</p>\r\n\r\n<p align=\"center\">\r\n  <b>Lightweight Express.js observability middleware that automatically traces requests, database timing, and execution flow with a built-in UI.</b>\r\n</p>\r\n\r\n---\r\n\r\n## ⚡ What is Tracify?\r\n\r\n**Tracify is a zero-config request tracing SDK for Express.js.**\r\n\r\nIt helps you instantly understand:\r\n\r\n* How long each request takes\r\n* How much time is spent in DB operations\r\n* What happens inside your request lifecycle\r\n* Where bottlenecks are occurring\r\n\r\nNo setup. No external services. No dashboards to configure.\r\n\r\nJust install and use.\r\n\r\n---\r\n\r\n## 🚀 Features\r\n\r\n* 📡 Automatic request tracing\r\n* ⏱ Total, DB, and processing time breakdown\r\n* 🧠 Step-by-step request timeline\r\n* 🖥 Built-in `/trace` UI dashboard\r\n* 💾 Persistent storage (`.tracify/traces.json`)\r\n* 🔍 Route-level performance insights\r\n* 🧼 Safe logging with fallback protection\r\n* ⚡ Works with any Express app\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\nnpm install @alikhan-devs/tracify\r\n```\r\n\r\n---\r\n\r\n## 🧠 Quick Start\r\n\r\n```js\r\nconst express = require(\"express\");\r\nconst tracify = require(\"@alikhan-devs/tracify\");\r\n\r\nconst app = express();\r\n\r\napp.use(express.json());\r\n\r\n// Enable tracing (1 line)\r\napp.use(tracify());\r\n\r\napp.get(\"/users\", async (req, res) => {\r\n  req.tracer.addStep(\"fetching users\");\r\n\r\n  const users = await getUsersFromDB();\r\n\r\n  req.tracer.addStep(\"users fetched\");\r\n\r\n  res.json(users);\r\n});\r\n\r\napp.listen(3000, () => {\r\n  console.log(\"Server running on http://localhost:3000\");\r\n  console.log(\"Trace UI: http://localhost:3000/trace\");\r\n});\r\n```\r\n\r\n---\r\n\r\n## 🖥 Trace UI\r\n\r\nOnce enabled, open:\r\n\r\n```\r\nhttp://localhost:3000/trace\r\n```\r\n\r\nYou will see:\r\n\r\n* All API requests\r\n* Execution timeline\r\n* DB vs processing breakdown\r\n* Slow request highlighting\r\n* Request-by-request inspection\r\n\r\n---\r\n\r\n## 📊 Example Trace Output\r\n\r\n```json\r\n{\r\n  \"traceId\": \"7e556d045ed72e58\",\r\n  \"method\": \"GET\",\r\n  \"path\": \"/users\",\r\n  \"status\": 200,\r\n  \"totalTime\": 18,\r\n  \"dbTime\": 12,\r\n  \"processingTime\": 6,\r\n  \"steps\": [\r\n    { \"label\": \"fetching users\" },\r\n    { \"label\": \"users fetched\" }\r\n  ],\r\n  \"timestamp\": \"2026-05-02T10:26:02.071Z\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## 🧪 Tracer API\r\n\r\nInside routes:\r\n\r\n### Add step\r\n\r\n```js\r\nreq.tracer.addStep(\"validation started\");\r\n```\r\n\r\n### DB timing\r\n\r\n```js\r\nreq.tracer.startTimer(\"db\");\r\n\r\nawait User.find();\r\n\r\nreq.tracer.endTimer(\"db\");\r\n```\r\n\r\n---\r\n\r\n## ⚙️ Configuration\r\n\r\n```js\r\napp.use(tracify({\r\n  slowThreshold: 500, // ms threshold for slow request detection\r\n}));\r\n```\r\n\r\n---\r\n\r\n## 📁 Persistent Storage\r\n\r\nTraces are automatically saved to:\r\n\r\n```\r\n.tracify/traces.json\r\n```\r\n\r\nThis means:\r\n\r\n* Restart server → data still exists\r\n* Debug history persists\r\n* No external DB required\r\n\r\n---\r\n\r\n## 🔒 Security\r\n\r\nTracify is designed to be safe by default:\r\n\r\n* No external network calls\r\n* No data leaves your server\r\n* Sensitive logs are automatically sanitized\r\n* Can be disabled in production\r\n\r\n---\r\n\r\n## 🚫 Ignored Routes\r\n\r\nInternal UI routes are automatically ignored:\r\n\r\n* `/trace`\r\n* `/trace/api.json`\r\n\r\n---\r\n\r\n## 🧠 Why Tracify?\r\n\r\nMost observability tools require:\r\n\r\n* External dashboards\r\n* API keys\r\n* Setup complexity\r\n* Paid plans\r\n\r\nTracify is different:\r\n\r\n> You install it, and it just works inside your app.\r\n\r\nPerfect for:\r\n\r\n* Developers\r\n* Startups\r\n* MVPs\r\n* Internal tools\r\n* Learning backend performance\r\n\r\n---\r\n\r\n## 🛣 Roadmap\r\n\r\n* [ ] Real-time WebSocket streaming UI\r\n* [ ] Route grouping (`/users/:id`)\r\n* [ ] Performance percentiles (p50, p95)\r\n* [ ] Distributed tracing support\r\n* [ ] OpenTelemetry export\r\n* [ ] Cloud dashboard (optional SaaS layer)\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nMIT © Ali Khan\r\n\r\n---\r\n\r\n## ⭐ Support\r\n\r\nIf Tracify helped you:\r\n\r\n* Star the repo\r\n* Share it with developers\r\n* Use it in your projects\r\n\r\n\r\n","readmeFilename":"readme.md","_rev":"1-f68ae8a630e7aa94f8b188d2f519f827"}