diff options
| -rw-r--r-- | include/grpc/census.h | 174 |
1 files changed, 149 insertions, 25 deletions
diff --git a/include/grpc/census.h b/include/grpc/census.h index a32da6f364..e2bef9add3 100644 --- a/include/grpc/census.h +++ b/include/grpc/census.h @@ -46,11 +46,12 @@ extern "C" { /* Identify census functionality that can be enabled via census_initialize(). */ enum census_functions { - CENSUS_NONE = 0, /* Do not enable census. */ - CENSUS_TRACING = 1, /* Enable census tracing. */ - CENSUS_STATS = 2, /* Enable Census stats collection. */ - CENSUS_CPU = 4, /* Enable Census CPU usage collection. */ - CENSUS_ALL = CENSUS_TRACING | CENSUS_STATS | CENSUS_CPU + CENSUS_NONE = 0, /* Do not enable census. */ + CENSUS_TRACING = 1, /* Enable distributed tracing. */ + CENSUS_STATS = 2, /* Enable stats collection. */ + CENSUS_CPU = 4, /* Enable CPU usage collection. */ + CENSUS_ACTIVE_OPS = 8, /* Trace Active operations. */ + CENSUS_ALL = CENSUS_TRACING | CENSUS_STATS | CENSUS_CPU | CENSUS_ACTIVE_OPS }; /* Shutdown and startup census subsystem. The 'functions' argument should be @@ -100,26 +101,149 @@ int census_context_deserialize(const char *buffer, census_context **context); * future census calls will result in undefined behavior. */ void census_context_destroy(census_context *context); -/* Start a new logical tracing "operation". The operation ends when - * census_trace_end_op() is called. */ -void census_trace_start_op(census_context *context); -+ service method start time, - peer ? +sampled ? - - /* End a tracing operation. Must be matched with an earlier - * census_start_op(). - */ - void - census_trace_end_op(census_context *context); -+ 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); - -census_active_ops_as_html() + struct or char *query ops - census_sampled_ops_as_html() +/* 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); + +/* 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 + 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 operation (e.g. latency + breakdown for each service/method combination). + + The following functions serve to delineate the start and stop points for + each logical operation. */ +/** + Start a client rpc operation. 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 + 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 + 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. + + @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); + +/** + 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. + */ +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); + +/** + 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: + - 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 + 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 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. + + @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); + +/** End a tracing operation. Must be matched with an earlier + * census_start_*_op*() call. */ +void census_trace_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 */); #ifdef __cplusplus } |