# async-tracer > Trace all async operations, output as newline delimited JSON logs, with minimal overhead. Latest version **0.6.1** (published 2017-09-23) · MIT license · 0 weekly downloads ## Install ```sh npm install async-tracer pnpm add async-tracer yarn add async-tracer bun add async-tracer ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.6.1 | | Published | 2017-09-23 | | First published | 2016-05-06 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >=4 <8 | | Dependencies | 5 | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 15 | | Author | David Mark Clements | | Maintainers | davidmarkclements | ## Links - npm: https://www.npmjs.com/package/async-tracer - Repository: https://github.com/davidmarkclements/async-tracer - Homepage: https://github.com/davidmarkclements/async-tracer#readme - Issues: https://github.com/davidmarkclements/async-tracer/issues - npm.io page: https://npm.io/package/async-tracer ## Dependencies (5) - [flatstr](https://npm.io/package/flatstr.md) ^1.0.3 - [reusify](https://npm.io/package/reusify.md) ^1.0.1 - [quick-format](https://npm.io/package/quick-format.md) ^2.0.4 - [fast-safe-stringify](https://npm.io/package/fast-safe-stringify.md) ^1.0.9 - [json-stringify-safe](https://npm.io/package/json-stringify-safe.md) ^5.0.1 ## Recent versions - 0.6.1 (latest) — 2017-09-23 - 0.6.0 — 2016-05-09 - 0.5.0 — 2016-05-08 - 0.4.2 — 2016-05-08 - 0.4.1 — 2016-05-07 - 0.4.0 — 2016-05-07 - 0.3.2 — 2016-05-06 - 0.3.1 — 2016-05-06 - 0.3.0 — 2016-05-06 - 0.2.2 — 2016-05-06 - 0.2.1 — 2016-05-06 - 0.2.0 — 2016-05-06 - 0.1.1 — 2016-05-06 - 0.1.0 — 2016-05-06 - 0.0.0 — 2016-05-06 ## README # async-tracer Trace all async operations, output as newline delimited JSON logs, with minimal overhead. [![Build Status](https://travis-ci.org/davidmarkclements/async-tracer.svg)](https://travis-ci.org/davidmarkclements/async-tracer) ## Supports Node v4 to v6 ## Usage ### Write to a stream ```js require('async-tracer')(process.stderr) ``` ### Write to a path ```js require('async-tracer')('/var/async.' + process.pid + '.log') ``` ### Write to a file handle ```js require('async-tracer')(1) // 1 is STDOUT, default require('async-tracer')() //same thing ``` ## API ```js require('async-tracer') => (WritableStream, opts) => {enable, disable} ``` ```js require('async-tracer') => (String: path, ops) => {enable, disable} ``` ```js require('async-tracer') => (Number: handle, opts) => {enable, disable} ``` ### Interface #### `enable` Start tracing (will start automatically if `autostart` option is `true`) #### `disable` Stop all tracing ### Opts #### `autostart` [default: `true`] `Boolean` Begin tracing immediately #### `append` [default: `false`] `Boolean` Only applies to when a path is supplied, opens file with `a` flag instead of `w` flag. #### `prefix` [default: `undefined`] `Object` Additional data to attach to the beginning of each log message. #### `suffix` [default: `undefined`] `Object` Additional data to attach to the end of each log message. #### `stacks` [default: `false`] `Boolean` or `Number` If `true` then include an array of call sites in each `init` log, as the `stack` property. The stack array takes the following form: ``` ["functionName:fileName:lineNum:colNum"] ``` If set to a number, (from 1 to Infinity) `stacks` will also determine the maximum amount of frames to capture for the log (defaults to `Infinity` if `true`). #### `contexts` [default: `false`] `Boolean` Supply the operations context in the `pre` and `post` logs as the `ctx` property. The context is an exposed C object that holds state for the async op. ## Benchmarks Overhead of using `async-tracer` is about 25%. ```sh npm run benchmark ``` ### With tracing ``` Running 10s test @ http://localhost:3000 10 connections with 10 pipelining factor Stat Avg Stdev Max Latency (ms) 0.23 0.8 54 Req/Sec 33283.64 2291.73 35135 Bytes/Sec 3.7 MB 250.51 kB 3.93 MB ``` ### Without tracing ``` Running 10s test @ http://localhost:3000 10 connections with 10 pipelining factor Stat Avg Stdev Max Latency (ms) 0.13 0.44 33 Req/Sec 45426.91 1279.75 46303 Bytes/Sec 5.06 MB 150.72 kB 5.24 MB ``` Overhead of turning on tracing with `async_wrap` is around 8%, so the net overhead is 17%, mostly this is the cost of writing to a stream. ### Benchmarking Options The cost of turning `stacks` and `contexts` options on can also be determined with: ```sh npm run benchmark-options ``` Overhead of enabling context is surprisingly low, 4580k reqs without contexts 4370k reqs with context - about 5% overhead (profiled on Node 6.1.0, Mac OS X 2013, 2.6ghz i7, 16gb). However, YMMV based on real world usage. Another consideration of logging contexts is the log file size (although compression is likely to be quite effective). Overhead of enabling `stacks` is roughly the same as for enabling `contexts`. ## Example ```js var http = require('http') require('async-tracer')() http.createServer(function (req, res) { res.end('hello world') }).listen(3000) ``` ```sh curl http://localhost:3000 ``` ## Test ```sh npm test ``` ## License MIT ## Acknowledgements Sponsored by [nearForm](http://nearform.com) --- _Source: https://npm.io/package/async-tracer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._