initial commit

1 files changed, 56 insertions, 46 deletions

diff --git a/include/grpc/census.h b/include/grpc/census.h
index d0bc90420c..b127669694 100644
--- a/include/grpc/census.h
+++ b/include/grpc/census.h
@@ -324,60 +324,70 @@ 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();
 
-/* Max number of characters in tag key */
-#define CENSUS_MAX_TAG_KEY_LENGTH 20
-/* Max number of tag value characters */
-#define CENSUS_MAX_TAG_VALUE_LENGTH 50
-
 /* 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;
 
-/* Returns a pointer to a newly created, empty tag set. If size_hint > 0,
-   indicates that the tag set is intended to hold approximately that number
-   of tags. */
-census_tag_set *census_tag_set_create(size_t size_hint);
-
-/* Add a new tag key/value to an existing tag set; if the tag key already exists
-   in the tag set, then its value is overwritten with the new one. Can also be
-   used to delete a tag, by specifying a NULL value. If key is NULL, returns
-   the number of tags in the tag set.
-   Return values:
-   -1: invalid length key or value
-   non-negative value: the number of tags in the tag set. */
-int census_tag_set_add(census_tag_set *tags, const char *key,
-                       const char *value);
-
-/* Destroys a tag set. This function must be called to prevent memory leaks.
-   Once called, the tag set cannot be used again. */
-void census_tag_set_destroy(census_tag_set *tags);
-
-/* Get a contexts tag set. */
-census_tag_set *census_context_tag_set(census_context *context);
-
-/* A read-only representation of a tag for use by census clients. */
+/* A tag is a key:value pair. The key is a printable, nil-terminate
+   string. The value is a binary string, that may be printable. There are no
+   limits on the sizes of either keys or values, but code authors should
+   remember that systems may have inbuilt limits (e.g. for propagated tags,
+   the bytes on the wire) and that larger tags means more memory consumed and
+   time in processing. */
 typedef struct {
-  size_t key_len;    /* Number of bytes in tag key. */
-  const char *key;   /* A pointer to the tag key. May not be null-terminated. */
-  size_t value_len;  /* Number of bytes in tag value. */
-  const char *value; /* Pointer to the tag value. May not be null-terminated. */
-} census_tag_const;
+  const char *key;
+  const char *value;
+  size_t value_len;
+  gpr_uint8 flags;
+} census_tag;
+
+/* 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)
+
+#define CENSUS_MAX_TAG_KV_LEN 255 /* Maximum length of key/value in a tag. */
+#define CENSUS_MAX_TAGS 255       /* Maximum number of tags in a tag set. */
+
+/* Create a new tag set, adding and removing tags from an existing tag set.
+   @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 replaced. Tags with keys in
+   both, but with NULL or zero-length values, will be deleted from the
+   tag set.
+   @param ntags number of tags in 'tags'
+*/
+census_tag_set *census_tag_set_create(const census_tag_set *base,
+                                      const census_tag *tags, int ntags);
+
+/* 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);
 
-/* Used to iterate through a tag sets contents. */
-typedef struct census_tag_set_iterator census_tag_set_iterator;
+/* Get the number of tags in the tag set. */
+int census_tag_set_ntags(const census_tag_set *tags);
 
-/* Open a tag set for iteration. The tag set must not be modified while
-   iteration is ongoing. Returns an iterator for use in following functions. */
-census_tag_set_iterator *census_tag_set_open(census_tag_set *tags);
+/* Get a tag by it's index in the tag set. Returns 0 if the index is invalid
+   (<0 or >= census_tag_set_ntags). There is no guarantee on tag ordering. */
+int census_tag_set_get_tag_by_index(const census_tag_set *tags, int index,
+                                    census_tag *tag);
 
-/* Get the next tag in the tag set, by writing into the 'tag' argument. Returns
-   1 if there is a "next" tag, 0 if there are no more tags. */
-int census_tag_set_next(census_tag_set_iterator *it, census_tag_const *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);
 
-/* Close an iterator opened by census_tag_set_open(). The iterator will be
-   invalidated, and should not be used once close is called. */
-void census_tag_set_close(census_tag_set_iterator *it);
+/* 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
@@ -424,8 +434,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. */