post merge

1 files changed, 144 insertions, 163 deletions

diff --git a/include/grpc/census.h b/include/grpc/census.h
index f4130c7e6a..3624337392 100644
--- a/include/grpc/census.h
+++ b/include/grpc/census.h
@@ -70,28 +70,144 @@ int census_supported(void);
 int census_enabled(void);
 
 /**
-  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().
-*/
+  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. */
 typedef struct census_context census_context;
 
-/* This function is called by the RPC subsystem whenever it needs to get a
- * serialized form of the current census context (presumably to pass across
- * the wire). Arguments:
- * 'buffer': pointer to memory into which serialized context will be placed
- * 'buf_size': size of 'buffer'
- *
- * Returns: the number of bytes used in buffer if successful, or 0 if the
- * buffer is of insufficient size.
- *
- * TODO(aveitch): determine how best to communicate required/max buffer size
- * so caller doesn't have to guess. */
-size_t census_context_serialize(const census_context *context, char *buffer,
-                                size_t buf_size);
+/* A tag is a key:value pair. The key is a non-empty, printable (UTF-8
+   encoded), nil-terminated string. The value is a binary string, that may be
+   printable. There are limits on the sizes of both keys and values (see
+   CENSUS_MAX_TAG_KB_LEN definition below), and the number of tags that can be
+   propagated (CENSUS_MAX_PROPAGATED_TAGS). Users should also remember that
+   some systems may have limits on, e.g., the number of bytes that can be
+   transmitted as metadata, and that larger tags means more memory consumed
+   and time in processing. */
+typedef struct {
+  const char *key;
+  const char *value;
+  size_t value_len;
+  uint8_t flags;
+} census_tag;
+
+/* Maximum length of a tag's key or value. */
+#define CENSUS_MAX_TAG_KV_LEN 255
+/* Maximum number of propagatable tags. */
+#define CENSUS_MAX_PROPAGATED_TAGS 255
+
+/* Tag flags. */
+#define CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */
+#define CENSUS_TAG_STATS 2     /* Tag will be used for statistics aggregation */
+#define CENSUS_TAG_BINARY 4    /* Tag value is not printable */
+#define CENSUS_TAG_RESERVED 8  /* Reserved for internal use. */
+/* Flag values 8,16,32,64,128 are reserved for future/internal use. Clients
+   should not use or rely on their values. */
+
+#define CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE)
+#define CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS)
+#define CENSUS_TAG_IS_BINARY(flags) (flags & CENSUS_TAG_BINARY)
+
+/* An instance of this structure is kept by every context, and records the
+   basic information associated with the creation of that context. */
+typedef struct {
+  int n_propagated_tags;        /* number of propagated printable tags */
+  int n_propagated_binary_tags; /* number of propagated binary tags */
+  int n_local_tags;             /* number of non-propagated (local) tags */
+  int n_deleted_tags;           /* number of tags that were deleted */
+  int n_added_tags;             /* number of tags that were added */
+  int n_modified_tags;          /* number of tags that were modified */
+  int n_invalid_tags;           /* number of tags with bad keys or values (e.g.
+                                   longer than CENSUS_MAX_TAG_KV_LEN) */
+  int n_ignored_tags;           /* number of tags ignored because of
+                                   CENSUS_MAX_PROPAGATED_TAGS limit. */
+} census_context_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.
+   @param base Base context to build upon. Can be NULL.
+   @param tags A set of tags to be added/changed/deleted. Tags with keys that
+   are in 'tags', but not 'base', are added to the tag set. Keys that are in
+   both 'tags' and 'base' will have their value/flags modified. Tags with keys
+   in both, but with NULL or zero-length values, will be deleted from the tag
+   set. 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.
+   @param ntags number of tags in 'tags'
+   @param 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.
+   @return A new, valid census_context.
+*/
+census_context *census_context_create(const census_context *base,
+                                      const census_tag *tags, int ntags,
+                                      census_context_status const **status);
+
+/* Destroy a context. Once this function has been called, the context cannot
+   be reused. */
+void census_context_destroy(census_context *context);
+
+/* Get a pointer to the original status from the context creation. */
+const census_context_status *census_context_get_status(
+    const census_context *context);
+
+/* Structure used for iterating over the tegs in a context. API clients should
+   not use or reference internal fields - neither their contents or
+   presence/absence are guaranteed. */
+typedef struct {
+  const census_context *context;
+  int base;
+  int index;
+  char *kvm;
+} census_context_iterator;
+
+/* Initialize a census_tag_iterator. Must be called before first use. */
+void census_context_initialize_iterator(const census_context *context,
+                                        census_context_iterator *iterator);
+
+/* 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.
+   */
+int census_context_next_tag(census_context_iterator *iterator, census_tag *tag);
+
+/* Get a context tag by key. Returns 0 if the key is not present. */
+int census_context_get_tag(const census_context *context, const char *key,
+                           census_tag *tag);
+
+/* Tag set encode/decode functionality. These functionas are intended
+   for use by RPC systems only, for purposes of transmitting/receiving contexts.
+   */
+
+/* Encode a context into a buffer. The propagated tags are encoded into the
+   buffer in two regions: one for printable tags, and one for binary tags.
+   @param context context to be encoded
+   @param buffer pointer to buffer. This address will be used to encode the
+                 printable tags.
+   @param buf_size number of available bytes in buffer.
+   @param print_buf_size Will be set to the number of bytes consumed by
+                         printable tags.
+   @param bin_buf_size Will be set to the number of bytes used to encode the
+                       binary tags.
+   @return A pointer to the binary tag's encoded, or NULL if the buffer was
+           insufficiently large to hold the encoded tags. Thus, if successful,
+           printable tags are encoded into
+           [buffer, buffer + *print_buf_size) and binary tags into
+           [returned-ptr, returned-ptr + *bin_buf_size) (and the returned
+           pointer should be buffer + *print_buf_size) */
+char *census_context_encode(const census_context *context, char *buffer,
+                            size_t buf_size, size_t *print_buf_size,
+                            size_t *bin_buf_size);
+
+/* Decode context buffers encoded with census_context_encode(). Returns NULL
+   if there is an error in parsing either buffer. */
+census_context *census_context_decode(const char *buffer, size_t size,
+                                      const char *bin_buffer, size_t bin_size);
 
 /* Distributed traces can have a number of options. */
 enum census_trace_mask_values {
@@ -324,143 +440,6 @@ int census_get_trace_record(census_trace_record *trace_record);
 /** End a scan previously started by census_trace_scan_start() */
 void census_trace_scan_end();
 
-/* A Census tag set is a collection of key:value string pairs; these form the
-   basis against which Census metrics will be recorded. Keys are unique within
-   a tag set. All contexts have an associated tag set. */
-typedef struct census_tag_set census_tag_set;
-
-/* A tag is a key:value pair. The key is a non-empty, printable (UTF-8
-   encoded), nil-terminated string. The value is a binary string, that may be
-   printable. There are limits on the sizes of both keys and values (see
-   CENSUS_MAX_TAG_KB_LEN definition below), and the number of tags that can be
-   propagated (CENSUS_MAX_PROPAGATED_TAGS). Users should also remember that
-   some systems may have limits on, e.g., the number of bytes that can be
-   transmitted as metadata, and that larger tags means more memory consumed
-   and time in processing. */
-typedef struct {
-  const char *key;
-  const char *value;
-  size_t value_len;
-  uint8_t flags;
-} census_tag;
-
-/* Maximum length of a tag's key or value. */
-#define CENSUS_MAX_TAG_KV_LEN 255
-/* Maximum number of propagatable tags. */
-#define CENSUS_MAX_PROPAGATED_TAGS 255
-
-/* Tag flags. */
-#define CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */
-#define CENSUS_TAG_STATS 2     /* Tag will be used for statistics aggregation */
-#define CENSUS_TAG_BINARY 4    /* Tag value is not printable */
-#define CENSUS_TAG_RESERVED 8  /* Reserved for internal use. */
-/* Flag values 8,16,32,64,128 are reserved for future/internal use. Clients
-   should not use or rely on their values. */
-
-#define CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE)
-#define CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS)
-#define CENSUS_TAG_IS_BINARY(flags) (flags & CENSUS_TAG_BINARY)
-
-typedef struct {
-  int n_propagated_tags;        /* number of propagated printable tags */
-  int n_propagated_binary_tags; /* number of propagated binary tags */
-  int n_local_tags;             /* number of non-propagated (local) tags */
-  int n_deleted_tags;           /* number of tags that were deleted */
-  int n_added_tags;             /* number of tags that were added */
-  int n_modified_tags;          /* number of tags that were modified */
-  int n_invalid_tags;           /* number of tags with bad keys or values (e.g.
-                                   longer than CENSUS_MAX_TAG_KV_LEN) */
-  int n_ignored_tags;           /* number of tags ignored because of
-                                   CENSUS_MAX_PROPAGATED_TAGS limit. */
-} census_tag_set_create_status;
-
-/* Create a new tag set, adding and removing tags from an existing tag set.
-   This will copy all tags from it's input parameters, so it is recommended
-   to add as many tags in a single operation as is practical for the client.
-   @param base Base tag set to build upon. Can be NULL.
-   @param tags A set of tags to be added/changed/deleted. Tags with keys that
-   are in 'tags', but not 'base', are added to the tag set. Keys that are in
-   both 'tags' and 'base' will have their value/flags modified. Tags with keys
-   in both, but with NULL or zero-length values, will be deleted from the tag
-   set. 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.
-   @param ntags number of tags in 'tags'
-   @param status If not NULL, will return a pointer to a
-   census_tag_set_create_status structure containing information about the new
-   tag set and status of the tags used in its creation.
-   @return A new, valid census_tag_set.
-*/
-census_tag_set *census_tag_set_create(
-    const census_tag_set *base, const census_tag *tags, int ntags,
-    census_tag_set_create_status const **status);
-
-/* Destroy a tag set created by census_tag_set_create(). Once this function
-   has been called, the tag set cannot be reused. */
-void census_tag_set_destroy(census_tag_set *tags);
-
-/* Get a pointer to the original status from the creation of this tag set. */
-const census_tag_set_create_status *census_tag_set_get_create_status(
-    const census_tag_set *tags);
-
-/* Structure used for tag set iteration. API clients should not use or
-   reference internal fields - neither their contents or presence/absence are
-   guaranteed. */
-typedef struct {
-  const census_tag_set *tags;
-  int base;
-  int index;
-  char *kvm;
-} census_tag_set_iterator;
-
-/* Initialize a tag set iterator. Must be called before first use of the
-   iterator. */
-void census_tag_set_initialize_iterator(const census_tag_set *tags,
-                                        census_tag_set_iterator *iterator);
-
-/* Get the contents of the "next" tag in the tag set. If there are no more
-   tags in the tag set, returns 0 (and 'tag' contents will be unchanged),
-   otherwise returns 1. */
-int census_tag_set_next_tag(census_tag_set_iterator *iterator, census_tag *tag);
-
-/* Get a tag by its key. Returns 0 if the key is not present in the tag
-   set. */
-int census_tag_set_get_tag_by_key(const census_tag_set *tags, const char *key,
-                                  census_tag *tag);
-
-/* Tag set encode/decode functionality. These functionas are intended
-   for use by RPC systems only, for purposes of transmitting/receiving tag
-   sets. */
-
-/* Encode a tag set into a buffer. The propagated tags are encoded into the
-   buffer in two regions: one for printable tags, and one for binary tags.
-   @param tags tag set to be encoded
-   @param buffer pointer to buffer. This address will be used to encode the
-                 printable tags.
-   @param buf_size number of available bytes in buffer.
-   @param print_buf_size Will be set to the number of bytes consumed by
-                         printable tags.
-   @param bin_buf_size Will be set to the number of bytes used to encode the
-                       binary tags.
-   @return A pointer to the binary tag's encoded, or NULL if the buffer was
-           insufficiently large to hold the encoded tags. Thus, if successful,
-           printable tags are encoded into
-           [buffer, buffer + *print_buf_size) and binary tags into
-           [returned-ptr, returned-ptr + *bin_buf_size) (and the return value
-           should be buffer + *print_buf_size) */
-char *census_tag_set_encode(const census_tag_set *tags, char *buffer,
-                            size_t buf_size, size_t *print_buf_size,
-                            size_t *bin_buf_size);
-
-/* Decode tag set buffers encoded with census_tag_set_encode_*(). Returns NULL
-   if there is an error in parsing either buffer. */
-census_tag_set *census_tag_set_decode(const char *buffer, size_t size,
-                                      const char *bin_buffer, size_t bin_size);
-
-/* Get a contexts tag set. */
-census_tag_set *census_context_tag_set(census_context *context);
-
 /* Core stats collection API's. The following concepts are used:
    * Aggregation: A collection of values. Census supports the following
        aggregation types:
@@ -506,8 +485,8 @@ extern census_aggregation_ops census_agg_window;
     construction via census_define_view(). */
 typedef struct {
   const census_aggregation_ops *ops;
-  const void *
-      create_arg; /* Argument to be used for aggregation initialization. */
+  const void
+      *create_arg; /* Argument to be used for aggregation initialization. */
 } census_aggregation;
 
 /** A census view type. Opaque. */
@@ -515,13 +494,15 @@ typedef struct census_view census_view;
 
 /** Create a new view.
   @param metric_id Metric with which this view is associated.
-  @param tags tags that define the view
+  @param tags tags that define the view.
   @param aggregations aggregations to associate with the view
   @param naggregations number of aggregations
 
   @return A new census view
 */
-census_view *census_view_create(uint32_t metric_id, const census_tag_set *tags,
+/* TODO(aveitch): consider if context is the right argument type to pass in
+   tags. */
+census_view *census_view_create(uint32_t metric_id, const census_context *tags,
                                 const census_aggregation *aggregations,
                                 size_t naggregations);
 
@@ -535,7 +516,7 @@ size_t census_view_metric(const census_view *view);
 size_t census_view_naggregations(const census_view *view);
 
 /** Get tags associated with view. */
-const census_tag_set *census_view_tags(const census_view *view);
+const census_context *census_view_tags(const census_view *view);
 
 /** Get aggregation descriptors associated with a view. */
 const census_aggregation *census_view_aggregrations(const census_view *view);
@@ -543,7 +524,7 @@ const census_aggregation *census_view_aggregrations(const census_view *view);
 /** Holds all the aggregation data for a particular view instantiation. Forms
   part of the data returned by census_view_data(). */
 typedef struct {
-  const census_tag_set *tags; /* Tags for this set of aggregations. */
+  const census_context *tags; /* Tags for this set of aggregations. */
   const void **data; /* One data set for every aggregation in the view. */
 } census_view_aggregation_data;