Couchbase C Client  2.9.4
Asynchronous C Client for Couchbase
End to end tracing

Detailed Description

Tracing operations through SDK and the Cluster.

Functions

void lcb_fts_set_parent_span (lcb_t instance, lcb_FTSHANDLE handle, lcbtrace_SPAN *span)
 
Associate parent tracing span with the FTS request. More...
 
void lcb_n1ql_set_parent_span (lcb_t instance, lcb_N1QLHANDLE handle, lcbtrace_SPAN *span)
 
Associate parent tracing span with the N1QL request. More...
 
lcbtrace_TRACERlcb_get_tracer (lcb_t instance)
 
Get current tracer of the connection. More...
 
void lcb_set_tracer (lcb_t instance, lcbtrace_TRACER *tracer)
 
Set current tracer for the connection. More...
 
lcbtrace_TRACERlcbtrace_new (lcb_t instance, lcb_U64 flags)
 
Create default libcouchbase tracer instance. More...
 
void lcbtrace_destroy (lcbtrace_TRACER *tracer)
 
Destroy tracer object. More...
 
lcb_U64 lcbtrace_now (void)
 
Get current timestamp. More...
 
lcbtrace_SPAN * lcbtrace_span_start (lcbtrace_TRACER *tracer, const char *operation, lcb_U64 now, lcbtrace_REF *ref)
 
Start span. More...
 
void lcbtrace_span_finish (lcbtrace_SPAN *span, lcb_U64 now)
 
Mark the span as finished. More...
 
lcb_U64 lcbtrace_span_get_start_ts (lcbtrace_SPAN *span)
 
Get start timestamp of the span. More...
 
lcb_U64 lcbtrace_span_get_finish_ts (lcbtrace_SPAN *span)
 
Get finish timestamp of the span. More...
 
int lcbtrace_span_is_orphaned (lcbtrace_SPAN *span)
 
Check if the span is orphaned. More...
 
const char * lcbtrace_span_get_operation (lcbtrace_SPAN *span)
 
Get operation code of the span. More...
 
lcb_U64 lcbtrace_span_get_span_id (lcbtrace_SPAN *span)
 
Get ID of the span. More...
 
lcb_U64 lcbtrace_span_get_trace_id (lcbtrace_SPAN *span)
 
Get trace ID of the span. More...
 
lcbtrace_SPAN * lcbtrace_span_get_parent (lcbtrace_SPAN *span)
 
Get parent span of the span. More...
 
lcb_error_t lcbtrace_span_get_tag_str (lcbtrace_SPAN *span, const char *name, char **value, size_t *nvalue)
 
Get value of the string tag of the span. More...
 
lcb_error_t lcbtrace_span_get_tag_uint64 (lcbtrace_SPAN *span, const char *name, lcb_U64 *value)
 
Get value of the integer tag of the span. More...
 
lcb_error_t lcbtrace_span_get_tag_double (lcbtrace_SPAN *span, const char *name, double *value)
 
Get value of the double tag of the span. More...
 
lcb_error_t lcbtrace_span_get_tag_bool (lcbtrace_SPAN *span, const char *name, int *value)
 
Get value of the boolean tag of the span. More...
 
void lcbtrace_span_add_tag_str (lcbtrace_SPAN *span, const char *name, const char *value)
 
Add string tag to span. More...
 
void lcbtrace_span_add_tag_uint64 (lcbtrace_SPAN *span, const char *name, lcb_U64 value)
 
Add integer tag to span. More...
 
void lcbtrace_span_add_tag_double (lcbtrace_SPAN *span, const char *name, double value)
 
Add double tag to span. More...
 
void lcbtrace_span_add_tag_bool (lcbtrace_SPAN *span, const char *name, int value)
 
Add boolean tag to span. More...
 
void lcb_view_set_parent_span (lcb_t instance, lcb_VIEWHANDLE handle, lcbtrace_SPAN *span)
 
Associate parent tracing span with the View request. More...
 

Macros

#define LCBTRACE_F_THRESHOLD
 Flag for lcbtrace_new to request threshold logging tracer.
 
#define LCBTRACE_NOW
 zero means the library will trigger timestamp automatically
 
#define LCBTRACE_OP_REQUEST_ENCODING
 
#define LCBTRACE_OP_DISPATCH_TO_SERVER
 
#define LCBTRACE_OP_RESPONSE_DECODING
 
