Prints time duration of various stages of a HTTP/S request, like DNS lookup, TLS handshake, Time to First Byte etc. Similarly to the time command, which measures process timings, the
nettime command measures HTTP/S request timings. You can find more information in Understanding & Measuring HTTP Timings with Node.js.
Attention: Command-line options changed between 0.x and 1.x versions, so that they become compatible with curl. If you use the
nettime command-line tool, check the affected options:
-e, --ignore-certificate => -k, --insecure-u, --unit => -t, --time-unit-U, --user => -u, --user
The programmatic interface did not change and has remained compatible.
Make sure that you have Node.js >= 8 installed. Install the
nettime package globally and print timings of a sample web site:
$ npm install -g nettime$ nettime https://www.google.comPhase Finished Duration-----------------------------------Socket Open 0.023s 0.023sDNS Lookup 0.024s 0.001sTCP Connection 0.053s 0.029sTLS Handshake 0.133s 0.079sFirst Byte 0.174s 0.041sContent Transfer 0.176s 0.002sSocket Close 0.177s 0.001s-----------------------------------Status Code: OK
nettime without any parameters prints usage instructions:
Usage: nettime [options] <URL>Options:-V, --version output the version number-0, --http1.0 use HTTP 1.0--http1.1 use HTTP 1.1 (default)--http2 use HTTP 2.0-c, --connect-timeout <ms> maximum time to wait for a connection-d, --data <data> data to be sent using the POST verb-f, --format <format> set output format: text, json, raw-H, --header <header> send specific HTTP header-i, --include include response headers in the output-I, --head use HEAD verb to get document info only-k, --insecure ignore certificate errors-o, --output <file> write the received data to a file-t, --time-unit <unit> set time unit: ms, s+ns-u, --user <credentials> credentials for Basic Authentication-X, --request <verb> specify HTTP verb to use for the request-C, --request-count <count> count of requests to make (default: 1)-D, --request-delay <ms> delay between two requests-A, --average-timings print an average of multiple request timings-h, --help output usage informationThe default output format is "text" and time unit "ms". Other optionsare compatible with curl. Timings are printed to the standard output.Examples:$ nettime -f json$ nettime --http2 -C 3 -A
Make sure that you use Node.js >= 8. Install the
nettime package locally and get time duration of waiting for the response and downloading the content of a sample web page:
npm install --save nettime
const nettime =
The main module exports a function which makes a HTTP/S request and returns a Promise to the result object.
The input argument is a string with a URL to make the request with, or an object with multiple properties.
The input object can contain:
url: string with a URL to make the request with.
credentials: object with
passwordstring properties to be used for formatting of the Basic Authentication HTTP header.
data: string or Buffer to send to the server using the HTTP verb
POSTand the content type
failOnOutputFileError: boolean for preventing the request timing operation from failing, if writing to the output file failed. If set to
false, the error will be printed on the standard output and the process exit code will be set to 2. It is in effect only if
outputFileis specified. The default is
headers: object with header names as string keys and header values as string values.
httpVersion: string with the protocol version ('1.0', '1.1' or '2.0') to be sent to the server. (Node.js HTTP support is hard-coded for 1.1. There can be a difference between 1.0 and 1.1 on the server side only. Node.js supports HTTP/2 in the version 8.4.0 or newer with the --expose-http2 command-lime option and in the version 8.8.1 or newer out-of-the-box. Alternatively, you can install a "http2" module as a polyfill.)
includeHeaders: boolean for including property
Object) with response headers in the promised result object. If
outputFileis specified, the headers are written to the beginning of the output file too.
method: HTTP verb to use in the HTTP request;
GETis the default, unless
-doptions are not set.
outputFile: file path to write the received data to.
rejectUnauthorized: boolean to refuse finishing the HTTPS request, is set to
true(the default), if validation of the web site certificate fails; setting it to
falsemakes the request ignore certificate errors.
returnResponse: boolean for including property
Buffer) with the received data in the promised result object.
requestCount: integer for making multiple requests instead of one.
requestDelay: integer to introduce a delay (in milliseconds ) between each two requests. The default is 100.
timeout: intere to set the maximum time (in milliseconds) a single request should take before aborting it.
The result object contains:
httpVersion: HTTP version, which the server responsed with (string).
statusCode: HTTP status code of the response (integer).
statusMessage: HTTP status message for the status code (string).
timings: object with timing properties from various stages of the request. Timing is an array with two integers - seconds and nanoseconds passed since the request has been made, as returned by process.hrtime.
"httpVersion": '1.1'"statusCode": 200"statusMessage": "OK""timings":"socketOpen": 0 13260126"dnsLookup": 0 13747391 // Optional, if hostname was specified"tcpConnection": 0 152135165"tlsHandshake": 0 433219351 // Optional, if HTTPS protocol was used"firstByte": 1 888887072"contentTransfer": 1 891221207"socketClose": 1 893156380
If the option
requestCount is greater than
1, the result objects will be returned in an array of the same length as teh
time-unit parameter affects not only the "text" output format of the command line script, but also the "json" one. If set to "ms", timing values will be printed in milliseconds. If set to "s+ns", timings will be printed as arrays in process.hrtime's format. Calling the
nettime function programmatically will always return the timings as arrays in process.hrtime's format.
The following functions are exposed as named exports from the
nettime/lib/timings module to help dealing with process.hrtime's timing format and timings from multiple requests:
getDuration(start, end): computes the difference between two timings. Expects two arrays in process.hrtime's format and returns the result as an array in the same process.hrtime's format.
getMilliseconds(timing): converts the timing to milliseconds. Expects an array in process.hrtime's format and returns the result as an integer.
computeAverageDurations(multipleTimings): computes average durations from an array of event timings. The array is supposed to contain objects with the same keys as the
timingsobject from the
nettimeresponse. The returned object will contain the same keys pointing to event durations in process.hrtime's format.
createTimingsFromDurations(timings, startTime): reconstructs event timings from event durations. The
timingsobject is supposed to contain the same keys as the
timingsobject from the
nettimeresponse, but pointing to event durations in process.hrtime's format. The returned object will contain the same keys, but pointing to event times in process.hrtime's format. The
startTimeparameter can shoft the event times. The default is no shift -
These methods can be required separately too:
constgetDuration getMillisecondscomputeAverageDurations createTimingsFromDurations} =
getMilliseconds are accessible also as static methods of the
nettime function exported from the main
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
- 2019-10-18 v2.1.2 Fix crash on Node.js 10 and newer
- 2019-03-10 v2.1.0 Added option for setting connection timeout
- 2018-05-19 v2.0.1 Fixed http2 connection for Node.js 8.11.2
- 2018-04-27 v2.0.0 Dropped support of Node.js 4
- 2018-03-16 v1.1.2 Upgrade package dependencies
- 2017-12-21 v1.1.1 Upgrade semantic release and other dependencies
- 2017-11-11 v1.1.0 Support HTTP/2 requests
- 2017-11-06 v1.0.0 Make command-line options compatible with curl
- 2017-11-06 v0.5.0 Add support for the curl options "iIXdo"
- 2017-11-06 v0.4.0 Support custom headers and Basic Authentication
- 2017-11-05 v0.3.3 Do not add seconds in nanosecond precision to avoid errors
- 2017-11-04 v0.3.2 Print HTTP status message too
- 2017-10-22 v0.3.1 Round resulting milliseconds instead of truncating them
- 2017-10-22 v0.3.0 Allow ignoring of TLS certificate errors
- 2017-10-22 v0.2.0 Add timing for Socket Close
- 2017-10-21 v0.1.0 Initial release
Copyright (c) 2017-2019 Ferdinand Prantl
Licensed under the MIT license.