#include <grpc/grpc.h>

Data Structures
struct	census_tag
	A tag is a key:value pair. More...

struct	census_context_status
	An instance of this structure is kept by every context, and records the basic information associated with the creation of that context. More...

struct	census_context_iterator
	Structure used for iterating over the tags in a context. More...

struct	census_timestamp
	The concept of "operation" is a fundamental concept for Census. 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
	A single value to be recorded comprises two parts: an ID for the particular resource and the value to be recorded against it. More...

Macros
#define	CENSUS_MAX_TAG_KV_LEN 255
	Maximum length of a tag's key or value. More...

#define	CENSUS_MAX_PROPAGATED_TAGS 255
	Maximum number of propagatable tags. More...

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

#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)
	Flag values 4,8,16,32,64,128 are reserved for future/internal use. More...

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

Enumerations
enum	census_features { CENSUS_FEATURE_NONE = 0, CENSUS_FEATURE_TRACING = 1, CENSUS_FEATURE_STATS = 2, CENSUS_FEATURE_CPU = 4, CENSUS_FEATURE_ALL }
	RPC-internal Census API's. More...

enum	census_trace_mask_values { CENSUS_TRACE_MASK_NONE = 0, CENSUS_TRACE_MASK_IS_SAMPLED = 1 }
	Distributed traces can have a number of options. More...

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)
	Create a new context, adding and removing tags from an existing context. More...

CENSUSAPI void	census_context_destroy (census_context *context)
	Destroy a context. More...

CENSUSAPI const census_context_status *	census_context_get_status (const census_context *context)
	Get a pointer to the original status from the context creation. More...

CENSUSAPI void	census_context_initialize_iterator (const census_context context, census_context_iterator iterator)
	Initialize a census_tag_iterator. More...

CENSUSAPI int	census_context_next_tag (census_context_iterator iterator, census_tag tag)
	Get the contents of the "next" tag in the context. More...

CENSUSAPI int	census_context_get_tag (const census_context context, const char key, census_tag *tag)
	Get a context tag by key. More...

CENSUSAPI size_t	census_context_encode (const census_context context, char buffer, size_t buf_size)
	Tag set encode/decode functionality. More...

CENSUSAPI census_context *	census_context_decode (const char *buffer, size_t size)
	Decode context buffer encoded with census_context_encode(). More...

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 int32_t	census_define_resource (const uint8_t *resource_pb, size_t resource_pb_size)
	Core stats collection API's. More...

CENSUSAPI void	census_delete_resource (int32_t resource_id)
	Delete a resource created by census_define_resource(). More...

CENSUSAPI int32_t	census_resource_id (const char *name)
	Determine the id of a resource, given its name. More...

CENSUSAPI void	census_record_values (census_context context, census_value values, size_t nvalues)
	Record new usage values against the given context. More...

Macro Definition Documentation

#define CENSUS_MAX_PROPAGATED_TAGS 255

Maximum number of propagatable tags.

#define CENSUS_MAX_TAG_KV_LEN 255

Maximum length of a tag's key or value.

#define CENSUS_TAG_IS_PROPAGATED ( flags ) (flags & CENSUS_TAG_PROPAGATE)

Flag values 4,8,16,32,64,128 are reserved for future/internal use.

Clients should not use or rely on their values.

#define CENSUS_TAG_IS_STATS ( flags ) (flags & CENSUS_TAG_STATS)

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

Tag flags.

#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_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.

Enumeration Type Documentation

enum census_features

RPC-internal Census API's.

These are designed to be generic enough that they can (ultimately) be used in many different RPC systems (with differing implementations). Identify census features that can be enabled via census_initialize().

Enumerator
CENSUS_FEATURE_NONE
CENSUS_FEATURE_TRACING	Do not enable census.
CENSUS_FEATURE_STATS	Enable census tracing.
CENSUS_FEATURE_CPU	Enable Census stats collection.
CENSUS_FEATURE_ALL	Enable Census CPU usage collection.

