#include <grpc/grpc.h>

Data Structures
struct	census_tag

struct	census_context_status

struct	census_context_iterator

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_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_MAX_TAG_KV_LEN 255

#define	CENSUS_MAX_PROPAGATED_TAGS 255

#define	CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */

#define	CENSUS_TAG_STATS 2 /* Tag will be used for statistics aggregation */

#define	CENSUS_TAG_RESERVED 4 /* Reserved for internal use. */

#define	CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE)

#define	CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS)

#define	CENSUS_TRACE_RECORD_START_OP ((uint32_t)0)

#define	CENSUS_TRACE_RECORD_END_OP ((uint32_t)1)

Typedefs
typedef struct census_context	census_context
	A Census Context is a handle used by Census to represent the current tracing and stats collection information. More...

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
CENSUSAPI int	census_initialize (int features)
	Shutdown and startup census subsystem. More...

CENSUSAPI void	census_shutdown (void)

CENSUSAPI int	census_supported (void)
	Return the features supported by the current census implementation (not all features will be available on all platforms). More...

CENSUSAPI int	census_enabled (void)
	Return the census features currently enabled. More...

CENSUSAPI census_context *	census_context_create (const census_context base, const census_tag tags, int ntags, census_context_status const **status)

CENSUSAPI void	census_context_destroy (census_context *context)

CENSUSAPI const census_context_status *	census_context_get_status (const census_context *context)

CENSUSAPI void	census_context_initialize_iterator (const census_context context, census_context_iterator iterator)

CENSUSAPI int	census_context_next_tag (census_context_iterator iterator, census_tag tag)

CENSUSAPI int	census_context_get_tag (const census_context context, const char key, census_tag *tag)

CENSUSAPI size_t	census_context_encode (const census_context context, char buffer, size_t buf_size)

CENSUSAPI census_context *	census_context_decode (const char *buffer, size_t size)

CENSUSAPI int	census_trace_mask (const census_context *context)
	Get the current trace mask associated with this context. More...

CENSUSAPI void	census_set_trace_mask (int trace_mask)
	Set the trace mask associated with a context. More...

CENSUSAPI census_timestamp	census_start_rpc_op_timestamp (void)
	Mark the beginning of an RPC operation. More...

