Name

lcb_enable_timings — internal timings

Synopsis

cc [ flag … ] file… -lcouchbase [ library … ]

#include <libcouchbase/couchbase.h>
lcb_error_t lcb_enable_timings(lcb_t instance);
lcb_error_t lcb_disable_timings(lcb_t instance);
lcb_error_t lcb_get_timings(lcb_t instance,
                            const void * cookie,
                            lcb_timings_callback callback);

DESCRIPTION

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. The lcb_timings_callback is a function with the following signature:

void  function(lcb_t instance,
               const void *cookie,
               lcb_timeunit_t timeunit,
               lcb_uint32_t min,
               lcb_uint32_t max,
               lcb_uint32_t total,
               lcb_uint32_t maxtotal);

instance is the libcouchbase instance that called lcb_get_timings(). cookie is the cookie provided to lcb_get_timings(). timeunit is the unit of time for the values (see below for the values). min and max specify the time range for this bucket. total is the number of commands within this time range. maxtotal is the highest number in one of the buckets (this value may be used to "scale" the other values.

Time units

The following time units are defined:

LCB_TIMEUNIT_NSEC     The times are specified in nanoseconds
LCB_TIMEUNIT_USEC     The times are specified in microseconds
LCB_TIMEUNIT_MSEC     The times are specified in milliseconds
LCB_TIMEUNIT_SEC      The times are specified in seconds

RETURN VALUES

lcb_enable_timings(), lcb_disable_timings() and lcb_get_timings() returns LCB_SUCCESS on success, or an error code describing the error otherwise. See lcb_strerror(3couchbase) for more information about error codes.

EXAMPLES

The following example dumps a small histogram of lantencies

#include <libcouchbase/couchbase.h>
...
static void callback(lcb_t instance, const void *cookie,
                     lcb_timeunit_t timeunit,
                     lcb_uint32_t min,
                     lcb_uint32_t max,
                     lcb_uint32_t total,
                     lcb_uint32_t 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);
}
...
lb_enable_timings(instance);
... do a lot of operations ...
fprintf(stderr, "              +---------+\n"
lcb_get_timings(instance, stderr, callback);
fprintf(stderr, "              +---------+\n"
lcb_disable_timings(instance);
...

Note that the source code for libcouchbase also includes an example program which further demonstrates these functions.

ATTRIBUTES

See lcb_attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability

Committed

MT-Level

MT-Safe

COPYRIGHT

Copyright 2010-2013 Couchbase, Inc.

SEE ALSO

Learn more at http://www.couchbase.com/communities/c.

libcouchbase(3lib), lcb_create(3couchbase), lcb_wait(3couchbase), lcb_attributes(5)