What Do Curl Timings Mean?

API Science monitor checks gather statistics that provide a means for analyzing multiple aspects of API performance. For example, clicking on a monitor name from your API Dashboard brings up a summary screen that includes a bar plot detailing the performance for the last 10 API checks:

cURL-stats-last-10

Each bar consists of four sub-bars that are stacked: Resolve, Connect, Processing, and Transfer. The total height of the stacked bars indicates the total time it took for the API check to complete.

In the above plot, it looks like Transfer time is missing. Clicking one of the date/time stamps in the table below provides a detailed view of that check, for example:

cURL-stats-detail

This shows that the Transfer time was 0.21 milliseconds, which is less than 0.4% of the total time for the check. Pixel rendering in the stacked columns can make a tiny Transfer sub-bar not appear.

But what do these values mean? What are they actually telling us?

curl Metrics

curl is “an open source command line tool and library for transferring data with URL syntax,” that supports many different Internet protocols such as FTP, HTTP, HTTP GET, and IMAP.

The API Science platform uses curl to access the API URLs you specify when you create a monitor. For example, the “br Washington DC” monitor shown above executes an HTTP GET command for the URL http://api.worldbank.org/countries/br, requesting information about Brazil from the World Bank Countries API.

The curl man page includes information curl’s --write-out feature, which provides access to metrics about the just-completed URL transfer, including timing measures used by API Science, for example,  time_name_lookup, time_connect, time_start_transfer, and time_total. However, the definitions in the man page are highly technical, and if you don’t know the details of how HTTP and the Internet’s infrastructure fit together, the curl man definitions may not provide clarity.

In his blog post HTTP Request Timings with cURL, Ken Weiner describes what happens when a client makes an HTTP request:

  1. DNS name resolution
  2. SSL/SSH/etc connect/handshake to the remote host if applicable
  3. TCP connection to the remote host
  4. Negotiations specific to the particular protocol(s) involved
  5. Redirects if applicable
  6. Content generation on remote host
  7. Content transfer

He uses the image below to represent “a simple request to a non-SSL page that involves no redirects”:

Ken-Weiner-curl-phasesAn HTTP GET to the World Bank’s Countries API is similar to this. You’ll also notice that Ken divides up the request and the return of the requested data into four categories, just like the API Science monitor performance plots and tables.

Resolve Time

API Science’s “Resolve Time” is the equivalent of Ken’s “DNS Lookup.” DNS stands for Domain Name System. A URL consists of text (and sometimes numbers); however, the communication addresses that compose the Internet are formulated as IP (Internet Protocol) addresses, for example, 208.80.152.2. Before a request can be routed between the requesting client and the server that will process the request, the IP address that the URL refers must be looked up. A request is sent to a DNS resolver by curl, and the resolver returns the correlated IP address. API Science’s “Resolve Time” is the time in milliseconds that it took this operation to complete.

Connect Time

With the IP address in hand, it’s possible to directly connect with the server that will process the request, using the TCP protocol. It is the time between when curl sends a request to the IP address and the server responds with a reply that confirms a communications channel has been established. This process is what API Science’s “Connect Time” represents.

Processing Time

API Science’s “Processing Time” is the equivalent of Ken Weiner’s “Content Generation.” This includes the time for the request information to be communicated to the server, and the time the server takes to create the response. During this period, curl is primarily idle, waiting for the API server to do its work. When the server has completed all of its processing and generated the response text, it signals the client that is about to send the first byte. API Science’s “Processing Time” in essence measures the API server’s performance.

Transfer Time

API Science’s “Transfer Time” is the same as Ken’s “Content Transfer” time. The server has signaled that the response text is ready to be sent, and it is transferred byte-by-byte and received by the curl client. When the entire response text has been received by curl, the server signals that is ready to close the connection. API Science’s “Transfer Time” is the amount of time it took to transfer all of the response bytes.

Conclusion

Returning to the “br Washington DC” example case from above:

cURL-stats-detail

we see that:

  • obtaining the IP address that corresponds to the URL http://api.worldbank.org/countries/br took 29.45 msec (Resolve Time)
  • contacting the API server and performing a handshake that confirmed curl and the server were connected took 0.72 msec (Connect Time)
  • sending the request text to the server and waiting for it to notify curl that it was about to begin sending the response bytes took 29.21 msec (Processing Time);
  • receiving all the response bytes took 0.21 msec (Transfer Time).

This illustrates the type of timing information curl provides, and shows what API Science’s timing metrics mean.