Couchbase C Client  2.7.7
Timings

Detailed Description

Determine how long operations are taking to be completed.

libcouchbase provides a simple form of per-command timings you may use to figure out the current lantency for the request-response cycle as generated by your application. Please note that these numbers are not necessarily accurate as you may affect the timing recorded by doing work in the event loop.

The time recorded with this library is the time elapsed from the command being called, and the response packet being received from the server. Everything the application does before driving the event loop will affect the timers.

The function lcb_enable_timings() is used to enable the timings for the given instance, and lcb_disable_timings is used to disable the timings. The overhead of using the timers should be negligible.

The function lcb_get_timings is used to retrieve the current timing. values from the given instance. The cookie is passed transparently to the callback function.

Here is an example of the usage of this module:

static void callback(
lcb_t instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min,
lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)
{
FILE* out = (void*)cookie;
int num = (float)10.0 * (float)total / ((float)maxtotal);
fprintf(out, "[%3u - %3u]", min, max);
switch (timeunit) {
fprintf(out, "ns");
break;
fprintf(out, "us");
break;
fsprintf(out, "ms");
break;
fprintf(out, "s ");
break;
default:
;
}
fprintf(out, " |");
for (int ii = 0; ii < num; ++ii) {
fprintf(out, "#");
}
fprintf(out, " - %u\n", total);
}
... do a lot of operations ...
fprintf(stderr, " +---------+\n"
lcb_get_timings(instance, stderr, callback);
fprintf(stderr, " +---------+\n"

Functions

lcb_error_t lcb_enable_timings (lcb_t instance)
 Start recording timing metrics for the different operations. More...
 
lcb_error_t lcb_disable_timings (lcb_t instance)
 Stop recording (and release all resources from previous measurements) timing metrics. More...
 
lcb_error_t lcb_get_timings (lcb_t instance, const void *cookie, lcb_timings_callback callback)
 Get the timings histogram. More...
 

Typedefs

typedef enum lcb_timeunit_t lcb_timeunit_t
 
typedef void(* lcb_timings_callback) (lcb_t instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)
 The following function is called for each bucket in the timings histogram when you call lcb_get_timings. More...
 

Enumerations

enum  lcb_timeunit_t
 Time units reported by lcb_get_timings() More...
 

Function Documentation

◆ lcb_enable_timings()

lcb_error_t lcb_enable_timings ( lcb_t  instance)

Start recording timing metrics for the different operations.

The timer is started when the command is called (and the data spooled to the server), and the execution time is the time until we parse the response packets. This means that you can affect the timers by doing a lot of other stuff before checking if there is any results available..

Parameters
instancethe handle to lcb
Returns
Status of the operation.
Stability
Committed:

◆ lcb_disable_timings()

lcb_error_t lcb_disable_timings ( lcb_t  instance)

Stop recording (and release all resources from previous measurements) timing metrics.

Parameters
instancethe handle to lcb
Returns
Status of the operation.
Stability
Committed:

◆ lcb_get_timings()

lcb_error_t lcb_get_timings ( lcb_t  instance,
const void *  cookie,
lcb_timings_callback  callback 
)

Get the timings histogram.

Parameters
instancethe handle to lcb
cookiea cookie that will be present in all of the callbacks
callbackCallback to invoke which will handle the timings
Returns
Status of the operation.
Stability
Committed:

Typedef Documentation

◆ lcb_timings_callback

typedef void(* lcb_timings_callback) (lcb_t instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)

The following function is called for each bucket in the timings histogram when you call lcb_get_timings.

You are guaranteed that the callback will be called with the lowest [min,max] range first.

Parameters
instancethe handle to lcb
cookiethe cookie you provided that allows you to pass arbitrary user data to the callback
timeunitthe "scale" for the values
minThe lower bound for this histogram bucket
maxThe upper bound for this histogram bucket
totalThe number of hits in this histogram bucket
maxtotalThe highest value in all of the buckets

Enumeration Type Documentation

◆ lcb_timeunit_t

Time units reported by lcb_get_timings()

Enumerator
LCB_TIMEUNIT_NSEC 

Time is in nanoseconds.

LCB_TIMEUNIT_USEC 

Time is in microseconds.

LCB_TIMEUNIT_MSEC 

Time is in milliseconds.

LCB_TIMEUNIT_SEC 

Time is in seconds.