census.h File Reference

#include <grpc/grpc.h>

Go to the source code of this file.

Data Structures
struct	census_timestamp
	This structure represents a timestamp as used by census to record the time at which an operation begins. More...
struct	census_rpc_name_info
	Represent functions to map RPC name ID to service/method names. More...
struct	census_trace_record
	Trace record. More...
struct	census_tag_const
struct	census_value
struct	census_aggregation
	Information needed to instantiate a new aggregation. More...
struct	census_view_aggregation_data
	Holds all the aggregation data for a particular view instantiation. More...
struct	census_view_data
	Census view data as returned by census_view_get_data(). More...

Macros
#define	CENSUS_TRACE_RECORD_START_OP   ((gpr_uint32)0)
#define	CENSUS_TRACE_RECORD_END_OP   ((gpr_uint32)1)
#define	CENSUS_MAX_TAG_KEY_LENGTH   20
#define	CENSUS_MAX_TAG_VALUE_LENGTH   50

Typedefs
typedef struct census_context	census_context
	Context is a handle used by census to represent the current tracing and tagging information. More...
typedef struct census_tag_set	census_tag_set
typedef struct census_tag_set_iterator	census_tag_set_iterator
typedef struct census_aggregation_ops	census_aggregation_ops
	Type representing a particular aggregation. More...
typedef struct census_view	census_view
	A census view type. More...

Enumerations
enum	census_features {   CENSUS_FEATURE_NONE = 0, CENSUS_FEATURE_TRACING = 1, CENSUS_FEATURE_STATS = 2, CENSUS_FEATURE_CPU = 4,   CENSUS_FEATURE_ALL }
enum	census_trace_mask_values { CENSUS_TRACE_MASK_NONE = 0, CENSUS_TRACE_MASK_IS_SAMPLED = 1 }

Functions
int	census_initialize (int features)
	Shutdown and startup census subsystem. More...
void	census_shutdown (void)
int	census_supported (void)
	Return the features supported by the current census implementation (not all features will be available on all platforms). More...
int	census_enabled (void)
	Return the census features currently enabled. More...
size_t	census_context_serialize (const census_context *context, char *buffer, size_t buf_size)
int	census_trace_mask (const census_context *context)
	Get the current trace mask associated with this context. More...
void	census_set_trace_mask (int trace_mask)
	Set the trace mask associated with a context. More...
census_timestamp	census_start_rpc_op_timestamp (void)
	Mark the beginning of an RPC operation. More...
census_context *	census_start_client_rpc_op (const census_context *context, gpr_int64 rpc_name_id, const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask, const census_timestamp *start_time)
	Start a client rpc operation. More...
void	census_set_rpc_client_peer (census_context *context, const char *peer)
	Add peer information to a context representing a client RPC operation. More...
census_context *	census_start_server_rpc_op (const char *buffer, gpr_int64 rpc_name_id, const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask, census_timestamp *start_time)
	Start a server RPC operation. More...
census_context *	census_start_op (census_context *context, const char *family, const char *name, int trace_mask)
	Start a new, non-RPC operation. More...
void	census_end_op (census_context *context, int status)
	End an operation started by any of the census_start_*_op*() calls. More...
void	census_trace_print (census_context *context, gpr_uint32 type, const char *buffer, size_t n)
	Insert a trace record into the trace stream. More...
int	census_trace_scan_start (int consume)
	Start a scan of existing trace records. More...
int	census_get_trace_record (census_trace_record *trace_record)
	Get a trace record. More...
void	census_trace_scan_end ()
	End a scan previously started by census_trace_scan_start() More...
census_tag_set *	census_tag_set_create (size_t size_hint)
int	census_tag_set_add (census_tag_set *tags, const char *key, const char *value)
void	census_tag_set_destroy (census_tag_set *tags)
census_tag_set *	census_context_tag_set (census_context *context)
census_tag_set_iterator *	census_tag_set_open (census_tag_set *tags)
int	census_tag_set_next (census_tag_set_iterator *it, census_tag_const *tag)
void	census_tag_set_close (census_tag_set_iterator *it)
void	census_record_values (census_context *context, census_value *values, size_t nvalues)
census_view *	census_view_create (gpr_uint32 metric_id, const census_tag_set *tags, const census_aggregation *aggregations, size_t naggregations)
	Create a new view. More...
void	census_view_delete (census_view *view)
	Destroy a previously created view. More...
size_t	census_view_metric (const census_view *view)
	Metric ID associated with a view. More...
size_t	census_view_naggregations (const census_view *view)
	Number of aggregations associated with view. More...
const census_tag_set *	census_view_tags (const census_view *view)
	Get tags associated with view. More...
const census_aggregation *	census_view_aggregrations (const census_view *view)
	Get aggregation descriptors associated with a view. More...
const census_view_data *	census_view_get_data (const census_view *view)
	Get data from aggregations associated with a view. More...
void	census_view_reset (census_view *view)
	Reset all view data to zero for the specified view. More...

