# route-metrics `route-metrics` allows server performance, exclusive of network time, to be compared on a route-by-route basis. It was created to compare server performance with and without `@contrast/agent` being loaded and active. `route-metrics` measures the elapsed time of http/https requests from the the time that the `request` event is emitted to the time the response's `end` function is called. Elapsed time is measured in microseconds but is output in milliseconds by default. `route-metrics` writes a log file in which each line is JSON. the log files can be interpreted using the included `log-processor`. ## usage As usual, execute `npm install @contrast/route-metrics` to install it. But, unlike most packages, `route-metrics` is not required by your program. The `route-metrics` agent must be run by importing it on the node command line. ``` $ node --import @contrast/route-metrics my-web-server.js ``` If another package, say `@contrast/agent`, is being required on the command line, then `route-metrics` must be required first: ``` $ node --import @contrast/route-metrics -r @contrast/agent my-web-server.js ``` This allows server performance, exclusive of network time, to be compared with and without other packages installed. `route-metrics` writes a json log file, `route-metrics.log` by default. ### benchmarking A primary use case for `route-metrics` is benchmark performance of different configurations. Because the time-series data is written on intervals, it's possible that the last `proc`, `eventloop`, and `gc` entries will be before the last of the `route` entries in the log file, so they won't encompass the entire set of requests in the benchmark. Send a `SIGINT` signal to the node process and `route-metrics` will write the time-series data. It only listens for `SIGINT` once, but should get the signal before the application process does. This has been tested on Linux, not Macs. It does not work on Windows - the program gets the `SIGINT` on `^C`, but not when signaled via `childprocess.kill('SIGINT')`. ## processing the log file Once the `route-metrics` agent has been used to generate a log file, it's useful to do something with the output. The included log-processor can be executed via `npm run log-processor` and will look for the default log file in the current directory, `./route-metrics.log`. To specify a different log file or location, `npm run log-processor dir/other-file-name.log`. The log processor will read the log file, output some informational text, and use the requested reporter to write the output. Informational output is enclosed in brackets, e.g., `[this is information]`. So if the reporter is writing to the default, file descriptor 1 (stdout), the lines enclosed in brackets are not part of the report. They should all preceed the reporter output in any case. ### csv reporter output The first line after the informational lines is the header line. The percentiles are calculated using the smallest value that is greater than or equal to the specified percentile of values; no interpolation is done. ### json reporter output This reporter writes no informational output. It writes the data gathered from the log file as a single JSON object. The code is the only documentation for it at this time. ## configuration All route-metrics agent configuration is done via environment variables. The environment variables are shown with their default values. - `CSI_RM_LOG_FILE=route-metrics.log` - `CSI_RM_GARBAGE_COLLECTION=false` - `CSI_RM_EVENTLOOP=false` - `CSI_RM_EVENTLOOP_RESOLUTION=20` - `CSI_RM_LOG_ALL_LOADS=0` Boolean options must be set to `true` to enable. The eventloop resolution is how often it is sampled internally by node; the setting is in milliseconds. The log-all-loads option, when non- zero, causes all files that are loaded via `import` or `require` to be logged; the number is the size in MB of the log file buffer because the default buffer size is not enough to handle the large number of writes generated by this option. The `route-metrics` log processor is also configured via environment variables. - `CSI_RM_REPORTER=csv` # json is also valid. the json reporter is a formatted dump of the raw data. - `CSI_RM_OUTPUT=1` # if numeric writes to that file descriptor, else writes to that file name. - `CSI_RM_TEMPLATE` # a template that defines how the output is grouped - `CSI_RM_MICROSECONDS` # report times in microseconds instead of milliseconds. (json reporter always reports raw data, i.e., microseconds or, in the case of the eventloop delay, nanoseconds.) ## using a template A template is a JavaScript file that is used to group routes into buckets. For example, a route may have optional parameters or query params that would make them appear, by default, as separate routes. See example/template.js for a simple template with explanatory comments. ## design philosophy `route-metrics` should have as low an impact on the server as possible. To this end, after startup, it does everything asynchronously and as efficiently as possible. If you see anything that can be made more efficient please submit an issue or, ideally, submit a PR. While `route-metrics` strives to work correctly, it does not implement code to prevent garbage-in, garbage-out. For example, providing `route-metrics` with an unwritable path will cause an EACCES error to be thrown. Because the expected use is in a testing environment, this seems reasonable. If it turns out to be a bad decision, appropriate fallbacks can be implemented. `route-metrics` is also written with minimal production dependencies. At this time `shimmer` is the only one. ## limitations - works only with node versions >= 18.19.0 - does not report on web sockets - `log-processor` has minimal automated testing; manual testing has revealed no inconsistencies or errors. ## breaking changes v1 => v2 - `route-metrics` must be invoked using `--import`. `--require` is no longer supported. - node versions < 18.19.0 are no longer supported. - `proc` entries now report raw data, not averages, for memory. the names have been changed to reflect that (`heapUsedAvg` => `heapUsed` and `externalAvg` to `external`). - `arrayBuffers` have been added to the `proc` entry. - the averaging interval was removed. It was not documented and shouldn't cause any issues.