enum census_trace_mask_values

Distributed traces can have a number of options.

Enumerator
CENSUS_TRACE_MASK_NONE
CENSUS_TRACE_MASK_IS_SAMPLED	Default, empty flags.

Function Documentation

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

Create a new context, adding and removing tags from an existing context.

This will copy all tags from the 'tags' input, so it is recommended to add as many tags in a single operation as is practical for the client.

Parameters

base	Base context to build upon. Can be NULL.
tags	A set of tags to be added/changed/deleted. Tags with keys that are in 'tags', but not 'base', are added to the context. Keys that are in both 'tags' and 'base' will have their value/flags modified. Tags with keys in both, but with NULL values, will be deleted from the context. Tags with invalid (too long or short) keys or values will be ignored. If adding a tag will result in more than CENSUS_MAX_PROPAGATED_TAGS in either binary or non-binary tags, they will be ignored, as will deletions of tags that don't exist.
ntags	number of tags in 'tags'
status	If not NULL, will return a pointer to a census_context_status structure containing information about the new context and status of the tags used in its creation.

Returns: A new, valid census_context.

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

Decode context buffer encoded with census_context_encode().

Returns NULL if there is an error in parsing either buffer.

CENSUSAPI void census_context_destroy ( census_context * context )

Destroy a context.

Once this function has been called, the context cannot be reused.

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

Tag set encode/decode functionality.

These functions are intended for use by RPC systems only, for purposes of transmitting/receiving contexts. Encode a context into a buffer.

Parameters

context	context to be encoded
buffer	buffer into which the context will be encoded.
buf_size	number of available bytes in buffer.

Returns: The number of buffer bytes consumed for the encoded context, or zero if the buffer was of insufficient size.

CENSUSAPI const census_context_status* census_context_get_status ( const census_context * context )

Get a pointer to the original status from the context creation.

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

Get a context tag by key.

Returns 0 if the key is not present.

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

Initialize a census_tag_iterator.

Must be called before first use.

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

Get the contents of the "next" tag in the context.

If there are no more tags, returns 0 (and 'tag' contents will be unchanged), otherwise returns 1.

CENSUSAPI int32_t census_define_resource	(	const uint8_t *	resource_pb,
		size_t	resource_pb_size
	)

Core stats collection API's.

The following concepts are used: Resource: Users record measurements for a single resource. Examples include RPC latency, CPU seconds consumed, and bytes transmitted. Aggregation: An aggregation of a set of measurements. Census supports the following aggregation types: Distribution - statistical distribution information, used for recording average, standard deviation etc. Can include a histogram. Interval - a count of events that happen in a rolling time window. View: A view is a combination of a Resource, a set of tag keys and an Aggregation. When a measurement for a Resource matches the View tags, it is recorded (for each unique set of tag values) using the Aggregation type. Each resource can have an arbitrary number of views by which it will be broken down.

Census uses protos to define each of the above, and output results. This ensures unification across the different language and runtime implementations. The proto definitions can be found in src/proto/census. Define a new resource. resource_pb should contain an encoded Resource protobuf, resource_pb_size being the size of the buffer. Returns a -ve value on error, or a positive (>= 0) resource id (for use in census_delete_resource() and census_record_values()). In order to be valid, a resource must have a name, and at least one numerator in its unit type. The resource name must be unique, and an error will be returned if it is not.

CENSUSAPI void census_delete_resource ( int32_t resource_id )

Delete a resource created by census_define_resource().

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 -1, otherwise the set of enabled features (which may be smaller than that provided in the features argument, see census_supported()) is returned. It is an error to call census_initialize() more than once (without an intervening census_shutdown()). These functions are not thread-safe.

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

Record new usage values against the given context.

CENSUSAPI int32_t census_resource_id ( const char * name )

Determine the id of a resource, given its name.

returns -1 if the resource does not exist.

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation