Brian O'Connor | c67f9fa | 2014-08-07 18:17:46 -0700 | [diff] [blame] | 1 | package net.floodlightcontroller.debugcounter; |
| 2 | |
| 3 | import net.floodlightcontroller.core.module.IFloodlightService; |
| 4 | import net.floodlightcontroller.debugcounter.DebugCounter.DebugCounterInfo; |
| 5 | |
| 6 | import java.util.List; |
| 7 | |
| 8 | public interface IDebugCounterService extends IFloodlightService { |
| 9 | |
| 10 | /** |
| 11 | * Different counter types. Counters that are meant to be counted-on-demand |
| 12 | * need to be separately enabled/disabled. |
| 13 | */ |
| 14 | public enum CounterType { |
| 15 | ALWAYS_COUNT, |
| 16 | COUNT_ON_DEMAND |
| 17 | } |
| 18 | |
| 19 | /** |
| 20 | * Debug Counter Qualifiers |
| 21 | */ |
| 22 | public static final String CTR_MDATA_WARN = "warn"; |
| 23 | public static final String CTR_MDATA_ERROR = "error"; |
| 24 | public static final String CTR_MDATA_DROP = "drop"; |
| 25 | |
| 26 | /** |
| 27 | * A limit on the maximum number of counters that can be created |
| 28 | */ |
| 29 | public static final int MAX_COUNTERS = 5000; |
| 30 | |
| 31 | /** |
| 32 | * Exception thrown when MAX_COUNTERS have been registered |
| 33 | */ |
| 34 | public class MaxCountersRegistered extends CounterException { |
| 35 | private static final long serialVersionUID = 3173747663719376745L; |
| 36 | String errormsg; |
| 37 | public MaxCountersRegistered(String errormsg) { |
| 38 | this.errormsg = errormsg; |
| 39 | } |
| 40 | @Override |
| 41 | public String getMessage() { |
| 42 | return this.errormsg; |
| 43 | } |
| 44 | } |
| 45 | /** |
| 46 | * Exception thrown when MAX_HIERARCHY has been reached |
| 47 | */ |
| 48 | public class MaxHierarchyRegistered extends CounterException { |
| 49 | private static final long serialVersionUID = 967431358683523871L; |
| 50 | String errormsg; |
| 51 | public MaxHierarchyRegistered(String errormsg) { |
| 52 | this.errormsg = errormsg; |
| 53 | } |
| 54 | @Override |
| 55 | public String getMessage() { |
| 56 | return this.errormsg; |
| 57 | } |
| 58 | } |
| 59 | /** |
| 60 | * Exception thrown when attempting to register a hierarchical counter |
| 61 | * where higher levels of the hierarchy have not been pre-registered |
| 62 | */ |
| 63 | public class MissingHierarchicalLevel extends CounterException { |
| 64 | private static final long serialVersionUID = 517315311533995739L; |
| 65 | String errormsg; |
| 66 | public MissingHierarchicalLevel(String errormsg) { |
| 67 | this.errormsg = errormsg; |
| 68 | } |
| 69 | @Override |
| 70 | public String getMessage() { |
| 71 | return this.errormsg; |
| 72 | } |
| 73 | } |
| 74 | |
| 75 | public class CounterException extends Exception { |
| 76 | private static final long serialVersionUID = 2219781500857866035L; |
| 77 | } |
| 78 | |
| 79 | /** |
| 80 | * maximum levels of hierarchy |
| 81 | * Example of moduleName/counterHierarchy: |
| 82 | * switch/00:00:00:00:01:02:03:04/pktin/drops where |
| 83 | * moduleName ==> "switch" and |
| 84 | * counterHierarchy of 3 ==> "00:00:00:00:01:02:03:04/pktin/drops" |
| 85 | */ |
| 86 | public static final int MAX_HIERARCHY = 3; |
| 87 | |
| 88 | /** |
| 89 | * All modules that wish to have the DebugCounterService count for them, must |
| 90 | * register their counters by making this call (typically from that module's |
| 91 | * 'startUp' method). The counter can then be updated, displayed, reset etc. |
| 92 | * using the registered moduleName and counterHierarchy. |
| 93 | * |
| 94 | * @param moduleName the name of the module which is registering the |
| 95 | * counter eg. linkdiscovery or controller or switch |
| 96 | * @param counterHierarchy the hierarchical counter name specifying all |
| 97 | * the hierarchical levels that come above it. |
| 98 | * For example: to register a drop counter for |
| 99 | * packet-ins from a switch, the counterHierarchy |
| 100 | * can be "00:00:00:00:01:02:03:04/pktin/drops" |
| 101 | * It is necessary that counters in hierarchical levels |
| 102 | * above have already been pre-registered - in this |
| 103 | * example: "00:00:00:00:01:02:03:04/pktin" and |
| 104 | * "00:00:00:00:01:02:03:04" |
| 105 | * @param counterDescription a descriptive string that gives more information |
| 106 | * of what the counter is measuring. For example, |
| 107 | * "Measures the number of incoming packets seen by |
| 108 | * this module". |
| 109 | * @param counterType One of CounterType. On-demand counter types |
| 110 | * need to be explicitly enabled/disabled using other |
| 111 | * methods in this API -- i.e. registering them is |
| 112 | * not enough to start counting. |
| 113 | * @param metaData variable arguments that qualify a counter |
| 114 | * eg. warn, error etc. |
| 115 | * @return IDebugCounter with update methods that can be |
| 116 | * used to update a counter. |
| 117 | * @throws MaxCountersRegistered |
| 118 | * @throws MaxHierarchyRegistered |
| 119 | * @throws MissingHierarchicalLevel |
| 120 | */ |
| 121 | public IDebugCounter registerCounter(String moduleName, String counterHierarchy, |
| 122 | String counterDescription, CounterType counterType, |
| 123 | String... metaData) |
| 124 | throws MaxCountersRegistered, MaxHierarchyRegistered, |
| 125 | MissingHierarchicalLevel; |
| 126 | |
| 127 | /** |
| 128 | * Flush all thread-local counter values (from the current thread) |
| 129 | * to the global counter store. This method is not intended for use by any |
| 130 | * module. It's typical usage is from floodlight core and it is meant |
| 131 | * to flush those counters that are updated in the packet-processing pipeline, |
| 132 | * typically with the 'updateCounterNoFlush" methods in IDebugCounter. |
| 133 | */ |
| 134 | public void flushCounters(); |
| 135 | |
| 136 | /** |
| 137 | * Resets the value of counters in the hierarchy to zero. Note that the reset |
| 138 | * applies to the level of counter hierarchy specified AND ALL LEVELS BELOW it |
| 139 | * in the hierarchy. |
| 140 | * For example: If a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops" |
| 141 | * specifying a reset hierarchy: "00:00:00:00:01:02:03:04" |
| 142 | * will reset all counters for the switch dpid specified; |
| 143 | * while specifying a reset hierarchy: ""00:00:00:00:01:02:03:04/pktin" |
| 144 | * will reset the pktin counter and all levels below it (like drops) |
| 145 | * for the switch dpid specified. |
| 146 | */ |
| 147 | void resetCounterHierarchy(String moduleName, String counterHierarchy); |
| 148 | |
| 149 | /** |
| 150 | * Resets the values of all counters in the system. |
| 151 | */ |
| 152 | public void resetAllCounters(); |
| 153 | |
| 154 | /** |
| 155 | * Resets the values of all counters belonging |
| 156 | * to a module with the given 'moduleName'. |
| 157 | */ |
| 158 | public void resetAllModuleCounters(String moduleName); |
| 159 | |
| 160 | /** |
| 161 | * This method applies only to CounterType.COUNT_ON_DEMAND. It is used to |
| 162 | * enable counting on the counter. Note that this step is necessary to start |
| 163 | * counting for these counter types - merely registering the counter is not |
| 164 | * enough (as is the case for CounterType.ALWAYS_COUNT). Newly |
| 165 | * enabled counters start from an initial value of zero. |
| 166 | * |
| 167 | * Enabling a counter in a counterHierarchy enables only THAT counter. It |
| 168 | * does not enable any other part of the counterHierarchy. For example, if |
| 169 | * a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops", where the |
| 170 | * 'pktin' and 'drops' counters are CounterType.COUNT_ON_DEMAND, then enabling |
| 171 | * the 'pktin' counter by specifying the counterHierarchy as |
| 172 | * "00:00:00:00:01:02:03:04/pktin" does NOT enable the 'drops' counter. |
| 173 | */ |
| 174 | public void enableCtrOnDemand(String moduleName, String counterHierarchy); |
| 175 | |
| 176 | /** |
| 177 | * This method applies only to CounterType.COUNT_ON_DEMAND. It is used to |
| 178 | * enable counting on the counter. Note that disabling a counter results in a loss |
| 179 | * of the counter value. When re-enabled the counter will restart from zero. |
| 180 | * |
| 181 | * Disabling a counter in a counterHierarchy disables only THAT counter. It |
| 182 | * does not disable any other part of the counterHierarchy. For example, if |
| 183 | * a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops", where the |
| 184 | * 'pktin' and 'drops' counters are CounterType.COUNT_ON_DEMAND, then disabling |
| 185 | * the 'pktin' counter by specifying the counterHierarchy as |
| 186 | * "00:00:00:00:01:02:03:04/pktin" does NOT disable the 'drops' counter. |
| 187 | */ |
| 188 | public void disableCtrOnDemand(String moduleName, String counterHierarchy); |
| 189 | |
| 190 | /** |
| 191 | * Get counter value and associated information for the specified counterHierarchy. |
| 192 | * Note that information on the level of counter hierarchy specified |
| 193 | * AND ALL LEVELS BELOW it in the hierarchy will be returned. |
| 194 | * |
| 195 | * For example, |
| 196 | * if a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops", then |
| 197 | * specifying a counterHierarchy of "00:00:00:00:01:02:03:04/pktin" in the |
| 198 | * get call will return information on the 'pktin' as well as the 'drops' |
| 199 | * counters for the switch dpid specified. |
| 200 | * |
| 201 | * @return A list of DebugCounterInfo or an empty list if the counter |
| 202 | * could not be found |
| 203 | */ |
| 204 | public List<DebugCounterInfo> getCounterHierarchy(String moduleName, |
| 205 | String counterHierarchy); |
| 206 | |
| 207 | /** |
| 208 | * Get counter values and associated information for all counters in the |
| 209 | * system |
| 210 | * |
| 211 | * @return the list of values/info or an empty list |
| 212 | */ |
| 213 | public List<DebugCounterInfo> getAllCounterValues(); |
| 214 | |
| 215 | /** |
| 216 | * Get counter values and associated information for all counters associated |
| 217 | * with a module. |
| 218 | * |
| 219 | * @param moduleName |
| 220 | * @return the list of values/info or an empty list |
| 221 | */ |
| 222 | public List<DebugCounterInfo> getModuleCounterValues(String moduleName); |
| 223 | |
| 224 | /** |
| 225 | * Convenience method to figure out if the the given 'counterHierarchy' corresponds |
| 226 | * to a registered counterHierarchy for 'moduleName'. Note that the counter may or |
| 227 | * may not be enabled for counting, but if it is registered the method will |
| 228 | * return true. |
| 229 | * |
| 230 | * @param param |
| 231 | * @return false if moduleCounterHierarchy is not a registered counter |
| 232 | */ |
| 233 | public boolean containsModuleCounterHierarchy(String moduleName, |
| 234 | String counterHierarchy); |
| 235 | |
| 236 | /** |
| 237 | * Convenience method to figure out if the the given 'moduleName' corresponds |
| 238 | * to a registered moduleName or not. Note that the module may or may not have |
| 239 | * a counter enabled for counting, but if it is registered the method will |
| 240 | * return true. |
| 241 | * |
| 242 | * @param param |
| 243 | * @return false if moduleName is not a registered counter |
| 244 | */ |
| 245 | public boolean containsModuleName(String moduleName); |
| 246 | |
| 247 | /** |
| 248 | * Returns a list of moduleNames registered for debug counters or an empty |
| 249 | * list if no counters have been registered in the system |
| 250 | */ |
| 251 | public List<String> getModuleList(); |
| 252 | |
| 253 | /** |
| 254 | * Returns a list of all counters registered for a specific moduleName |
| 255 | * or a empty list |
| 256 | */ |
| 257 | public List<String> getModuleCounterList(String moduleName); |
| 258 | |
| 259 | |
| 260 | } |