Detailed Description

End to end tracing.

Tracing operations through SDK and the Cluster.

Functions
lcb_STATUS	lcb_cmdanalytics_parent_span (lcb_CMDANALYTICS cmd, lcbtrace_SPAN span)
	Associate parent tracing span with the Analytics request. More...

lcb_STATUS	lcb_cmdsearch_parent_span (lcb_CMDSEARCH cmd, lcbtrace_SPAN span)
	Associate parent tracing span with the FTS request. More...

lcb_STATUS	lcb_cmdquery_parent_span (lcb_CMDQUERY cmd, lcbtrace_SPAN span)
	Associate parent tracing span with the N1QL request. More...

lcbtrace_TRACER *	lcb_get_tracer (lcb_INSTANCE *instance)
	Get current tracer of the connection. More...

void	lcb_set_tracer (lcb_INSTANCE instance, lcbtrace_TRACER tracer)
	Set current tracer for the connection. More...

lcbtrace_TRACER *	lcbtrace_new (lcb_INSTANCE *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_STATUS	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_STATUS	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_STATUS	lcbtrace_span_get_tag_double (lcbtrace_SPAN span, const char name, double *value)
	Get value of the double tag of the span. More...

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

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_INSERT

#define	LCBTRACE_OP_INSERT

#define	LCBTRACE_OP_APPEND

#define	LCBTRACE_OP_COUNTER

#define	LCBTRACE_OP_GET

#define	LCBTRACE_OP_GET_FROM_REPLICA

#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_EXISTS

#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_cmdanalytics_parent_span()

lcb_STATUS lcb_cmdanalytics_parent_span	(	lcb_CMDANALYTICS *	cmd,
		lcbtrace_SPAN *	span
	)

Associate parent tracing span with the Analytics request.

Parameters

cmd	the command
span	parent span

Attach parent tracing span to request object.: lcb_CMDANALYTICS* cmd;

lcb_cmdanalytics_create(&cmd);

lcb_analytics_parentspan(instance, span);

lcb_error_t err = lcb_analytics_query(instance, cookie, cmd);

◆ lcb_cmdsearch_parent_span()

lcb_STATUS lcb_cmdsearch_parent_span	(	lcb_CMDSEARCH *	cmd,
		lcbtrace_SPAN *	span
	)

Associate parent tracing span with the FTS request.

Parameters

cmd	the command
span	parent span

Attach parent tracing span to request object.: lcb_CMDSEARCH cmd;

lcb_cmdsearch_create(&cmd);

// create a search query...

lcb_error_t err = lcb_search(instance, cookie, cmd);

if (err == LCB_SUCCESS) {

lcb_cmdsearch_parent_span(instance, span);

}

◆ lcb_cmdquery_parent_span()

lcb_STATUS lcb_cmdquery_parent_span	(	lcb_CMDQUERY *	cmd,
		lcbtrace_SPAN *	span
	)

Associate parent tracing span with the N1QL request.

Parameters

cmd	the command
span	parent span

Attach parent tracing span to request object.: lcb_CMDQUERY* cmd;

lcb_cmdquery_create(&cmd);

lcb_error_t err = lcb_query(instance, cookie, cmd);

if (err == LCB_SUCCESS) {

lcb_cmdquery_parent_span(cmd, span);

}

◆ lcb_get_tracer()

lcbtrace_TRACER* lcb_get_tracer ( lcb_INSTANCE * instance )

Get current tracer of the connection.

Parameters

instance current connection

Returns: tracer

Stability

Committed:

◆ lcb_set_tracer()

void lcb_set_tracer	(	lcb_INSTANCE *	instance,
		lcbtrace_TRACER *	tracer
	)

Set current tracer for the connection.

Parameters

instance	current connection
tracer	tracer instance

Stability

Committed:

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

◆ lcbtrace_new()

lcbtrace_TRACER* lcbtrace_new	(	lcb_INSTANCE *	instance,
		lcb_U64	flags
	)

Create default libcouchbase tracer instance.

Parameters

instance	current connection
flags	pass 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

tracer	tracer instance
operation	the operation code
now	start timestamp or LCBTRACE_NOW to let the library to record current time from the wall clock.
ref	reference 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

span	span instance
now	finish 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

span	span 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

span	span 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

span	span 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

span	span 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

span	span 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

span	span 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

span	span instance

Returns: parent span or NULL

Stability

Committed:

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

◆ lcbtrace_span_get_tag_str()

lcb_STATUS 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

span	span instance
name	name of the tag
value	pointer to result string
nvalue	pointer 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_STATUS lcbtrace_span_get_tag_uint64	(	lcbtrace_SPAN *	span,
		const char *	name,
		lcb_U64 *	value
	)

Get value of the integer tag of the span.

Parameters

span	span instance
name	name of the tag
value	pointer 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_STATUS lcbtrace_span_get_tag_double	(	lcbtrace_SPAN *	span,
		const char *	name,
		double *	value
	)

Get value of the double tag of the span.

Parameters

span	span instance
name	name of the tag
value	pointer to result

Returns: LCB_SUCCESS if value exists and was written to result pointer

Stability

Committed:

◆ lcbtrace_span_get_tag_bool()

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

Get value of the boolean tag of the span.

Parameters

span	span instance
name	name of the tag
value	pointer 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

span	span instance
name	name of the tag
value	value 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

span	span instance
name	name of the tag
value	value 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

span	span instance
name	name of the tag
value	value 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

span	span instance
name	name of the tag
value	value of the tag. 0 if false, otherwise – true.

Stability

Committed:

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

cmd	the command structure
ctx	the lcbtrace_SPAN pointer

Stability

Committed:

Detailed Description

Functions

Macros

Typedefs

Enumerations

Function Documentation

◆ lcb_cmdanalytics_parent_span()

◆ lcb_cmdsearch_parent_span()

◆ lcb_cmdquery_parent_span()

◆ lcb_get_tracer()

◆ lcb_set_tracer()

◆ lcbtrace_new()

◆ lcbtrace_destroy()

◆ lcbtrace_now()

◆ lcbtrace_span_start()

◆ lcbtrace_span_finish()

◆ lcbtrace_span_get_start_ts()

◆ lcbtrace_span_get_finish_ts()

◆ lcbtrace_span_is_orphaned()

◆ lcbtrace_span_get_operation()

◆ lcbtrace_span_get_span_id()

◆ lcbtrace_span_get_trace_id()

◆ lcbtrace_span_get_parent()

◆ lcbtrace_span_get_tag_str()

◆ lcbtrace_span_get_tag_uint64()

◆ lcbtrace_span_get_tag_double()

◆ lcbtrace_span_get_tag_bool()

◆ lcbtrace_span_add_tag_str()

◆ lcbtrace_span_add_tag_uint64()

◆ lcbtrace_span_add_tag_double()

◆ lcbtrace_span_add_tag_bool()

Data Structure Documentation

◆ lcbtrace_TRACER

Data Fields

Field Documentation

◆ cookie

◆ ldcptrace_REPORTER

Data Fields

Macro Definition Documentation

◆ LCBTRACE_TAG_PEER_LATENCY

◆ LCB_CMD_SET_TRACESPAN