pceplib/pcep_utils_counters.h

   1 // SPDX-License-Identifier: LGPL-2.1-or-later
   2 /*
   3  * This file is part of the PCEPlib, a PCEP protocol library.
   4  *
   5  * Copyright (C) 2020 Volta Networks https://voltanet.io/
   6  *
   7  * Author : Brady Johnson <brady@voltanet.io>
   8  *
   9  */
  10
  11
  12 /*
  13  * Definitions of PCEP Counters.
  14  */
  15
  16 #ifndef PCEP_UTILS_INCLUDE_PCEP_UTILS_COUNTERS_H_
  17 #define PCEP_UTILS_INCLUDE_PCEP_UTILS_COUNTERS_H_
  18
  19 #include <stdbool.h>
  20 #include <stdint.h>
  21 #include <time.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /*
  28  * Example Counter group with sub-groups and counters
  29  *
  30  *  pcep_counters {
  31  *      counters_group_rx {
  32  *          message_open;
  33  *          message_keepalive;
  34  *          message_pcreq;
  35  *      }
  36  *      counters_group_tx {
  37  *          message_open;
  38  *          message_keepalive;
  39  *          message_pcreq;
  40  *      }
  41  *      counters_group_events {
  42  *          pcc_connect;
  43  *          pce_connect;
  44  *          pcc_disconnect;
  45  *          pce_disconnect;
  46  *      }
  47  *  }
  48  *
  49  * To create the above structure of groups, sub-groups, and counters, do the
  50  * following:
  51  *
  52  * struct counters_subgroup *rx_subgroup = create_counters_subgroup("rx
  53  * counters", 3); struct counters_subgroup *tx_subgroup =
  54  * create_counters_subgroup("tx counters", 3); struct counters_subgroup
  55  * *events_subgroup = create_counters_subgroup("events counters", 4);
  56  *
  57  * Use message_id: PCEP_TYPE_OPEN=1
  58  * create_subgroup_counter(rx_subgroup, 1, "Message Open");
  59  * create_subgroup_counter(rx_subgroup, 2, "Message KeepAlive");
  60  * create_subgroup_counter(rx_subgroup, 3, "Message PcReq");
  61  *
  62  * create_subgroup_counter(tx_subgroup, 1, "Message Open");
  63  * create_subgroup_counter(tx_subgroup, 2, "Message KeepAlive");
  64  * create_subgroup_counter(tx_subgroup, 3, "Message PcReq");
  65  *
  66  * create_subgroup_counter(events_subgroup, 1, "PCC Connect");
  67  * create_subgroup_counter(events_subgroup, 2, "PCE Connect");
  68  * create_subgroup_counter(events_subgroup, 3, "PCC Disconnect");
  69  * create_subgroup_counter(events_subgroup, 4, "PCE Disconnect");
  70  *
  71  * struct counters_group *cntrs_group = create_counters_group("PCEP Counters",
  72  * 3); add_counters_subgroup(cntrs_group, rx_subgroup);
  73  * add_counters_subgroup(cntrs_group, tx_subgroup);
  74  * add_counters_subgroup(cntrs_group, events_subgroup);
  75  */
  76
  77 #define MAX_COUNTER_STR_LENGTH 128
  78 #define MAX_COUNTER_GROUPS 500
  79 #define MAX_COUNTERS 500
  80
  81 struct counter {
  82         uint16_t counter_id;
  83         char counter_name[MAX_COUNTER_STR_LENGTH];
  84         uint32_t counter_value;
  85 };
  86
  87 struct counters_subgroup {
  88         char counters_subgroup_name[MAX_COUNTER_STR_LENGTH];
  89         uint16_t subgroup_id;
  90         uint16_t num_counters;
  91         uint16_t max_counters;
  92         /* Array of (struct counter *) allocated when the subgroup is created.
  93          * The array is indexed by the struct counter->counter_id */
  94         struct counter **counters;
  95 };
  96
  97 struct counters_group {
  98         char counters_group_name[MAX_COUNTER_STR_LENGTH];
  99         uint16_t num_subgroups;
 100         uint16_t max_subgroups;
 101         time_t start_time;
 102         /* Array  of (struct counters_subgroup *) allocated when the group is
 103          * created. The subgroup is indexed by the (struct counters_subgroup
 104          * *)->subgroup_id */
 105         struct counters_subgroup **subgroups;
 106 };
 107
 108 /*
 109  * Create a counters group with the given group_name and number of subgroups.
 110  * Subgroup_ids are 0-based, so take that into account when setting
 111  * max_subgroups. Return true on success or false if group_name is NULL or
 112  * max_subgroups >= MAX_COUNTER_GROUPS.
 113  */
 114 struct counters_group *create_counters_group(const char *group_name,
 115                                              uint16_t max_subgroups);
 116
 117 /*
 118  * Create a counters subgroup with the given subgroup_name, subgroup_id and
 119  * number of counters. The subgroup_id is 0-based. counter_ids are 0-based, so
 120  * take that into account when setting max_counters. Return true on success or
 121  * false if subgroup_name is NULL, subgroup_id >= MAX_COUNTER_GROUPS, or
 122  * max_counters >= MAX_COUNTERS.
 123  */
 124 struct counters_subgroup *create_counters_subgroup(const char *subgroup_name,
 125                                                    uint16_t subgroup_id,
 126                                                    uint16_t max_counters);
 127
 128 /*
 129  * Add a counter_subgroup to a counter_group.
 130  * Return true on success or false if group is NULL or if subgroup is NULL.
 131  */
 132 bool add_counters_subgroup(struct counters_group *group,
 133                            struct counters_subgroup *subgroup);
 134
 135 /*
 136  * Clone a subgroup and set a new name and subgroup_id for the new subgroup.
 137  * This is useful for RX and TX counters: just create the RX counters and clone
 138  * it for the TX counters.
 139  */
 140 struct counters_subgroup *
 141 clone_counters_subgroup(struct counters_subgroup *subgroup,
 142                         const char *subgroup_name, uint16_t subgroup_id);
 143
 144 /*
 145  * Create a counter in a subgroup with the given counter_id and counter_name.
 146  * The counter_id is 0-based.
 147  * Return true on success or false if subgroup is NULL, counter_id >=
 148  * MAX_COUNTERS, or if counter_name is NULL.
 149  */
 150 bool create_subgroup_counter(struct counters_subgroup *subgroup,
 151                              uint32_t counter_id, const char *counter_name);
 152
 153 /*
 154  * Delete the counters_group and recursively delete all subgroups and their
 155  * counters. Return true on success or false if group is NULL.
 156  */
 157 bool delete_counters_group(struct counters_group *group);
 158
 159 /*
 160  * Delete the counters_subgroup and all its counters counters.
 161  * Return true on success or false if subgroup is NULL.
 162  */
 163 bool delete_counters_subgroup(struct counters_subgroup *subgroup);
 164
 165 /*
 166  * Reset all the counters in all sub-groups contained in this group.
 167  * Return true on success or false if group is NULL.
 168  */
 169 bool reset_group_counters(struct counters_group *group);
 170
 171 /*
 172  * Reset all the counters in this subgroup.
 173  * Return true on success or false if subgroup is NULL.
 174  */
 175 bool reset_subgroup_counters(struct counters_subgroup *subgroup);
 176
 177 /*
 178  * Increment a counter given a counter_group, subgroup_id, and counter_id.
 179  * Return true on success or false if group is NULL, subgroup_id >=
 180  * MAX_COUNTER_GROUPS, or counter_id >= MAX_COUNTERS.
 181  */
 182 bool increment_counter(struct counters_group *group, uint16_t subgroup_id,
 183                        uint16_t counter_id);
 184
 185 /*
 186  * Increment a counter given the counter_subgroup and counter_id.
 187  * Return true on success or false if subgroup is NULL or counter_id >=
 188  * MAX_COUNTERS.
 189  */
 190 bool increment_subgroup_counter(struct counters_subgroup *subgroup,
 191                                 uint16_t counter_id);
 192
 193 /*
 194  * Dump the counter_group info and all its counter_subgroups.
 195  * Return true on success or false if group is NULL.
 196  */
 197 bool dump_counters_group_to_log(struct counters_group *group);
 198
 199 /*
 200  * Dump all the counters in a counter_subgroup.
 201  * Return true on success or false if subgroup is NULL.
 202  */
 203 bool dump_counters_subgroup_to_log(struct counters_subgroup *subgroup);
 204
 205 /*
 206  * Search for a counters_subgroup by subgroup_id in a counters_group
 207  * and return it, if found, else return NULL.
 208  */
 209 struct counters_subgroup *find_subgroup(const struct counters_group *group,
 210                                         uint16_t subgroup_id);
 211
 212 /*
 213  * Given a counters_subgroup, return the sum of all the counters.
 214  */
 215 uint32_t subgroup_counters_total(struct counters_subgroup *subgroup);
 216
 217 #ifdef __cplusplus
 218 }
 219 #endif
 220
 221 #endif /* PCEP_UTILS_INCLUDE_PCEP_UTILS_COUNTERS_H_ */