diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/grpc/census.h | 102 |
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. */ |