`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.
npm install @contrast/route-metricsroute-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'send 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.
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 commandroute-metrics
line, then 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 jsonroute-metrics.log
log file, by default.
A primary use case for route-metrics is benchmark performance of differentproc
configurations. Because the time-series data is written on intervals, it's
possible that the last , eventloop, and gc entries will be beforeroute
the last of the 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 theSIGINT
time-series data. It only listens for once, but should get the signalSIGINT
before the application process does. This has been tested on Linux, not Macs.
It does not work on Windows - the program gets the on ^C, but notchildprocess.kill('SIGINT')
when signaled via .
Once the route-metrics agent has been used to generate a log file, it'snpm run log-processor
useful to do something with the output. The included log-processor can be
executed via and will look for the default log file./route-metrics.log
in the current directory, . To specify a different lognpm run log-processor dir/other-file-name.log
file or location, .
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.
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.
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.
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
-
-
-
-
Boolean options must be set to true to enable. The eventloop resolution is how often it isimport
sampled internally by node; the setting is in milliseconds. The log-all-loads option, when non-
zero, causes all files that are loaded via 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 groupedCSI_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.)
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.
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,route-metrics
garbage-out. For example, providing 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.
- 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.
v1 => v2
- route-metrics must be invoked using --import. --require is no longer supported.proc
- node versions < 18.19.0 are no longer supported.
- entries now report raw data, not averages, for memory. the names have beenheapUsedAvg
changed to reflect that ( => 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.