mirror of
https://fuchsia.googlesource.com/third_party/grpc
synced 2024-09-20 19:36:13 +00:00
8d428f1e6d
add external tag set API
178 lines
7.5 KiB
C
178 lines
7.5 KiB
C
/*
|
|
*
|
|
* Copyright 2015, Google Inc.
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are
|
|
* met:
|
|
*
|
|
* * Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* * Redistributions in binary form must reproduce the above
|
|
* copyright notice, this list of conditions and the following disclaimer
|
|
* in the documentation and/or other materials provided with the
|
|
* distribution.
|
|
* * Neither the name of Google Inc. nor the names of its
|
|
* contributors may be used to endorse or promote products derived from
|
|
* this software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
*/
|
|
|
|
/* RPC-internal Census API's. These are designed to be generic enough that
|
|
* they can (ultimately) be used in many different RPC systems (with differing
|
|
* implementations). */
|
|
|
|
#ifndef CENSUS_CENSUS_H
|
|
#define CENSUS_CENSUS_H
|
|
|
|
#include <grpc/grpc.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* Identify census features that can be enabled via census_initialize(). */
|
|
enum census_features {
|
|
CENSUS_FEATURE_NONE = 0, /* Do not enable census. */
|
|
CENSUS_FEATURE_TRACING = 1, /* Enable census tracing. */
|
|
CENSUS_FEATURE_STATS = 2, /* Enable Census stats collection. */
|
|
CENSUS_FEATURE_CPU = 4, /* Enable Census CPU usage collection. */
|
|
CENSUS_FEATURE_ALL =
|
|
CENSUS_FEATURE_TRACING | CENSUS_FEATURE_STATS | CENSUS_FEATURE_CPU
|
|
};
|
|
|
|
/** Shutdown and startup census subsystem. The 'features' argument should be
|
|
* the OR (|) of census_features values. If census fails to initialize, then
|
|
* census_initialize() will return a non-zero value. It is an error to call
|
|
* census_initialize() more than once (without an intervening
|
|
* census_shutdown()). */
|
|
int census_initialize(int features);
|
|
void census_shutdown(void);
|
|
|
|
/** Return the features supported by the current census implementation (not all
|
|
* features will be available on all platforms). */
|
|
int census_supported(void);
|
|
|
|
/** Return the census features currently enabled. */
|
|
int census_enabled(void);
|
|
|
|
/* Internally, Census relies on a context, which should be propagated across
|
|
* RPC's. From the RPC subsystems viewpoint, this is an opaque data structure.
|
|
* A context must be used as the first argument to all other census
|
|
* functions. Conceptually, contexts should be thought of as specific to
|
|
* single RPC/thread. The context can be serialized for passing across the
|
|
* wire. */
|
|
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);
|
|
|
|
/* Create a new census context, possibly from a serialized buffer. If 'buffer'
|
|
* is non-NULL, it is assumed that it is a buffer encoded by
|
|
* census_context_serialize(). If `buffer` is NULL, a new, empty context is
|
|
* created. The decoded/new contest is returned in 'context'.
|
|
*
|
|
* Returns 0 if no errors, non-zero if buffer is incorrectly formatted, in
|
|
* which case a new empty context will be returned. */
|
|
int census_context_deserialize(const char *buffer, census_context **context);
|
|
|
|
/* The given context is destroyed. Once destroyed, using the context in
|
|
* future census calls will result in undefined behavior. */
|
|
void census_context_destroy(census_context *context);
|
|
|
|
/* 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. */
|
|
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;
|
|
|
|
/* Used to iterate through a tag sets contents. */
|
|
typedef struct census_tag_set_iterator census_tag_set_iterator;
|
|
|
|
/* 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 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);
|
|
|
|
/* 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);
|
|
|
|
/* A census statistic to be recorded comprises two parts: an ID for the
|
|
* particular statistic and the value to be recorded against it. */
|
|
typedef struct {
|
|
int id;
|
|
double value;
|
|
} census_stat;
|
|
|
|
/* Record new stats against the given context. */
|
|
void census_record_stat(census_context *context, census_stat *stats,
|
|
size_t nstats);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* CENSUS_CENSUS_H */
|