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:

#include <libcouchbase/couchbase.h>
 
static void callback(
 lcb_INSTANCE *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) {
  case LCB_TIMEUNIT_NSEC:
     fprintf(out, "ns");
     break;
  case LCB_TIMEUNIT_USEC:
     fprintf(out, "us");
     break;
  case LCB_TIMEUNIT_MSEC:
     fsprintf(out, "ms");
     break;
  case LCB_TIMEUNIT_SEC:
     fprintf(out, "s ");
     break;
  default:
     ;
  }
 
  fprintf(out, " |");
  for (int ii = 0; ii < num; ++ii) {
     fprintf(out, "#");
  }
  fprintf(out, " - %u\n", total);
}
 
 
lcb_enable_timings(instance);
... do a lot of operations ...
fprintf(stderr, "              +---------+\n"
lcb_get_timings(instance, stderr, callback);
fprintf(stderr, "              +---------+\n"
lcb_disable_timings(instance);

Function Documentation

lcb_enable_timings()

lcb_STATUS lcb_enable_timings

(

lcb_INSTANCE *

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

instance

the handle to lcb

Returns

Status of the operation.

Stability

Committed

lcb_disable_timings()

lcb_STATUS lcb_disable_timings

(

lcb_INSTANCE *

instance

)

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

Parameters

instance

the handle to lcb

Returns

Status of the operation.

Stability

Committed

lcb_get_timings()

lcb_STATUS lcb_get_timings	(	lcb_INSTANCE *	instance,
		const void *	cookie,
		lcb_timings_callback	callback )

Get the timings histogram.

Parameters

instance	the handle to lcb
cookie	a cookie that will be present in all of the callbacks
callback	Callback 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_INSTANCE *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

instance	the handle to lcb
cookie	the cookie you provided that allows you to pass arbitrary user data to the callback
timeunit	the "scale" for the values
min	The lower bound for this histogram bucket
max	The upper bound for this histogram bucket
total	The number of hits in this histogram bucket
maxtotal	The highest value in all of the buckets

Enumeration Type Documentation

lcb_timeunit_t

enum 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.