CENSUSAPI census_context *	census_start_client_rpc_op (const census_context context, int64_t 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...

CENSUSAPI void	census_set_rpc_client_peer (census_context context, const char peer)
	Add peer information to a context representing a client RPC operation. More...

CENSUSAPI census_context *	census_start_server_rpc_op (const char buffer, int64_t 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...

CENSUSAPI census_context *	census_start_op (census_context context, const char family, const char *name, int trace_mask)
	Start a new, non-RPC operation. More...

CENSUSAPI void	census_end_op (census_context *context, int status)
	End an operation started by any of the census_start__op() calls. More...

CENSUSAPI void	census_trace_print (census_context context, uint32_t type, const char buffer, size_t n)
	Insert a trace record into the trace stream. More...

CENSUSAPI int	census_trace_scan_start (int consume)
	Start a scan of existing trace records. More...

CENSUSAPI int	census_get_trace_record (census_trace_record *trace_record)
	Get a trace record. More...

CENSUSAPI void	census_trace_scan_end ()
	End a scan previously started by census_trace_scan_start() More...

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

CENSUSAPI census_view *	census_view_create (uint32_t metric_id, const census_context tags, const census_aggregation aggregations, size_t naggregations)
	Create a new view. More...

CENSUSAPI void	census_view_delete (census_view *view)
	Destroy a previously created view. More...

CENSUSAPI size_t	census_view_metric (const census_view *view)
	Metric ID associated with a view. More...

CENSUSAPI size_t	census_view_naggregations (const census_view *view)
	Number of aggregations associated with view. More...

CENSUSAPI const census_context *	census_view_tags (const census_view *view)
	Get tags associated with view. More...

CENSUSAPI const census_aggregation *	census_view_aggregrations (const census_view *view)
	Get aggregation descriptors associated with a view. More...

CENSUSAPI const census_view_data *	census_view_get_data (const census_view *view)
	Get data from aggregations associated with a view. More...

CENSUSAPI 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_PROPAGATED_TAGS 255

#define CENSUS_MAX_TAG_KV_LEN 255

#define CENSUS_TAG_IS_PROPAGATED ( flags ) (flags & CENSUS_TAG_PROPAGATE)

#define CENSUS_TAG_IS_STATS ( flags ) (flags & CENSUS_TAG_STATS)

#define CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */

#define CENSUS_TAG_RESERVED 4 /* Reserved for internal use. */

#define CENSUS_TAG_STATS 2 /* Tag will be used for statistics aggregation */

#define CENSUS_TRACE_RECORD_END_OP ((uint32_t)1)

#define CENSUS_TRACE_RECORD_START_OP ((uint32_t)0)

Typedef Documentation

typedef struct census_aggregation_ops census_aggregation_ops

Type representing a particular aggregation.

typedef struct census_context census_context

A Census Context is a handle used by Census to represent the current tracing and stats collection information.

Contexts should be propagated across RPC's (this is the responsibility of the local RPC system). A context is typically used as the first argument to most census functions. Conceptually, they should be thought of as specific to a single RPC/thread. The user visible context representation is that of a collection of key:value string pairs, each of which is termed a 'tag'; these form the basis against which Census metrics will be recorded. Keys are unique within a context.

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

CENSUSAPI census_context* census_context_create	(	const census_context *	base,
		const census_tag *	tags,
		int	ntags,
		census_context_status const **	status
	)

CENSUSAPI census_context* census_context_decode	(	const char *	buffer,
		size_t	size
	)

CENSUSAPI void census_context_destroy ( census_context * context )

CENSUSAPI size_t census_context_encode	(	const census_context *	context,
		char *	buffer,
		size_t	buf_size
	)

CENSUSAPI const census_context_status* census_context_get_status ( const census_context * context )

CENSUSAPI int census_context_get_tag	(	const census_context *	context,
		const char *	key,
		census_tag *	tag
	)

CENSUSAPI void census_context_initialize_iterator	(	const census_context *	context,
		census_context_iterator *	iterator
	)

CENSUSAPI int census_context_next_tag	(	census_context_iterator *	iterator,
		census_tag *	tag
	)

CENSUSAPI int census_enabled ( void )

Return the census features currently enabled.

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

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

CENSUSAPI 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()).

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

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

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

CENSUSAPI void census_set_trace_mask ( int trace_mask )

Set the trace mask associated with a context.

CENSUSAPI void census_shutdown ( void )

CENSUSAPI census_context* census_start_client_rpc_op	(	const census_context *	context,
		int64_t	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.

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

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

CENSUSAPI census_context* census_start_server_rpc_op	(	const char *	buffer,
		int64_t	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.

CENSUSAPI int census_supported ( void )

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

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

CENSUSAPI void census_trace_print	(	census_context *	context,
		uint32_t	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

CENSUSAPI void census_trace_scan_end ( )

End a scan previously started by census_trace_scan_start()

CENSUSAPI 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)

CENSUSAPI const census_aggregation* census_view_aggregrations ( const census_view * view )

Get aggregation descriptors associated with a view.

CENSUSAPI census_view* census_view_create	(	uint32_t	metric_id,
		const census_context *	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

CENSUSAPI void census_view_delete ( census_view * view )

Destroy a previously created view.

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

CENSUSAPI size_t census_view_metric ( const census_view * view )

Metric ID associated with a view.

CENSUSAPI size_t census_view_naggregations ( const census_view * view )

Number of aggregations associated with view.

CENSUSAPI void census_view_reset ( census_view * view )

Reset all view data to zero for the specified view.

CENSUSAPI const census_context* 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

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation