view and aggregation API

1 files changed, 138 insertions, 98 deletions

diff --git a/include/grpc/census.h b/include/grpc/census.h
index db3e89685a..968f5825a5 100644
--- a/include/grpc/census.h
+++ b/include/grpc/census.h
@@ -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
 }