#define LCBTRACE_OP_ADD
 
#define LCBTRACE_OP_APPEND
 
#define LCBTRACE_OP_COUNTER
 
#define LCBTRACE_OP_GET
 
#define LCBTRACE_OP_GET_FROM_REPLICA
 
#define LCBTRACE_OP_INSERT
 
#define LCBTRACE_OP_OBSERVE_CAS
 
#define LCBTRACE_OP_OBSERVE_CAS_ROUND
 
#define LCBTRACE_OP_OBSERVE_SEQNO
 
#define LCBTRACE_OP_PREPEND
 
#define LCBTRACE_OP_REMOVE
 
#define LCBTRACE_OP_REPLACE
 
#define LCBTRACE_OP_TOUCH
 
#define LCBTRACE_OP_UNLOCK
 
#define LCBTRACE_OP_UPSERT
 
#define LCBTRACE_OP_UPSERT
 
#define LCBTRACE_OP_STORE2NAME(code)
 
#define LCBTRACE_TAG_DB_TYPE
 
#define LCBTRACE_TAG_SPAN_KIND
 
#define LCBTRACE_TAG_DB_INSTANCE
 Bucket name.
 
#define LCBTRACE_TAG_COMPONENT
 The client's identifier string (the 'u' property in the updated HELLO request), the same one that is shared with the server to identify the SDK.
 
#define LCBTRACE_TAG_OPERATION_ID
 The unique ID of the operation.
 
#define LCBTRACE_TAG_SERVICE
 The service type, one of the following: kv, view, n1ql, search, analytics.
 
#define LCBTRACE_TAG_SERVICE_KV
 
#define LCBTRACE_TAG_SERVICE_VIEW
 
#define LCBTRACE_TAG_SERVICE_N1QL
 
#define LCBTRACE_TAG_SERVICE_SEARCH
 
#define LCBTRACE_TAG_SERVICE_ANALYTICS
 
#define LCBTRACE_TAG_LOCAL_ID
 
#define LCBTRACE_TAG_LOCAL_ADDRESS
 The local socket hostname / IP and port, in the format: {hostname}:{port} To be added to dispatch spans when the local socket is available.
 
#define LCBTRACE_TAG_PEER_ADDRESS
 The remote socket hostname / IP and port, in the format: {hostname}:{port} To be added to dispatch spans when the local socket is available.
 
#define LCBTRACE_TAG_PEER_LATENCY
 The server duration with precision suffix. More...
 
#define LCB_CMD_SET_TRACESPAN(cmd, span)
 
Sets the tracing context for the command. More...
 

Typedefs

typedef struct lcbtrace_SPAN_Cdummy lcbtrace_SPAN
 

Enumerations

enum  lcbtrace_REF_TYPE
 

Function Documentation

◆ lcb_fts_set_parent_span()

void lcb_fts_set_parent_span ( lcb_t  instance,
lcb_FTSHANDLE  handle,
lcbtrace_SPAN *  span 
)


Associate parent tracing span with the FTS request.

Parameters
instancethe instance
handleFTS request handle
spanparent span
Attach parent tracing span to request object.
lcb_CMDFTS cmd = {};
// initialize FTS command...
lcb_FTSHANDLE handle = NULL;
cmd->handle = &handle;
lcb_error_t err = lcb_fts_query(instance, cookie, cmd);
if (err == LCB_SUCCESS) {
lcb_fts_set_parent_span(instance, handle, span);
}
Stability
Committed:

◆ lcb_n1ql_set_parent_span()

void lcb_n1ql_set_parent_span ( lcb_t  instance,
lcb_N1QLHANDLE  handle,
lcbtrace_SPAN *  span 
)


Associate parent tracing span with the N1QL request.

Parameters
instancethe instance
handleN1QL request handle
spanparent span
Attach parent tracing span to request object.
lcb_CMDN1QL cmd = {};
// initialize N1QL command...
lcb_N1QLHANDLE handle = NULL;
cmd->handle = &handle;
lcb_error_t err = lcb_fts_query(instance, cookie, cmd);
if (err == LCB_SUCCESS) {
lcb_n1ql_set_parent_span(instance, handle, span);
}
Stability
Committed:

◆ lcb_get_tracer()

lcbtrace_TRACER* lcb_get_tracer ( lcb_t  instance)


Get current tracer of the connection.

Parameters
instancecurrent connection
Returns
tracer
Stability
Committed:

