GRPC Core  0.11.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
census.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015, Google Inc.
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are
8  * met:
9  *
10  * * Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * * Redistributions in binary form must reproduce the above
13  * copyright notice, this list of conditions and the following disclaimer
14  * in the documentation and/or other materials provided with the
15  * distribution.
16  * * Neither the name of Google Inc. nor the names of its
17  * contributors may be used to endorse or promote products derived from
18  * this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  */
33 
34 /* RPC-internal Census API's. These are designed to be generic enough that
35  * they can (ultimately) be used in many different RPC systems (with differing
36  * implementations). */
37 
38 #ifndef CENSUS_CENSUS_H
39 #define CENSUS_CENSUS_H
40 
41 #include <grpc/grpc.h>
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 
47 /* Identify census features that can be enabled via census_initialize(). */
49  CENSUS_FEATURE_NONE = 0, /* Do not enable census. */
50  CENSUS_FEATURE_TRACING = 1, /* Enable census tracing. */
51  CENSUS_FEATURE_STATS = 2, /* Enable Census stats collection. */
52  CENSUS_FEATURE_CPU = 4, /* Enable Census CPU usage collection. */
55 };
56 
62 int census_initialize(int features);
63 void census_shutdown(void);
64 
67 int census_supported(void);
68 
70 int census_enabled(void);
71 
81 
82 /* This function is called by the RPC subsystem whenever it needs to get a
83  * serialized form of the current census context (presumably to pass across
84  * the wire). Arguments:
85  * 'buffer': pointer to memory into which serialized context will be placed
86  * 'buf_size': size of 'buffer'
87  *
88  * Returns: the number of bytes used in buffer if successful, or 0 if the
89  * buffer is of insufficient size.
90  *
91  * TODO(aveitch): determine how best to communicate required/max buffer size
92  * so caller doesn't have to guess. */
93 size_t census_context_serialize(const census_context *context, char *buffer,
94  size_t buf_size);
95 
96 /* Distributed traces can have a number of options. */
98  CENSUS_TRACE_MASK_NONE = 0, /* Default, empty flags */
99  CENSUS_TRACE_MASK_IS_SAMPLED = 1 /* RPC tracing enabled for this context. */
100 };
101 
104 int census_trace_mask(const census_context *context);
105 
107 void census_set_trace_mask(int trace_mask);
108 
109 /* The concept of "operation" is a fundamental concept for Census. In an RPC
110  system, and operation typcially represents a single RPC, or a significant
111  sub-part thereof (e.g. a single logical "read" RPC to a distributed storage
112  system might do several other actions in parallel, from looking up metadata
113  indices to making requests of other services - each of these could be a
114  sub-operation with the larger RPC operation). Census uses operations for the
115  following:
116 
117  CPU accounting: If enabled, census will measure the thread CPU time
118  consumed between operation start and end times.
119 
120  Active operations: Census will maintain information on all currently
121  active operations.
122 
123  Distributed tracing: Each operation serves as a logical trace span.
124 
125  Stats collection: Stats are broken down by operation (e.g. latency
126  breakdown for each unique RPC path).
127 
128  The following functions serve to delineate the start and stop points for
129  each logical operation. */
130 
135 typedef struct {
136  /* Use gpr_timespec for default implementation. High performance
137  * implementations should use a cycle-counter based timestamp. */
140 
156 
168 typedef struct {
169  const char *(*get_rpc_service_name)(gpr_int64 id);
170  const char *(*get_rpc_method_name)(gpr_int64 id);
172 
208  const census_context *context, gpr_int64 rpc_name_id,
209  const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask,
210  const census_timestamp *start_time);
211 
215 void census_set_rpc_client_peer(census_context *context, const char *peer);
216 
236  const char *buffer, gpr_int64 rpc_name_id,
237  const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask,
238  census_timestamp *start_time);
239 
265 census_context *census_start_op(census_context *context, const char *family,
266  const char *name, int trace_mask);
267 
277 void census_end_op(census_context *context, int status);
278 
279 #define CENSUS_TRACE_RECORD_START_OP ((gpr_uint32)0)
280 #define CENSUS_TRACE_RECORD_END_OP ((gpr_uint32)1)
281 
289 void census_trace_print(census_context *context, gpr_uint32 type,
290  const char *buffer, size_t n);
291 
293 typedef struct {
294  census_timestamp timestamp; /* Time of record creation */
295  gpr_uint64 trace_id; /* Trace ID associated with record */
296  gpr_uint64 op_id; /* Operation ID associated with record */
297  gpr_uint32 type; /* Type (as used in census_trace_print() */
298  const char *buffer; /* Buffer (from census_trace_print() */
299  size_t buf_size; /* Number of bytes inside buffer */
301 
311 int census_trace_scan_start(int consume);
312 
323 
325 void census_trace_scan_end();
326 
327 /* Max number of characters in tag key */
328 #define CENSUS_MAX_TAG_KEY_LENGTH 20
329 /* Max number of tag value characters */
330 #define CENSUS_MAX_TAG_VALUE_LENGTH 50
331 
332 /* A Census tag set is a collection of key:value string pairs; these form the
333  basis against which Census metrics will be recorded. Keys are unique within
334  a tag set. All contexts have an associated tag set. */
336 
337 /* Returns a pointer to a newly created, empty tag set. If size_hint > 0,
338  indicates that the tag set is intended to hold approximately that number
339  of tags. */
340 census_tag_set *census_tag_set_create(size_t size_hint);
341 
342 /* Add a new tag key/value to an existing tag set; if the tag key already exists
343  in the tag set, then its value is overwritten with the new one. Can also be
344  used to delete a tag, by specifying a NULL value. If key is NULL, returns
345  the number of tags in the tag set.
346  Return values:
347  -1: invalid length key or value
348  non-negative value: the number of tags in the tag set. */
349 int census_tag_set_add(census_tag_set *tags, const char *key,
350  const char *value);
351 
352 /* Destroys a tag set. This function must be called to prevent memory leaks.
353  Once called, the tag set cannot be used again. */
355 
356 /* Get a contexts tag set. */
358 
359 /* A read-only representation of a tag for use by census clients. */
360 typedef struct {
361  size_t key_len; /* Number of bytes in tag key. */
362  const char *key; /* A pointer to the tag key. May not be null-terminated. */
363  size_t value_len; /* Number of bytes in tag value. */
364  const char *value; /* Pointer to the tag value. May not be null-terminated. */
366 
367 /* Used to iterate through a tag sets contents. */
369 
370 /* Open a tag set for iteration. The tag set must not be modified while
371  iteration is ongoing. Returns an iterator for use in following functions. */
373 
374 /* Get the next tag in the tag set, by writing into the 'tag' argument. Returns
375  1 if there is a "next" tag, 0 if there are no more tags. */
377 
378 /* Close an iterator opened by census_tag_set_open(). The iterator will be
379  invalidated, and should not be used once close is called. */
381 
382 /* Core stats collection API's. The following concepts are used:
383  * Aggregation: A collection of values. Census supports the following
384  aggregation types:
385  Sum - a single summation type. Typically used for keeping (e.g.)
386  counts of events.
387  Distribution - statistical distribution information, used for
388  recording average, standard deviation etc.
389  Histogram - a histogram of measurements falling in defined bucket
390  boundaries.
391  Window - a count of events that happen in reolling time window.
392  New aggregation types can be added by the user, if desired (see
393  census_register_aggregation()).
394  * Metric: Each measurement is for a single metric. Examples include RPC
395  latency, CPU seconds consumed, and bytes transmitted.
396  * View: A view is a combination of a metric, a tag set (in which the tag
397  values are regular expressions) and a set of aggregations. When a
398  measurement for a metric matches the view tags, it is recorded (for each
399  unique set of tags) against each aggregation. Each metric can have an
400  arbitrary number of views by which it will be broken down.
401 */
402 
403 /* A single value to be recorded comprises two parts: an ID for the particular
404  * metric and the value to be recorded against it. */
405 typedef struct {
407  double value;
408 } census_value;
409 
410 /* Record new usage values against the given context. */
411 void census_record_values(census_context *context, census_value *values,
412  size_t nvalues);
413 
416 
417 /* Predefined aggregation types, for use with census_view_create(). */
422 
425 typedef struct {
427  const void
428  *create_arg; /* Argument to be used for aggregation initialization. */
430 
432 typedef struct census_view census_view;
433 
443  const census_tag_set *tags,
444  const census_aggregation *aggregations,
445  size_t naggregations);
446 
448 void census_view_delete(census_view *view);
449 
451 size_t census_view_metric(const census_view *view);
452 
454 size_t census_view_naggregations(const census_view *view);
455 
457 const census_tag_set *census_view_tags(const census_view *view);
458 
461 
464 typedef struct {
465  const census_tag_set *tags; /* Tags for this set of aggregations. */
466  const void **data; /* One data set for every aggregation in the view. */
468 
470 typedef struct {
471  size_t n_tag_sets; /* Number of unique tag sets that matched view. */
472  const census_view_aggregation_data *data; /* n_tag_sets entries */
474 
480 
482 void census_view_reset(census_view *view);
483 
484 #ifdef __cplusplus
485 }
486 #endif
487 
488 #endif /* CENSUS_CENSUS_H */
const census_tag_set * tags
Definition: census.h:465
census_aggregation_ops census_agg_histogram
const census_view_data * census_view_get_data(const census_view *view)
Get data from aggregations associated with a view.
void census_tag_set_destroy(census_tag_set *tags)
int census_get_trace_record(census_trace_record *trace_record)
Get a trace record.
census_tag_set * census_tag_set_create(size_t size_hint)
size_t census_view_naggregations(const census_view *view)
Number of aggregations associated with view.
size_t census_view_metric(const census_view *view)
Metric ID associated with a view.
struct census_aggregation_ops census_aggregation_ops
Type representing a particular aggregation.
Definition: census.h:415
Definition: census.h:405
double value
Definition: census.h:407
struct census_view census_view
A census view type.
Definition: census.h:432
Definition: census.h:50
Holds all the aggregation data for a particular view instantiation.
Definition: census.h:464
const void ** data
Definition: census.h:466
const census_view_aggregation_data * data
Definition: census.h:472
census_context * census_start_op(census_context *context, const char *family, const char *name, int trace_mask)
Start a new, non-RPC operation.
census_tag_set_iterator * census_tag_set_open(census_tag_set *tags)
void census_trace_scan_end()
End a scan previously started by census_trace_scan_start()
Information needed to instantiate a new aggregation.
Definition: census.h:425
int census_tag_set_add(census_tag_set *tags, const char *key, const char *value)
int census_initialize(int features)
Shutdown and startup census subsystem.
Definition: census.h:52
Trace record.
Definition: census.h:293
census_trace_mask_values
Definition: census.h:97
census_timestamp census_start_rpc_op_timestamp(void)
Mark the beginning of an RPC operation.
Represent functions to map RPC name ID to service/method names.
Definition: census.h:168
Definition: census.h:53
Definition: census.h:51
uint32_t gpr_uint32
Definition: port_platform.h:312
void census_trace_print(census_context *context, gpr_uint32 type, const char *buffer, size_t n)
Insert a trace record into the trace stream.
void census_shutdown(void)
const census_aggregation_ops * ops
Definition: census.h:426
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 server RPC operation.
int census_trace_scan_start(int consume)
Start a scan of existing trace records.
void census_set_trace_mask(int trace_mask)
Set the trace mask associated with a context.
void census_tag_set_close(census_tag_set_iterator *it)
int census_tag_set_next(census_tag_set_iterator *it, census_tag_const *tag)
void census_view_delete(census_view *view)
Destroy a previously created view.
int census_trace_mask(const census_context *context)
Get the current trace mask associated with this context.
census_view * census_view_create(gpr_uint32 metric_id, const census_tag_set *tags, const census_aggregation *aggregations, size_t naggregations)
Create a new view.
const census_aggregation * census_view_aggregrations(const census_view *view)
Get aggregation descriptors associated with a view.
size_t n_tag_sets
Definition: census.h:471
census_timestamp timestamp
Definition: census.h:294
gpr_timespec ts
Definition: census.h:138
census_aggregation_ops census_agg_distribution
int64_t gpr_int64
Definition: port_platform.h:309
struct census_tag_set census_tag_set
Definition: census.h:335
This structure represents a timestamp as used by census to record the time at which an operation begi...
Definition: census.h:135
const char * key
Definition: census.h:362
int census_supported(void)
Return the features supported by the current census implementation (not all features will be availabl...
Definition: census.h:99
census_aggregation_ops census_agg_sum
const census_tag_set * census_view_tags(const census_view *view)
Get tags associated with view.
gpr_uint32 metric_id
Definition: census.h:406
void census_view_reset(census_view *view)
Reset all view data to zero for the specified view.
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)
Start a client rpc operation.
census_tag_set * census_context_tag_set(census_context *context)
const char * value
Definition: census.h:364
gpr_uint64 op_id
Definition: census.h:296
Census view data as returned by census_view_get_data().
Definition: census.h:470
census_features
Definition: census.h:48
void census_record_values(census_context *context, census_value *values, size_t nvalues)
void census_end_op(census_context *context, int status)
End an operation started by any of the census_start_*_op*() calls.
Definition: time.h:63
uint64_t gpr_uint64
Definition: port_platform.h:313
struct census_tag_set_iterator census_tag_set_iterator
Definition: census.h:368
const void * create_arg
Definition: census.h:428
void census_set_rpc_client_peer(census_context *context, const char *peer)
Add peer information to a context representing a client RPC operation.
int census_enabled(void)
Return the census features currently enabled.
size_t value_len
Definition: census.h:363
Definition: census.h:98
const char * buffer
Definition: census.h:298
size_t buf_size
Definition: census.h:299
size_t key_len
Definition: census.h:361
census_aggregation_ops census_agg_window
size_t census_context_serialize(const census_context *context, char *buffer, size_t buf_size)
Definition: census.h:360
gpr_uint64 trace_id
Definition: census.h:295
struct census_context census_context
Context is a handle used by census to represent the current tracing and tagging information.
Definition: census.h:80
Definition: census.h:49
gpr_uint32 type
Definition: census.h:297