Threshold Logging Tracing through the SDK

Why Tracing?

Tracing is recording details about discrete steps or phases of a request lifecycle, such as request encoding / decoding, or dispatching to server. These phases are timed independently, and contain additional contextual information. A single request is typically made up of multiple tracing points.

Open Tracing

OpenTracing is a standardised API to structure tracing information in a consistent and predictable manner.

Threshold Logging in C SDK

Response Time Observability is implemented as Threshold Logging in libcouchbase from release 2.9.0.

Table 1. Threshold Logging Tracer Properties
Setting name Macro name for lcb_cntl Description Default Value

enable_tracing

LCB_CNTL_ENABLE_TRACING

Boolean used to determine tracing is enabled. Defaults to using the ThesholdLoggingTracer if enabled. When false a Noop or similar tracing implementation should be used instead. Also when enabled the SDK will try and retrieve duration metrics from the server for KV operations.

true

tracing_threshold_queue_flush_interval

LCB_CNTL_TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL

The interval between executions that process the collected operation spans. Expressed in seconds with fractions (or microseconds for lcb_cntl).

10.0 seconds (or 10000000 microseconds)

tracing_threshold_queue_size

LCB_CNTL_TRACING_THRESHOLD_QUEUE_SIZE

The maximum number of items to keep in internal queue per service.

128

tracing_threshold_kv

LCB_CNTL_TRACING_THRESHOLD_KV

The KV operation operation threshold. Expressed in seconds with fractions (or microseconds for lcb_cntl).

0.5 second (500000 microseconds)

tracing_threshold_view

LCB_CNTL_TRACING_THRESHOLD_VIEW

The View query operation threshold. Expressed in seconds with fractions (or microseconds for lcb_cntl).

1 second (1000000 microseconds)

tracing_threshold_n1ql

LCB_CNTL_TRACING_THRESHOLD_N1QL

The N1QL query operation threshold. Expressed in seconds with fractions (or microseconds for lcb_cntl).

1 second (1000000 microseconds)

tracing_threshold_fts

LCB_CNTL_TRACING_THRESHOLD_FTS

The FTS query operation threshold. Expressed in seconds with fractions (or microseconds for lcb_cntl).

1 second (1000000 microseconds)

tracing_threshold_analytics

LCB_CNTL_TRACING_THRESHOLD_ANALYTICS

The Analytics query operation threshold. Expressed in seconds with fractions (or microseconds for lcb_cntl).

1 second (1000000 microseconds)

tracing_orphaned_queue_flush_interval

LCB_CNTL_TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL

The interval between executions that processes the collected operation spans. Expressed in seconds with fractions (or microseconds for lcb_cntl).

10.0 seconds (or 10000000 microseconds)

tracing_orphaned_queue_size

LCB_CNTL_TRACING_ORPHANED_QUEUE_SIZE

The maximum number of items to keep in internal queue per service.

128

Customizing

You can customise Tracer settings through the connection string, or using lcb_cntl. Here is an example on how to customize our default tracer to reduce the time interval when the information gets logged:

lcb_uint32_t tmoval = 10000000; /* in microseconds, 10 seconds */
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL, &tmoval);


/* the same as above, but using string-encoded float value, representing seconds with fraction part */
lcb_cntl_string("tracing_threshold_queue_flush_interval", "10.0");


/* the same, but using connection string */
lcb_t instance;
struct lcb_create_st cropts = {0};
lcb_error_t rc;

cropts.version = 3;
cropts.v.v3.connstr = "couchbase://127.0.0.1/default?tracing_threshold_queue_flush_interval=10.0";
cropts.v.v3.username = "Administrator";
cropts.v.v3.passwd = "password";

rc = lcb_create(&instance, &cropts);
if (rc != LCB_SUCCESS) {
    die(rc, "Creating instance");
}

Follow along with our example of Tracing from the C SDK (libcouchbase) with Couchbase Server, to discover how to use tracing in the C SDK for Response Time Observability.