@ -69,12 +69,14 @@ int census_supported(void);
/** Return the census features currently enabled. */
int census_enabled ( void ) ;
/* Internally, Census relies on a context, which should be propagated across
* RPC ' s . From the RPC subsystems viewpoint , this is an opaque data structure .
* A context must be used as the first argument to all other census
* functions . Conceptually , contexts should be thought of as specific to
* single RPC / thread . The context can be serialized for passing across the
* wire . */
/**
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_context census_context ;
/* This function is called by the RPC subsystem whenever it needs to get a
@ -91,18 +93,236 @@ typedef struct census_context census_context;
size_t census_context_serialize ( const census_context * context , char * buffer ,
size_t buf_size ) ;
/* Create a new census context, possibly from a serialized buffer. If 'buffer'
* is non - NULL , it is assumed that it is a buffer encoded by
* census_context_serialize ( ) . If ` buffer ` is NULL , a new , empty context is
* created . The decoded / new contest is returned in ' context ' .
*
* Returns 0 if no errors , non - zero if buffer is incorrectly formatted , in
* which case a new empty context will be returned . */
int census_context_deserialize ( const char * buffer , census_context * * context ) ;
/* Distributed traces can have a number of options. */
enum census_trace_mask_values {
CENSUS_TRACE_MASK_NONE = 0 , /* Default, empty flags */
CENSUS_TRACE_MASK_IS_SAMPLED = 1 /* RPC tracing enabled for this context. */
} ;
/** Get the current trace mask associated with this context. The value returned
will be the logical or of census_trace_mask_values values . */
int census_trace_mask ( const census_context * context ) ;
/** Set the trace mask associated with a context. */
void census_set_trace_mask ( int trace_mask ) ;
/* The concept of "operation" is a fundamental concept for Census. In an RPC
system , and operation typcially represents a single RPC , or a significant
sub - part thereof ( e . g . a single logical " read " RPC to a distributed storage
system might do several other actions in parallel , from looking up metadata
indices to making requests of other services - each of these could be a
sub - operation with the larger RPC operation ) . Census uses operations for the
following :
CPU accounting : If enabled , census will measure the thread CPU time
consumed between operation start and end times .
Active operations : Census will maintain information on all currently
active operations .
Distributed tracing : Each operation serves as a logical trace span .
Stats collection : Stats are broken down by operation ( e . g . latency
breakdown for each unique RPC path ) .
The following functions serve to delineate the start and stop points for
each logical operation . */
/**
This structure represents a timestamp as used by census to record the time
at which an operation begins .
*/
typedef struct {
/* Use gpr_timespec for default implementation. High performance
* implementations should use a cycle - counter based timestamp . */
gpr_timespec ts ;
} census_timestamp ;
/**
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 .
@ return A timestamp representing the operation start time .
*/
census_timestamp census_start_rpc_op_timestamp ( void ) ;
/**
Represent functions to map RPC name ID to service / method names . Census
breaks down all RPC stats by service and method names . We leave the
definition and format of these to the RPC system . For efficiency purposes ,
we encode these as a single 64 bit identifier , and allow the RPC system to
provide a structure for functions that can convert these to service and
method strings .
TODO ( aveitch ) : Instead of providing this as an argument to the rpc_start_op ( )
functions , maybe it should be set once at census initialization .
*/
typedef struct {
const char * ( * get_rpc_service_name ) ( gpr_int64 id ) ;
const char * ( * get_rpc_method_name ) ( gpr_int64 id ) ;
} census_rpc_name_info ;
/**
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 .
@ param context The parent context . Can be NULL .
@ param rpc_name_id The rpc name identifier to be associated with this RPC .
@ param rpc_name_info Used to decode rpc_name_id .
@ param peer RPC peer . If not available at the time , NULL can be used ,
and a later census_set_rpc_client_peer ( ) call made .
@ param trace_mask An OR of census_trace_mask_values values . Only used in
the creation of a new root context ( context = = NULL ) .
@ param start_time A timestamp returned from census_start_rpc_op_timestamp ( ) .
Can be NULL . Used to set the true time the operation
begins .
@ return A new census context .
*/
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 ) ;
/**
Add peer information to a context representing a client RPC operation .
*/
void census_set_rpc_client_peer ( census_context * context , const char * peer ) ;
/**
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 .
@ param buffer Buffer containing bytes output from census_context_serialize ( ) .
@ param rpc_name_id The rpc name identifier to be associated with this RPC .
@ param rpc_name_info Used to decode rpc_name_id .
@ param peer RPC peer .
@ param trace_mask An OR of census_trace_mask_values values . Only used in
the creation of a new root context ( buffer = = NULL ) .
@ param start_time A timestamp returned from census_start_rpc_op_timestamp ( ) .
Can be NULL . Used to set the true time the operation
begins .
@ return A new census context .
*/
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 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 .
@ param context The base context . Can be NULL .
@ param family Family name to associate with the trace
@ param name Name within family to associated with traces / stats
@ param trace_mask An OR of census_trace_mask_values values . Only used if
context is NULL .
@ return A new census context .
*/
census_context * census_start_op ( census_context * context , const char * family ,
const char * name , int trace_mask ) ;
/**
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 .
@ param context Context associated with operation which is ending .
@ param status status associated with the operation . Not interpreted by
census .
*/
void census_end_op ( census_context * context , int status ) ;
# define CENSUS_TRACE_RECORD_START_OP ((gpr_uint32)0)
# define CENSUS_TRACE_RECORD_END_OP ((gpr_uint32)1)
/** Insert a trace record into the trace stream. The record consists of an
arbitrary size buffer , the size of which is provided in ' n ' .
@ param context Trace context
@ param type User - defined type to associate with trace entry .
@ param buffer Pointer to buffer to use
@ param n Number of bytes in buffer
*/
void census_trace_print ( census_context * context , gpr_uint32 type ,
const char * buffer , size_t n ) ;
/** Trace record. */
typedef struct {
census_timestamp timestamp ; /* Time of record creation */
gpr_uint64 trace_id ; /* Trace ID associated with record */
gpr_uint64 op_id ; /* Operation ID associated with record */
gpr_uint32 type ; /* Type (as used in census_trace_print() */
const char * buffer ; /* Buffer (from census_trace_print() */
size_t buf_size ; /* Number of bytes inside buffer */
} census_trace_record ;
/** 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 .
@ param 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 )
*/
int census_trace_scan_start ( int consume ) ;
/** 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 ) .
@ param 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_get_trace_record ( census_trace_record * trace_record ) ;
/* The given context is destroyed. Once destroyed, using the context in
* future census calls will result in undefined behavior . */
void census_context_destroy ( census_context * context ) ;
/** End a scan previously started by census_trace_scan_start() */
void census_trace_scan_end ( ) ;
/* Max number of characters in tag key */
# define CENSUS_MAX_TAG_KEY_LENGTH 20
Julien Boeuf
9 years ago