◆ lcb_set_tracer()

void lcb_set_tracer ( lcb_t  instance,
lcbtrace_TRACER tracer 
)


Set current tracer for the connection.

Parameters
instancecurrent connection
tracertracer instance
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_new()

lcbtrace_TRACER* lcbtrace_new ( lcb_t  instance,
lcb_U64  flags 
)


Create default libcouchbase tracer instance.

Parameters
instancecurrent connection
flagspass LCBTRACE_F_THRESHOLD if needed threshold logging tracer.
Returns
new tracer or NULL when nothing has been created.
Stability
Committed:

◆ lcbtrace_destroy()

void lcbtrace_destroy ( lcbtrace_TRACER tracer)


Destroy tracer object.

Stability
Committed:

◆ lcbtrace_now()

lcb_U64 lcbtrace_now ( void  )


Get current timestamp.

Returns
current wall clock time in microseconds
Stability
Committed:

◆ lcbtrace_span_start()

lcbtrace_SPAN* lcbtrace_span_start ( lcbtrace_TRACER tracer,
const char *  operation,
lcb_U64  now,
lcbtrace_REF *  ref 
)


Start span.

Parameters
tracertracer instance
operationthe operation code
nowstart timestamp or LCBTRACE_NOW to let the library to record current time from the wall clock.
refreference to the other span, or NULL
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_finish()

void lcbtrace_span_finish ( lcbtrace_SPAN *  span,
lcb_U64  now 
)


Mark the span as finished.

Parameters
spanspan instance
nowfinish timestamp or LCBTRACE_NOW to let the library to record current time from the wall clock.
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_start_ts()

lcb_U64 lcbtrace_span_get_start_ts ( lcbtrace_SPAN *  span)


Get start timestamp of the span.

Parameters
spanspan instance
Returns
timestamp in microseconds when the span has been started.
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_finish_ts()

lcb_U64 lcbtrace_span_get_finish_ts ( lcbtrace_SPAN *  span)


Get finish timestamp of the span.

Parameters
spanspan instance
Returns
timestamp in microseconds when the span has been finished.
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_is_orphaned()

int lcbtrace_span_is_orphaned ( lcbtrace_SPAN *  span)


Check if the span is orphaned.

Spans might be marked as orphaned, when the library has discarded request structure without waiting for server response (e.g. on timeout).

Parameters
spanspan instance
Returns
non-zero if span is orphaned.
Stability
Committed:

◆ lcbtrace_span_get_operation()

const char* lcbtrace_span_get_operation ( lcbtrace_SPAN *  span)


Get operation code of the span.

Parameters
spanspan instance
Returns
operation code
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_span_id()

lcb_U64 lcbtrace_span_get_span_id ( lcbtrace_SPAN *  span)


Get ID of the span.

Parameters
spanspan instance
Returns
span ID
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_trace_id()

lcb_U64 lcbtrace_span_get_trace_id ( lcbtrace_SPAN *  span)


Get trace ID of the span.

Parameters
spanspan instance
Returns
trace ID
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_parent()

lcbtrace_SPAN* lcbtrace_span_get_parent ( lcbtrace_SPAN *  span)


Get parent span of the span.

Parameters
spanspan instance
Returns
parent span or NULL
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_tag_str()

lcb_error_t lcbtrace_span_get_tag_str ( lcbtrace_SPAN *  span,
const char *  name,
char **  value,
size_t *  nvalue 
)


Get value of the string tag of the span.

Parameters
spanspan instance
namename of the tag
valuepointer to result string
nvaluepointer to length of the result string
Returns
LCB_SUCCESS if value exists and was written to result pointer
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_tag_uint64()

lcb_error_t lcbtrace_span_get_tag_uint64 ( lcbtrace_SPAN *  span,
const char *  name,
lcb_U64 *  value 
)


Get value of the integer tag of the span.

Parameters
spanspan instance
namename of the tag
valuepointer to result
Returns
LCB_SUCCESS if value exists and was written to result pointer
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_get_tag_double()

lcb_error_t lcbtrace_span_get_tag_double ( lcbtrace_SPAN *  span,
const char *  name,
double *  value 
)


Get value of the double tag of the span.

Parameters
spanspan instance
namename of the tag
valuepointer to result
Returns
LCB_SUCCESS if value exists and was written to result pointer
Stability
Committed:

◆ lcbtrace_span_get_tag_bool()

lcb_error_t lcbtrace_span_get_tag_bool ( lcbtrace_SPAN *  span,
const char *  name,
int *  value 
)


Get value of the boolean tag of the span.

Parameters
spanspan instance
namename of the tag
valuepointer to result
Returns
LCB_SUCCESS if value exists and was written to result pointer
Stability
Committed:

◆ lcbtrace_span_add_tag_str()

void lcbtrace_span_add_tag_str ( lcbtrace_SPAN *  span,
const char *  name,
const char *  value 
)


Add string tag to span.

Parameters
spanspan instance
namename of the tag
valuevalue of the tag (NUL-terminated)
Stability
Committed:
Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ lcbtrace_span_add_tag_uint64()

void lcbtrace_span_add_tag_uint64 ( lcbtrace_SPAN *  span,
const char *  name,
lcb_U64  value 
)


Add integer tag to span.

Parameters
spanspan instance
namename of the tag
valuevalue of the tag
Stability
Committed:

◆ lcbtrace_span_add_tag_double()

void lcbtrace_span_add_tag_double ( lcbtrace_SPAN *  span,
const char *  name,
double  value 
)


Add double tag to span.

Parameters
spanspan instance
namename of the tag
valuevalue of the tag
Stability
Committed:

◆ lcbtrace_span_add_tag_bool()

void lcbtrace_span_add_tag_bool ( lcbtrace_SPAN *  span,
const char *  name,
int  value 
)


Add boolean tag to span.

Parameters
spanspan instance
namename of the tag
valuevalue of the tag. 0 if false, otherwise – true.
Stability
Committed:

◆ lcb_view_set_parent_span()

void lcb_view_set_parent_span ( lcb_t  instance,
lcb_VIEWHANDLE  handle,
lcbtrace_SPAN *  span 
)


Associate parent tracing span with the View request.

Parameters
instancethe instance
handleView request handle
spanparent span
Attach parent tracing span to view request object.
lcb_CMDVIEWQUERY vcmd = {0};
char *doc_name = "beer";
char *view_name = "by_location";
char *options = "reduce=false&limit=3";
vcmd.callback = view_callback;
vcmd.ddoc = doc_name;
vcmd.nddoc = strlen(doc_name);
vcmd.view = view_name;
vcmd.nview = strlen(view_name);
vcmd.optstr = options;
vcmd.noptstr = strlen(options);
vcmd.handle = &handle;
err = lcb_view_query(instance, NULL, &vcmd);
if (err != LCB_SUCCESS) {
die(instance, "Couldn't schedule view operation", err);
}
lcb_view_set_parent_span(instance, handle, span);
See also
example/tracing/views.c
Stability
Committed:
Examples:
example/tracing/views.c.

Data Structure Documentation

◆ lcbtrace_TRACER

struct lcbtrace_TRACER

Tracer interface.

Examples:
example/tracing/tracing.c, and example/tracing/views.c.

Data Fields

lcb_U16 version
 version of the structure, current value is 0
 
lcb_U64 flags
 tracer-specific flags
 
void * cookie
 opaque pointer (e.g. More...
 
void(* destructor )(struct lcbtrace_TRACER *tracer)
 destructor function or NULL, if it is not necessary
 
union {
   struct {
void(* report )(struct lcbtrace_TRACER *tracer, lcbtrace_SPAN *span)
 optional reporter function
 
   } v0
 
v
 

Field Documentation

◆ cookie

void* cookie

opaque pointer (e.g.

pointer to wrapper structure)

Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ ldcptrace_REPORTER

struct ldcptrace_REPORTER


Stability
Uncommitted:

Data Fields

void * state
 
void(* report )(void *state, lcbtrace_SPAN *span)
 

Macro Definition Documentation

◆ LCBTRACE_TAG_PEER_LATENCY

#define LCBTRACE_TAG_PEER_LATENCY

The server duration with precision suffix.

The suffix is required to indicate precision because KV is recorded in microseconds and N1QL query metrics use milliseconds. For example: 123us, 32.12ms

Examples:
example/tracing/tracing.c, and example/tracing/views.c.

◆ LCB_CMD_SET_TRACESPAN

#define LCB_CMD_SET_TRACESPAN (   cmd,
  span 
)


Sets the tracing context for the command.

Parameters
cmdthe command structure
ctxthe lcbtrace_SPAN pointer
Stability
Committed:
Examples:
example/tracing/tracing.c.