{"id":24678639,"url":"https://github.com/contrast-security-oss/node-route-metrics","last_synced_at":"2026-05-21T05:31:41.750Z","repository":{"id":37791694,"uuid":"395345863","full_name":"Contrast-Security-OSS/node-route-metrics","owner":"Contrast-Security-OSS","description":"@contrast/route-metrics records the time it takes for routes to complete and writes them to a log. Included in the package is `log-reporter` which can be used to output the logged information in various formats.","archived":false,"fork":false,"pushed_at":"2025-02-03T21:40:01.000Z","size":663,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-16T03:45:01.986Z","etag":null,"topics":["route-timing","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Contrast-Security-OSS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-12T14:27:17.000Z","updated_at":"2025-02-03T21:40:05.000Z","dependencies_parsed_at":"2024-03-06T17:09:17.460Z","dependency_job_id":"eb839946-a92d-46ed-a139-f16677f4fd72","html_url":"https://github.com/Contrast-Security-OSS/node-route-metrics","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Contrast-Security-OSS%2Fnode-route-metrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Contrast-Security-OSS%2Fnode-route-metrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Contrast-Security-OSS%2Fnode-route-metrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Contrast-Security-OSS%2Fnode-route-metrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Contrast-Security-OSS","download_url":"https://codeload.github.com/Contrast-Security-OSS/node-route-metrics/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244845874,"owners_count":20520037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["route-timing","web"],"created_at":"2025-01-26T13:17:48.185Z","updated_at":"2026-05-21T05:31:36.728Z","avatar_url":"https://github.com/Contrast-Security-OSS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# route-metrics\n\n`route-metrics` allows server performance, exclusive of network time,\nto be compared on a route-by-route basis. It was created to compare server\nperformance with and without `@contrast/agent` being loaded and active.\n\n`route-metrics` measures the elapsed time of http/https requests from the\nthe time that the `request` event is emitted to the time the response's\n`end` function is called. Elapsed time is measured in microseconds but is\noutput in milliseconds by default.\n\n`route-metrics` writes a log file in which each line is JSON. the log files\ncan be interpreted using the included `log-processor`.\n\n## usage\n\nAs usual, execute `npm install @contrast/route-metrics` to install it.\n\nBut, unlike most packages, `route-metrics` is not required by your program.\nThe `route-metrics` agent must be run by importing it on the node command line.\n\n```\n$ node --import @contrast/route-metrics my-web-server.js\n```\n\nIf another package, say `@contrast/agent`, is being required on the command\nline, then `route-metrics` must be required first:\n\n```\n$ node --import @contrast/route-metrics -r @contrast/agent my-web-server.js\n```\n\nThis allows server performance, exclusive of network time, to be compared\nwith and without other packages installed. `route-metrics` writes a json\nlog file, `route-metrics.log` by default.\n\n### benchmarking\n\nA primary use case for `route-metrics` is benchmark performance of different\nconfigurations. Because the time-series data is written on intervals, it's\npossible that the last `proc`, `eventloop`, and `gc` entries will be before\nthe last of the `route` entries in the log file, so they won't encompass the\nentire set of requests in the benchmark.\n\nSend a `SIGINT` signal to the node process and `route-metrics` will write the\ntime-series data. It only listens for `SIGINT` once, but should get the signal\nbefore the application process does. This has been tested on Linux, not Macs.\nIt does not work on Windows - the program gets the `SIGINT` on `^C`, but not\nwhen signaled via `childprocess.kill('SIGINT')`.\n\n## processing the log file\n\nOnce the `route-metrics` agent has been used to generate a log file, it's\nuseful to do something with the output. The included log-processor can be\nexecuted via `npm run log-processor` and will look for the default log file\nin the current directory, `./route-metrics.log`. To specify a different log\nfile or location, `npm run log-processor dir/other-file-name.log`.\n\nThe log processor will read the log file, output some informational text,\nand use the requested reporter to write the output.\n\nInformational output is enclosed in brackets, e.g., `[this is information]`. So\nif the reporter is writing to the default, file descriptor 1 (stdout), the lines\nenclosed in brackets are not part of the report. They should all preceed the\nreporter output in any case.\n\n### csv reporter output\n\nThe first line after the informational lines is the header line.\n\nThe percentiles are calculated using the smallest value that is greater than\nor equal to the specified percentile of values; no interpolation is done.\n\n### json reporter output\n\nThis reporter writes no informational output. It writes the data gathered from\nthe log file as a single JSON object. The code is the only documentation for it\nat this time.\n\n## configuration\n\nAll route-metrics agent configuration is done via environment variables. The environment variables\nare shown with their default values.\n\n- `CSI_RM_LOG_FILE=route-metrics.log`\n- `CSI_RM_GARBAGE_COLLECTION=false`\n- `CSI_RM_EVENTLOOP=false`\n- `CSI_RM_EVENTLOOP_RESOLUTION=20`\n- `CSI_RM_LOG_ALL_LOADS=0`\n\nBoolean options must be set to `true` to enable. The eventloop resolution is how often it is\nsampled internally by node; the setting is in milliseconds. The log-all-loads option, when non-\nzero, causes all files that are loaded via `import` or `require` to be logged; the number is the\nsize in MB of the log file buffer because the default buffer size is not enough to handle the\nlarge number of writes generated by this option.\n\nThe `route-metrics` log processor is also configured via environment variables.\n\n- `CSI_RM_REPORTER=csv`   # json is also valid. the json reporter is a formatted dump of the raw data.\n- `CSI_RM_OUTPUT=1`       # if numeric writes to that file descriptor, else writes to that file name.\n- `CSI_RM_TEMPLATE`       # a template that defines how the output is grouped\n- `CSI_RM_MICROSECONDS`   # report times in microseconds instead of milliseconds. (json reporter\nalways reports raw data, i.e., microseconds or, in the case of the eventloop delay, nanoseconds.)\n\n## using a template\n\nA template is a JavaScript file that is used to group routes into buckets (groups). For\nexample, a route may have optional parameters or query params that would make\nthem appear, by default, as separate routes.\n\nSee example/template.js for a simple template with explanatory comments.\n\n## design philosophy\n\n`route-metrics` should have as low an impact on the server as possible. To this end, after startup,\nit does everything asynchronously and as efficiently as possible. If you see anything that can be\nmade more efficient please submit an issue or, ideally, submit a PR.\n\nWhile `route-metrics` strives to work correctly, it does not implement code to prevent garbage-in,\ngarbage-out. For example, providing `route-metrics` with an unwritable path will cause an EACCES\nerror to be thrown. Because the expected use is in a testing environment, this seems reasonable. If\nit turns out to be a bad decision, appropriate fallbacks can be implemented.\n\n`route-metrics` is also written with minimal production dependencies. At this time `shimmer` is the\nonly one.\n\n## route-metrics-utils\n\nThe `utils` directory is a separate npm workspace and is published to npm as\n`@contrast/route-metrics-utils`. It provides common parsing code for packages\nthat process `route-metrics` log files. `route-metrics`' own `log-processor`\nuses it as well as `route-metrics-viewer`.\n\n## limitations\n\n- works only with node versions \u003e= 18.19.0\n- does not report on web sockets\n- `log-processor` has minimal automated testing; manual testing has revealed no inconsistencies\nor errors.\n\n## breaking changes\n\nv1 =\u003e v2\n- `route-metrics` must be invoked using `--import`. `--require` is no longer supported.\n- node versions \u003c 18.19.0 are no longer supported.\n- `proc` entries now report raw data, not averages, for memory. the names have been\nchanged to reflect that (`heapUsedAvg` =\u003e `heapUsed` and `externalAvg` to `external`).\n- `arrayBuffers` have been added to the `proc` entry.\n- the averaging interval was removed. It was not documented and shouldn't cause any\nissues.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrast-security-oss%2Fnode-route-metrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontrast-security-oss%2Fnode-route-metrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrast-security-oss%2Fnode-route-metrics/lists"}