End to end tracing

Detailed Description

End to end tracing.

Tracing operations through SDK and the Cluster.

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_wrap()

lcb_STATUS lcbtrace_span_wrap	(	lcbtrace_TRACER *	tracer,
		const char *	opname,
		uint64_t	start,
		void *	external_span,
		lcbtrace_SPAN **	lcbspan )

Wrap external span.

If using a custom tracer which has its own span representation, you can create an lcbtrace_SPAN that wraps it. This is useful when setting parent spans.

Parameters

tracer	tracer instance.
operation	operation code.
start	timestamp from the external_span.
external_span	pointer to the external span.
lcbspan	pointer to a new lcbtrace_SPAN* which wraps external_span.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

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_set_service()

lcb_STATUS lcbtrace_span_set_service	(	lcbtrace_SPAN *	span,
		lcbtrace_SERVICE	svc )

Set the service for the span.

Threshold logging uses this to determine which threshold to apply when deciding whether or not a span has taken too long and should be logged. This only applies to outer spans. See lcbtrace_span_set_is_outer for setting that.

Parameters

span	the span to set the service on.
svc	the desired service.

Returns

LCB_SUCCESS when successful

Stability

Volatile

lcbtrace_span_get_service()

lcb_STATUS lcbtrace_span_get_service	(	lcbtrace_SPAN *	span,
		lcbtrace_SERVICE *	svc )

Get the service for the span.

Threshold logging uses this to determine which threshold to apply when deciding whether or not a span has taken too long and should be logged. This only applies to outer spans. See lcbtrace_span_set_is_outer for setting that.

Parameters

span	the span.
svc	points to the the span's service, or to LCB_SERVICE__MAX if one is not set.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

lcbtrace_span_get_is_outer()

lcb_STATUS lcbtrace_span_get_is_outer	(	lcbtrace_SPAN *	span,
		int *	outer )

Get outer flag on span.

See lcbtrace-span_get_is_outer for description of flag.

Parameters

span	span instance
outer	pointer to the value of the flag.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

lcbtrace_span_set_is_outer()

lcb_STATUS lcbtrace_span_set_is_outer	(	lcbtrace_SPAN *	span,
		int	outer )

Set outer flag on span.

When libcouchbase is passed a parent span with this flag set, it will use it as its outer span for the operation, adding the appropriate tags. However, it will not finish the span when calling the callback, like it does when it creates its own outer span. The finish is up to the caller, perhaps allowing for extra spans accounting for the processing within the callback, or elsewhere.

Parameters

span	the span to modify.
outer	when set, span is considered an outer span, whose finish time will be managed by the caller.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

lcbtrace_span_get_is_encoding()

lcb_STATUS lcbtrace_span_get_is_encoding	(	lcbtrace_SPAN *	span,
		int *	encoding )

Get encoding flag on span.

See lcbtrace-span_get_is_encoding for description of flag.

Parameters

span	span instance
encoding	pointer to the value of the flag.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

lcbtrace_span_set_is_encode()

lcb_STATUS lcbtrace_span_set_is_encode	(	lcbtrace_SPAN *	span,
		int	encode )

Set encoding flag on span.

When libcouchbase sees an encoding span has finished, it propogates the duration up to the outer span. This is output by the threshold logging tracer.

Parameters

span	the span to modify.
encode	when set, span is considered an encode span, whose duration will be output by the threshold logging tracer.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

lcbtrace_span_get_is_dispatch()

lcb_STATUS lcbtrace_span_get_is_dispatch	(	lcbtrace_SPAN *	span,
		int *	dispatch )

Get dispatch flag on span.

See lcbtrace-span_get_is_dispatch for description of flag.

Parameters

span	span instance
dispatch	pointer to the value of the flag.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

lcbtrace_span_set_is_dispatch()

lcb_STATUS lcbtrace_span_set_is_dispatch	(	lcbtrace_SPAN *	span,
		int	dispatch )

Set dispatch flag on span.

When a span is marked as being a dispatch span, libcouchbase will copy the tags into the parent span as well. This is used internally, for threshold and orphan logging. If an external external tracer is being used, where the callbacks in the lcbtrace_TRACER is using the v1 callbacks, this copying of the tags will not be done.

Parameters

span	the span to modify.
dispatch	when set, span is considered a dispatch span.

Returns

LCB_SUCCESS when successful.

Stability

Volatile

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. pointer to wrapper structure)
void(*)(struct lcbtrace_TRACER *tracer)	destructor	destructor function or NULL, if it is not necessary
union lcbtrace_TRACER.v	v

ldcptrace_REPORTER

struct ldcptrace_REPORTER

Stability

Uncommitted

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

Macro Definition Documentation

LCBTRACE_TAG_LOCAL_ID

#define LCBTRACE_TAG_LOCAL_ID

Connection id used when creating a connection against the cluster.

Note this is only used in KV spans.

LCBTRACE_TAG_LOCAL_ADDRESS

#define LCBTRACE_TAG_LOCAL_ADDRESS

The local socket ip address.

To be added to dispatch spans when the local socket is available.

Examples

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

LCBTRACE_TAG_LOCAL_PORT

#define LCBTRACE_TAG_LOCAL_PORT

The local socket port.

To be added to dispatch spans when the local socket is available.

LCBTRACE_TAG_PEER_ADDRESS

#define LCBTRACE_TAG_PEER_ADDRESS

The remote socket ip address.

To be added to dispatch spans when the local socket is available.

Examples

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

LCBTRACE_TAG_PEER_PORT

#define LCBTRACE_TAG_PEER_PORT

The remote socket port.

To be added to dispatch spans when the local socket is available.

LCBTRACE_TAG_STATEMENT

#define LCBTRACE_TAG_STATEMENT

The statement used in this span, when applicable.

This is set for Query and Analytics.

LCBTRACE_TAG_OPERATION

#define LCBTRACE_TAG_OPERATION

The operation for the span.

Set unless the db.statement key has been set.

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

Enumeration Type Documentation

lcbtrace_SERVICE

enum lcbtrace_SERVICE

Service the span is associated with.

Used in threshold logging tracer