Variables
census_aggregation_ops	census_agg_sum
census_aggregation_ops	census_agg_distribution
census_aggregation_ops	census_agg_histogram
census_aggregation_ops	census_agg_window

Macro Definition Documentation

#define CENSUS_MAX_TAG_KEY_LENGTH   20

#define CENSUS_MAX_TAG_VALUE_LENGTH   50

#define CENSUS_TRACE_RECORD_END_OP   ((gpr_uint32)1)

#define CENSUS_TRACE_RECORD_START_OP   ((gpr_uint32)0)

Typedef Documentation

typedef struct census_aggregation_ops census_aggregation_ops

Type representing a particular aggregation.

typedef struct census_context census_context

Context is a handle used by census to represent the current tracing and tagging information.

Contexts should be propagated across RPC's. Contexts are created by any of the census_start_*_op() functions. A context is typically used as argument to most census functions. Conceptually, contexts should be thought of as specific to single RPC/thread. The context can be serialized for passing across the wire, via census_context_serialize().

typedef struct census_tag_set census_tag_set

typedef struct census_tag_set_iterator census_tag_set_iterator

typedef struct census_view census_view

A census view type.

Opaque.

Enumeration Type Documentation

enum census_features

Enumerator
CENSUS_FEATURE_NONE
CENSUS_FEATURE_TRACING
CENSUS_FEATURE_STATS
CENSUS_FEATURE_CPU
CENSUS_FEATURE_ALL

enum census_trace_mask_values

Enumerator
CENSUS_TRACE_MASK_NONE
CENSUS_TRACE_MASK_IS_SAMPLED

Function Documentation

size_t census_context_serialize	(	const census_context *	context,
		char *	buffer,
		size_t	buf_size
	)

census_tag_set* census_context_tag_set

(

census_context *

context

)

int census_enabled

(

void

)

Return the census features currently enabled.

void census_end_op	(	census_context *	context,
		int	status
	)

End an operation started by any of the census_start_*_op*() calls.

The context used in this call will no longer be valid once this function completes.

Parameters

context	Context associated with operation which is ending.
status	status associated with the operation. Not interpreted by census.

int census_get_trace_record

(

census_trace_record *

trace_record

)

Get a trace record.

The data pointed to by the trace buffer is guaranteed stable until the next census_get_trace_record() call (if the consume argument to census_trace_scan_start was non-zero) or census_trace_scan_end() is called (otherwise).

Parameters

trace_record

structure that will be filled in with oldest trace record.

Returns

-1 if an error occurred (e.g. no previous call to census_trace_scan_start()), 0 if there is no more trace data (and trace_record will not be modified) or 1 otherwise.

int census_initialize

(

int

features

)

Shutdown and startup census subsystem.

The 'features' argument should be the OR (|) of census_features values. If census fails to initialize, then census_initialize() will return a non-zero value. It is an error to call census_initialize() more than once (without an intervening census_shutdown()).

void census_record_values	(	census_context *	context,
		census_value *	values,
		size_t	nvalues
	)

void census_set_rpc_client_peer	(	census_context *	context,
		const char *	peer
	)

Add peer information to a context representing a client RPC operation.

void census_set_trace_mask

(

int

trace_mask

)

Set the trace mask associated with a context.

void census_shutdown

(

void

)

census_context* census_start_client_rpc_op	(	const census_context *	context,
		gpr_int64	rpc_name_id,
		const census_rpc_name_info *	rpc_name_info,
		const char *	peer,
		int	trace_mask,
		const census_timestamp *	start_time
	)

Start a client rpc operation.

This function should be called as early in the client RPC path as possible. This function will create a new context. If the context argument is non-null, then the new context will inherit all its properties, with the following changes:

• create a new operation ID for the new context, marking it as a child of the previous operation.
• use the new RPC path and peer information for tracing and stats collection purposes, rather than those from the original context

If the context argument is NULL, then a new root context is created. This is particularly important for tracing purposes (the trace spans generated will be unassociated with any other trace spans, except those downstream). The trace_mask will be used for tracing operations associated with the new context.

In some RPC systems (e.g. where load balancing is used), peer information may not be available at the time the operation starts. In this case, use a NULL value for peer, and set it later using the census_set_rpc_client_peer() function.

Parameters

context	The parent context. Can be NULL.
rpc_name_id	The rpc name identifier to be associated with this RPC.
rpc_name_info	Used to decode rpc_name_id.
peer	RPC peer. If not available at the time, NULL can be used, and a later census_set_rpc_client_peer() call made.
trace_mask	An OR of census_trace_mask_values values. Only used in the creation of a new root context (context == NULL).
start_time	A timestamp returned from census_start_rpc_op_timestamp(). Can be NULL. Used to set the true time the operation begins.

Returns

A new census context.

census_context* census_start_op	(	census_context *	context,
		const char *	family,
		const char *	name,
		int	trace_mask
	)

Start a new, non-RPC operation.

In general, this function works very similarly to census_start_client_rpc_op, with the primary difference being the replacement of host/path information with the more generic family/name tags. If the context argument is non-null, then the new context will inherit all its properties, with the following changes:

