|
|
|
|
@ -159,114 +159,154 @@ int census_tag_set_next(census_tag_set_iterator *it, census_tag_const *tag); |
|
|
|
|
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. */ |
|
|
|
|
/* Core stats collection API's. There following concepts are used:
|
|
|
|
|
* Aggregation: A collection of values. Census supports the following |
|
|
|
|
aggregation types: |
|
|
|
|
Scalar - a single scalar value. Typically used for keeping (e.g.) |
|
|
|
|
counts of events. |
|
|
|
|
Distribution - statistical distribution information, used for |
|
|
|
|
recording average, standard deviation etc. |
|
|
|
|
Histogram - a histogram of measurements falling in defined bucket |
|
|
|
|
boundaries. |
|
|
|
|
Window - a count of events that happen in reolling time window. |
|
|
|
|
New aggregation types can be added by the user, if desired (see |
|
|
|
|
census_register_aggregation()). |
|
|
|
|
* Metric: Each measurement is for a single metric. Examples include RPC |
|
|
|
|
latency, CPU seconds consumed, and bytes transmitted. |
|
|
|
|
* View: A view is a tag set, in which the tag values are regular expressions, |
|
|
|
|
combined with an arbitrary number of aggregations and their initialization |
|
|
|
|
parameters. |
|
|
|
|
|
|
|
|
|
Each metric can have an arbitrary number of views by which it will be |
|
|
|
|
broken down. For every measurement recorded, they are broken down by |
|
|
|
|
unique tag combinations, and recorded in each matvhing view/aggregation. |
|
|
|
|
*/ |
|
|
|
|
|
|
|
|
|
/* A single value to be recorded comprises two parts: an ID for the particular
|
|
|
|
|
* metric and the value to be recorded against it. */ |
|
|
|
|
typedef struct { |
|
|
|
|
int id; |
|
|
|
|
gpr_int32 metric_id; |
|
|
|
|
double value; |
|
|
|
|
} census_stat; |
|
|
|
|
} census_value; |
|
|
|
|
|
|
|
|
|
/* Record new usage values against the given context. */ |
|
|
|
|
void census_record_usage(census_context *context, census_value *values, |
|
|
|
|
size_t nvalues); |
|
|
|
|
|
|
|
|
|
/** Structure used to describe an aggregation type. */ |
|
|
|
|
typedef struct { |
|
|
|
|
/* Create a new aggregation. The pointer returned can be used in future calls
|
|
|
|
|
to free(), record(), data() and reset(). */ |
|
|
|
|
void *(*create)(const void *create_arg); |
|
|
|
|
/* Destroy an aggregation created by create() */ |
|
|
|
|
void (*free)(void *aggregation); |
|
|
|
|
/* Record a new value against aggregation. */ |
|
|
|
|
void (*record)(void *aggregation, double value); |
|
|
|
|
/* Return current aggregation data. The caller must cast this object into
|
|
|
|
|
the correct type for the aggregation result. The object returned can be |
|
|
|
|
freed by using free_data(). */ |
|
|
|
|
const void *(*data)(const void *aggregation); |
|
|
|
|
/* destroy an aggregation result eturned from get_aggregation(). */ |
|
|
|
|
void (*free_data)(const void *data); |
|
|
|
|
/* Reset an aggregation to default (zero) values. */ |
|
|
|
|
void (*reset)(void *aggregation); |
|
|
|
|
} census_aggregation_descriptor; |
|
|
|
|
|
|
|
|
|
/** Register a new aggregation type.
|
|
|
|
|
@param descriptor Describes aggregation |
|
|
|
|
@return An identifier that can be used to identify the aggregation in other |
|
|
|
|
census functions. */ |
|
|
|
|
gpr_int32 census_register_aggregation( |
|
|
|
|
const census_aggregation_descriptor *descriptor); |
|
|
|
|
|
|
|
|
|
/* Aggregation Identifiers for built-in census aggregations. */ |
|
|
|
|
#define CENSUS_AGGREGATION_ID_SCALAR ((gpr_int32)0) |
|
|
|
|
#define CENSUS_AGGREGATION_ID_DISTRIBUTION ((gpr_int32)1) |
|
|
|
|
#define CENSUS_AGGREGATION_ID_HISTOGRAM ((gpr_int32)2) |
|
|
|
|
#define CENSUS_AGGREGATION_ID_WINDOW ((gpr_int32)3) |
|
|
|
|
|
|
|
|
|
/** Information needed to instantiate a new aggregation. Used in view
|
|
|
|
|
construction via census_define_view(). */ |
|
|
|
|
typedef struct { |
|
|
|
|
gpr_int32 id; /* aggregation ID */ |
|
|
|
|
const void |
|
|
|
|
*create_arg; /* Argument to be used for aggregation initialization. */ |
|
|
|
|
} census_aggregation; |
|
|
|
|
|
|
|
|
|
/* Record new stats against the given context. */ |
|
|
|
|
void census_record_stat(census_context *context, census_stat *stats, |
|
|
|
|
size_t nstats); |
|
|
|
|
/** Type representing a single view. */ |
|
|
|
|
typedef struct census_view census_view; |
|
|
|
|
|
|
|
|
|
/* Stats Configuration - Census clients can use these functions and structures
|
|
|
|
|
to extend and define what stats get recorded for what measurements. */ |
|
|
|
|
/** Create a new view.
|
|
|
|
|
@param tags tags that define the view |
|
|
|
|
@param aggregations aggregations to associate with the view |
|
|
|
|
@param naggregations number of aggregations |
|
|
|
|
|
|
|
|
|
/** Stats types supported by census. */ |
|
|
|
|
typedef enum { |
|
|
|
|
CENSUS_STAT_SCALAR = 0, /* Simple scalar */ |
|
|
|
|
CENSUS_STAT_DISTRIBUTION = 1, /* count, average, variance */ |
|
|
|
|
CENSUS_STAT_HISTOGRAM = 2, /* Histogram. */ |
|
|
|
|
CENSUS_STAT_WINDOW = 3, /* Count over a time window. */ |
|
|
|
|
CENSUS_STAT_NSTATS = 4 /* Total number of stats types. */ |
|
|
|
|
} census_stat_type; |
|
|
|
|
@return A new census view |
|
|
|
|
*/ |
|
|
|
|
const census_view *census_define_view(const census_tag_set *tags, |
|
|
|
|
const census_aggregation *aggregations, |
|
|
|
|
size_t naggregations); |
|
|
|
|
|
|
|
|
|
/*
|
|
|
|
|
Each stats type differs in how it is initialized, how it is represented, and |
|
|
|
|
the results it provides. The following structures allow us to use a generic |
|
|
|
|
type for each of those. |
|
|
|
|
|
|
|
|
|
Types referenced (one for each stat type in census_stat_type, by creation |
|
|
|
|
arguments, output blob, and object representation. */ |
|
|
|
|
|
|
|
|
|
typedef struct census_stat_scalar_create_arg census_stat_scalar_create_arg; |
|
|
|
|
typedef struct census_stat_distribution_create_arg |
|
|
|
|
census_stat_distribution_create_arg; |
|
|
|
|
typedef struct census_stat_histogram_create_arg |
|
|
|
|
census_stat_histogram_create_arg; |
|
|
|
|
typedef struct census_stat_window_create_arg census_stat_window_create_arg; |
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Type for representing information to construct a new instance of a given |
|
|
|
|
stats type (e.g. histogram bucket boundaries). |
|
|
|
|
/** Number of aggregations associated with 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); |
|
|
|
|
|
|
|
|
|
/** Get aggregations associated with a view. */ |
|
|
|
|
const census_aggregation *census_view_aggregrations(const census_view *view); |
|
|
|
|
|
|
|
|
|
/** Associate a given view with a metric. Every metric can have many different
|
|
|
|
|
views. |
|
|
|
|
@param metric_id Identifier of metric with which to attah the view |
|
|
|
|
@param view View to attach to the metric |
|
|
|
|
@return A view identifier: can be used to retrieve aggregation data from |
|
|
|
|
the view using census_view_data(). |
|
|
|
|
*/ |
|
|
|
|
gpr_int64 census_attach_view(gpr_int32 metric_id, const census_view *view); |
|
|
|
|
|
|
|
|
|
/** Holds aggregation data, as it applies to a particular view. This structure
|
|
|
|
|
is used as one component of the data returned from census_get_view_data(). */ |
|
|
|
|
typedef struct { |
|
|
|
|
census_stat_type stat_type; /* The "real" type of the stat. */ |
|
|
|
|
union { |
|
|
|
|
const census_stat_scalar_create_arg *scalar_arg; |
|
|
|
|
const census_stat_distribution_create_arg *distribution_arg; |
|
|
|
|
const census_stat_histogram_create_arg *histogram_arg; |
|
|
|
|
const census_stat_window_create_arg *window_arg; |
|
|
|
|
} |
|
|
|
|
} census_stat_create_arg; |
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Type for representing a single stats result. */ |
|
|
|
|
/** Aggregation index in original view. Use as (e.g.)
|
|
|
|
|
census_view_aggregations(view)[index] to get the original |
|
|
|
|
census_aggregation structure. */ |
|
|
|
|
size_t index; |
|
|
|
|
/** Data as returned from the data() function for the relevant
|
|
|
|
|
aggregation descriptor. It is the user responsibility to cast this to the |
|
|
|
|
correct type for the aggregation. */ |
|
|
|
|
void *data; |
|
|
|
|
} census_aggregation_data; |
|
|
|
|
|
|
|
|
|
/** Holds all the aggregation data for a particular view instantiation. Forms
|
|
|
|
|
part of the data returned by census_get_view_data(). */ |
|
|
|
|
typedef struct { |
|
|
|
|
const census_tag_set *view; /* Unique tags associated with this result. */ |
|
|
|
|
census_stat_type stat_type; |
|
|
|
|
union { |
|
|
|
|
const census_stat_scalar_result *scalar_result; |
|
|
|
|
const census_stat_distribution_result *distribution_result; |
|
|
|
|
const census_stat_histogram_result *histogram_result; |
|
|
|
|
const census_stat_window_result *window_result; |
|
|
|
|
} |
|
|
|
|
} census_stat_result; |
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Generic type for representing a stat "object". |
|
|
|
|
*/ |
|
|
|
|
typdef struct { |
|
|
|
|
census_stat_type stat_type; |
|
|
|
|
union { |
|
|
|
|
census_stat_scalar *scalar; |
|
|
|
|
census_stat_distribution *distribution; |
|
|
|
|
census_stat_histogram *histogram; |
|
|
|
|
census_stat_window *window; |
|
|
|
|
} |
|
|
|
|
} census_stat; |
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
Structure holding function pointers and associated information needed to |
|
|
|
|
manipulate a statstics "object". Every stats type must provide an instance |
|
|
|
|
of this structure. */ |
|
|
|
|
const census_tag_set *tags; /* Tags for this set of aggregations */ |
|
|
|
|
size_t naggregations; /* Number of aggregations in data. */ |
|
|
|
|
const census_aggregation_data *data; /* Aggregation data */ |
|
|
|
|
} census_view_aggregation_data; |
|
|
|
|
|
|
|
|
|
/** Census view data as returned by census_get_view_data(). */ |
|
|
|
|
typedef struct { |
|
|
|
|
/* Create a new statistic. The pointer returned can be used in future calls
|
|
|
|
|
to clone_stat(), destroy_stat(), record_stat() and get_stats(). */ |
|
|
|
|
(census_stat *) (*create_stat)(const census_stat_create_arg *create_arg); |
|
|
|
|
/* Create a new statistic, using an existing one as base. */ |
|
|
|
|
(census_stat *) (*clone_stat)(const census_stat *stat); |
|
|
|
|
/* destroy a stats object created by {create,clone}_stat(). */ |
|
|
|
|
(void) (*destroy_stat)(census_stat *stat); |
|
|
|
|
/* Record a new value against a given statistics object instance. */ |
|
|
|
|
(void) (*record_stat)(census_stat *stat, double value); |
|
|
|
|
/* Return current state of a stat. The object returned can be freed by
|
|
|
|
|
using destroy_stats_result(). */ |
|
|
|
|
(const census_stat_result *) (*get_stat)(const census_stat *stat); |
|
|
|
|
/* destroy a stats result object, as returned from get_stat(). */ |
|
|
|
|
(void) (*destroy_stats_result)(census_stat_result *result); |
|
|
|
|
/* Reset a stats values. */ |
|
|
|
|
(void) (*reset_stat)(census_stat *stat); |
|
|
|
|
} census_stat; |
|
|
|
|
|
|
|
|
|
gpr_int32 census_define_view(const census_tag_set *view); |
|
|
|
|
|
|
|
|
|
gpr_int32 census_define_stat(gpr_int32 metric_id, gpr_int32 view_id, |
|
|
|
|
const census_stat *stat, |
|
|
|
|
const census_stat_create_arg *create_arg); |
|
|
|
|
|
|
|
|
|
census_stat_result *census_get_stat(gpr_int32 stat_id, gpr_int32 *nstats); |
|
|
|
|
const census_view *view; /* Original view */ |
|
|
|
|
size_t n_tag_sets; /* Number of unique tag sets that matched view. */ |
|
|
|
|
const census_view_aggregation_data *data; /* n_tag_sets entries */ |
|
|
|
|
} census_view_data; |
|
|
|
|
|
|
|
|
|
/** Get data from aggregations associated with a view.
|
|
|
|
|
@param view_id View identifier returned from census_attach_view |
|
|
|
|
@param aggregation_indices Indexes of aggregations (relative to original view) |
|
|
|
|
for which to return current data. This parameter is ignored if |
|
|
|
|
nindices == 0. |
|
|
|
|
@param nindices. Number of entries in aggregation_indices. If this is set to |
|
|
|
|
0, then all aggregations for the current view are returned. |
|
|
|
|
*/ |
|
|
|
|
const census_view_data *census_get_view_data(gpr_int64 view_id, |
|
|
|
|
size_t *aggregation_indices, |
|
|
|
|
size_t nindices); |
|
|
|
|
|
|
|
|
|
/** Reset all view data to zero for the specified view id. */ |
|
|
|
|
void census_reset_view_data(gpr_int64 view_id); |
|
|
|
|
|
|
|
|
|
#ifdef __cplusplus |
|
|
|
|
} |
|
|
|
|
|
Alistair Veitch
9 years ago