|
|
|
|
@ -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,19 +93,6 @@ 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); |
|
|
|
|
|
|
|
|
|
/* 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); |
|
|
|
|
|
|
|
|
|
/* Distributed traces can have a number of options. */ |
|
|
|
|
enum census_trace_mask_values { |
|
|
|
|
CENSUS_TRACE_MASK_NONE = 0, /* Default, empty flags */ |
|
|
|
|
@ -114,13 +103,15 @@ enum census_trace_mask_values { |
|
|
|
|
will be the logical or of census_trace_mask_values values. */ |
|
|
|
|
int census_trace_mask(const census_context *context); |
|
|
|
|
|
|
|
|
|
/* The concept of "operation" is a fundamental concept for Census. An
|
|
|
|
|
operation is a logical representation of a action in a RPC-using system. It |
|
|
|
|
is most typically used to represent 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 |
|
|
|
|
/** 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 |
|
|
|
|
sub-operation with the larger RPC operation). Census uses operations for the |
|
|
|
|
following: |
|
|
|
|
|
|
|
|
|
CPU accounting: If enabled, census will measure the thread CPU time |
|
|
|
|
@ -131,123 +122,152 @@ int census_trace_mask(const census_context *context); |
|
|
|
|
|
|
|
|
|
Distributed tracing: Each operation serves as a logical trace span. |
|
|
|
|
|
|
|
|
|
Stats collection: Stats are broken down operation (e.g. latency |
|
|
|
|
breakdown for each service/method combination). |
|
|
|
|
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 (opaquely) represents a timestamp as used by census to |
|
|
|
|
record the time at which an RPC operation begins. |
|
|
|
|
*/ |
|
|
|
|
typedef struct census_timestamp 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 will create a new context. If |
|
|
|
|
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 service/method/peer information for tracing and stats |
|
|
|
|
- use the new RPC path and peer information for tracing and stats |
|
|
|
|
collection purposes, rather than those from the original context |
|
|
|
|
- if trace_mask is non-zero, update the trace mask entries associated with |
|
|
|
|
the original context. |
|
|
|
|
|
|
|
|
|
If the context argument is NULL, then a new root context is created. This |
|
|
|
|
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). Whatever it's value, the trace_mask will be used for tracing |
|
|
|
|
operations associated with the new context. |
|
|
|
|
|
|
|
|
|
@param context The base context. Can be NULL. |
|
|
|
|
@param service RPC service name. On some systems, may include other |
|
|
|
|
parts of RPC identification (e.g. host on gRPC systems). |
|
|
|
|
@param method RPC method name |
|
|
|
|
@param peer RPC peer |
|
|
|
|
@param trace_mask An or of census_trace_mask_values values |
|
|
|
|
@param start_time If NULL, the time of function call is used as the |
|
|
|
|
start time for the operation. If non-NULL, then the time should be in the |
|
|
|
|
past, when the operation was deemed to have started. This is used when |
|
|
|
|
the other information used as arguments is not yet available. |
|
|
|
|
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(census_context *context, |
|
|
|
|
const char *service, |
|
|
|
|
const char *method, const char *peer, |
|
|
|
|
int trace_mask, |
|
|
|
|
gpr_timespec *start_time); |
|
|
|
|
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); |
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Indicate the start of a server rpc operation, updating the current |
|
|
|
|
context (which should have been created from census_context_deserialize() |
|
|
|
|
(as passed from the client side of the RPC operation) or census_start_op(). |
|
|
|
|
- if trace_mask is non-zero, update the trace mask entries associated with |
|
|
|
|
the original context. |
|
|
|
|
|
|
|
|
|
@param context The base context. Cannot be NULL. |
|
|
|
|
@param service RPC service name. On some systems, may include other |
|
|
|
|
parts of RPC identification (e.g. host on gRPC systems). |
|
|
|
|
@param method RPC method name |
|
|
|
|
@param peer RPC peer |
|
|
|
|
@param trace_mask An or of census_trace_mask_values values |
|
|
|
|
@param start_time If NULL, the time of function call is used as the |
|
|
|
|
start time for the operation. If non-NULL, then the time should be in the |
|
|
|
|
past, when the operation was deemed to have started. This is used when |
|
|
|
|
the other information used as arguments is not yet available. |
|
|
|
|
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. |
|
|
|
|
*/ |
|
|
|
|
void census_start_server_rpc_op(census_context *context, const char *service, |
|
|
|
|
const char *method, const char *peer, |
|
|
|
|
int trace_mask, gpr_timespec *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 new, non-RPC census operation. In general, this function works very |
|
|
|
|
similarly to census_start_client_rpc_op, with the primary differennce being |
|
|
|
|
the abscence of peer information, and the replacement of service and method |
|
|
|
|
names with the more general family/name. If the context argument is |
|
|
|
|
non-null, then the new context will inherit all its properties, with the |
|
|
|
|
following changes: |
|
|
|
|
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 trace_mask is non-zero, update the trace mask entries associated with |
|
|
|
|
the original context. |
|
|
|
|
|
|
|
|
|
If the context argument is NULL, then a new root context is created. This |
|
|
|
|
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). Whatever it's value, the trace_mask will be used for tracing |
|
|
|
|
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 |
|
|
|
|
@param start_time If NULL, the time of function call is used as the |
|
|
|
|
start time for the operation. If non-NULL, then the time should be in the |
|
|
|
|
past, when the operation was deemed to have started. This is used when |
|
|
|
|
the other information used as arguments is not yet available. |
|
|
|
|
@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, |
|
|
|
|
gpr_timespec *start_time); |
|
|
|
|
const char *name, int trace_mask); |
|
|
|
|
|
|
|
|
|
/** End a tracing operation. Must be matched with an earlier
|
|
|
|
|
* census_start_*_op*() call. */ |
|
|
|
|
void census_trace_end_op(census_context *context, int status); |
|
|
|
|
/** End an operation started by any of the census_start_*_op*() calls. */ |
|
|
|
|
void census_end_op(census_context *context, int status); |
|
|
|
|
|
|
|
|
|
/** Insert a trace record into the trace stream. The record consists of an
|
|
|
|
|
* arbitrary size buffer, the size of which is provided in 'n'. */ |
|
|
|
|
void census_trace_print(census_context *context, const char *buffer, size_t n); |
|
|
|
|
|
|
|
|
|
/** Retrieve active ops as a proto. Note that since we don't have proto
|
|
|
|
|
manipulation available in the grpc core yet, arguments etc. are left |
|
|
|
|
unspecified for now. */ |
|
|
|
|
void census_get_active_ops_as_proto(/* pointer to proto */); |
|
|
|
|
|
|
|
|
|
/** Retrieve all active trace records as a proto. Note that since we don't
|
|
|
|
|
have proto manipulation available in the grpc core yet, arguments etc. are |
|
|
|
|
left unspecified for now. This function will clear existing trace |
|
|
|
|
records. */ |
|
|
|
|
void census_get_trace_as_proto(/* pointer to proto */); |
|
|
|
|
|
|
|
|
|
/* A census statistic to be recorded comprises two parts: an ID for the
|
|
|
|
|
* particular statistic and the value to be recorded against it. */ |
|
|
|
|
typedef struct { |
|
|
|
|
|
Alistair Veitch
10 years ago