• create a new operation ID for the new context, marking it as a child of the previous operation.
• use the family and name information for tracing and stats collection purposes, rather than those from the original context

If the context argument is NULL, then a new root context is created. This is particularly important for tracing purposes (the trace spans generated will be unassociated with any other trace spans, except those downstream). The trace_mask will be used for tracing operations associated with the new context.

Parameters

context	The base context. Can be NULL.
family	Family name to associate with the trace
name	Name within family to associated with traces/stats
trace_mask	An OR of census_trace_mask_values values. Only used if context is NULL.

Returns

A new census context.

census_timestamp census_start_rpc_op_timestamp

(

void

)

Mark the beginning of an RPC operation.

The information required to call the functions to record the start of RPC operations (both client and server) may not be callable at the true start time of the operation, due to information not being available (e.g. the census context data will not be available in a server RPC until at least initial metadata has been processed). To ensure correct CPU accounting and latency recording, RPC systems can call this function to get the timestamp of operation beginning. This can later be used as an argument to census_start_{client,server}_rpc_op(). NB: for correct CPU accounting, the system must guarantee that the same thread is used for all request processing after this function is called.

Returns

A timestamp representing the operation start time.

census_context* census_start_server_rpc_op	(	const char *	buffer,
		gpr_int64	rpc_name_id,
		const census_rpc_name_info *	rpc_name_info,
		const char *	peer,
		int	trace_mask,
		census_timestamp *	start_time
	)

Start a server RPC operation.

Returns a new context to be used in future census calls. If buffer is non-NULL, then the buffer contents should represent the client context, as generated by census_context_serialize(). If buffer is NULL, a new root context is created.

Parameters

buffer	Buffer containing bytes output from census_context_serialize().
rpc_name_id	The rpc name identifier to be associated with this RPC.
rpc_name_info	Used to decode rpc_name_id.
peer	RPC peer.
trace_mask	An OR of census_trace_mask_values values. Only used in the creation of a new root context (buffer == NULL).
start_time	A timestamp returned from census_start_rpc_op_timestamp(). Can be NULL. Used to set the true time the operation begins.

Returns

A new census context.

int census_supported

(

void

)

Return the features supported by the current census implementation (not all features will be available on all platforms).

int census_tag_set_add	(	census_tag_set *	tags,
		const char *	key,
		const char *	value
	)

void census_tag_set_close

(

census_tag_set_iterator *

it

)

census_tag_set* census_tag_set_create

(

size_t

size_hint

)

void census_tag_set_destroy

(

census_tag_set *

tags

)

int census_tag_set_next	(	census_tag_set_iterator *	it,
		census_tag_const *	tag
	)

census_tag_set_iterator* census_tag_set_open

(

census_tag_set *

tags

)

int census_trace_mask

(

const census_context *

context

)

Get the current trace mask associated with this context.

The value returned will be the logical or of census_trace_mask_values values.

void census_trace_print	(	census_context *	context,
		gpr_uint32	type,
		const char *	buffer,
		size_t	n
	)

Insert a trace record into the trace stream.

The record consists of an arbitrary size buffer, the size of which is provided in 'n'.

Parameters

context	Trace context
type	User-defined type to associate with trace entry.
buffer	Pointer to buffer to use
n	Number of bytes in buffer

void census_trace_scan_end

(

)

End a scan previously started by census_trace_scan_start()

int census_trace_scan_start

(

int

consume

)

Start a scan of existing trace records.

While a scan is ongoing, addition of new trace records will be blocked if the underlying trace buffers fill up, so trace processing systems should endeavor to complete reading as soon as possible.

Parameters

consume

if non-zero, indicates that reading records also "consumes" the previously read record - i.e. releases space in the trace log while scanning is ongoing.

Returns

0 on success, non-zero on failure (e.g. if a scan is already ongoing)

const census_aggregation* census_view_aggregrations

(

const census_view *

view

)

Get aggregation descriptors associated with a view.

census_view* census_view_create	(	gpr_uint32	metric_id,
		const census_tag_set *	tags,
		const census_aggregation *	aggregations,
		size_t	naggregations
	)

Create a new view.

Parameters

metric_id	Metric with which this view is associated.
tags	tags that define the view
aggregations	aggregations to associate with the view
naggregations	number of aggregations

Returns

A new census view

void census_view_delete

(

census_view *

view

)

Destroy a previously created view.

const census_view_data* census_view_get_data

(

const census_view *

view

)

Get data from aggregations associated with a view.

Parameters

view	View from which to get data.

Returns

Full set of data for all aggregations for the view.

size_t census_view_metric

(

const census_view *

view

)

Metric ID associated with a view.

size_t census_view_naggregations

(

const census_view *

view

)

Number of aggregations associated with view.

void census_view_reset

(

census_view *

view

)

Reset all view data to zero for the specified view.

const census_tag_set* census_view_tags

(

const census_view *

view

)

Get tags associated with view.

Variable Documentation

census_aggregation_ops census_agg_distribution

census_aggregation_ops census_agg_histogram

census_aggregation_ops census_agg_sum

census_aggregation_ops census_agg_window