| package net.floodlightcontroller.debugcounter; |
| |
| import net.floodlightcontroller.core.module.IFloodlightService; |
| import net.floodlightcontroller.debugcounter.DebugCounter.DebugCounterInfo; |
| |
| import java.util.List; |
| |
| public interface IDebugCounterService extends IFloodlightService { |
| |
| /** |
| * Different counter types. Counters that are meant to be counted-on-demand |
| * need to be separately enabled/disabled. |
| */ |
| public enum CounterType { |
| ALWAYS_COUNT, |
| COUNT_ON_DEMAND |
| } |
| |
| /** |
| * Debug Counter Qualifiers |
| */ |
| public static final String CTR_MDATA_WARN = "warn"; |
| public static final String CTR_MDATA_ERROR = "error"; |
| public static final String CTR_MDATA_DROP = "drop"; |
| |
| /** |
| * A limit on the maximum number of counters that can be created |
| */ |
| public static final int MAX_COUNTERS = 5000; |
| |
| /** |
| * Exception thrown when MAX_COUNTERS have been registered |
| */ |
| public class MaxCountersRegistered extends CounterException { |
| private static final long serialVersionUID = 3173747663719376745L; |
| String errormsg; |
| public MaxCountersRegistered(String errormsg) { |
| this.errormsg = errormsg; |
| } |
| @Override |
| public String getMessage() { |
| return this.errormsg; |
| } |
| } |
| /** |
| * Exception thrown when MAX_HIERARCHY has been reached |
| */ |
| public class MaxHierarchyRegistered extends CounterException { |
| private static final long serialVersionUID = 967431358683523871L; |
| String errormsg; |
| public MaxHierarchyRegistered(String errormsg) { |
| this.errormsg = errormsg; |
| } |
| @Override |
| public String getMessage() { |
| return this.errormsg; |
| } |
| } |
| /** |
| * Exception thrown when attempting to register a hierarchical counter |
| * where higher levels of the hierarchy have not been pre-registered |
| */ |
| public class MissingHierarchicalLevel extends CounterException { |
| private static final long serialVersionUID = 517315311533995739L; |
| String errormsg; |
| public MissingHierarchicalLevel(String errormsg) { |
| this.errormsg = errormsg; |
| } |
| @Override |
| public String getMessage() { |
| return this.errormsg; |
| } |
| } |
| |
| public class CounterException extends Exception { |
| private static final long serialVersionUID = 2219781500857866035L; |
| } |
| |
| /** |
| * maximum levels of hierarchy |
| * Example of moduleName/counterHierarchy: |
| * switch/00:00:00:00:01:02:03:04/pktin/drops where |
| * moduleName ==> "switch" and |
| * counterHierarchy of 3 ==> "00:00:00:00:01:02:03:04/pktin/drops" |
| */ |
| public static final int MAX_HIERARCHY = 3; |
| |
| /** |
| * All modules that wish to have the DebugCounterService count for them, must |
| * register their counters by making this call (typically from that module's |
| * 'startUp' method). The counter can then be updated, displayed, reset etc. |
| * using the registered moduleName and counterHierarchy. |
| * |
| * @param moduleName the name of the module which is registering the |
| * counter eg. linkdiscovery or controller or switch |
| * @param counterHierarchy the hierarchical counter name specifying all |
| * the hierarchical levels that come above it. |
| * For example: to register a drop counter for |
| * packet-ins from a switch, the counterHierarchy |
| * can be "00:00:00:00:01:02:03:04/pktin/drops" |
| * It is necessary that counters in hierarchical levels |
| * above have already been pre-registered - in this |
| * example: "00:00:00:00:01:02:03:04/pktin" and |
| * "00:00:00:00:01:02:03:04" |
| * @param counterDescription a descriptive string that gives more information |
| * of what the counter is measuring. For example, |
| * "Measures the number of incoming packets seen by |
| * this module". |
| * @param counterType One of CounterType. On-demand counter types |
| * need to be explicitly enabled/disabled using other |
| * methods in this API -- i.e. registering them is |
| * not enough to start counting. |
| * @param metaData variable arguments that qualify a counter |
| * eg. warn, error etc. |
| * @return IDebugCounter with update methods that can be |
| * used to update a counter. |
| * @throws MaxCountersRegistered |
| * @throws MaxHierarchyRegistered |
| * @throws MissingHierarchicalLevel |
| */ |
| public IDebugCounter registerCounter(String moduleName, String counterHierarchy, |
| String counterDescription, CounterType counterType, |
| String... metaData) |
| throws MaxCountersRegistered, MaxHierarchyRegistered, |
| MissingHierarchicalLevel; |
| |
| /** |
| * Flush all thread-local counter values (from the current thread) |
| * to the global counter store. This method is not intended for use by any |
| * module. It's typical usage is from floodlight core and it is meant |
| * to flush those counters that are updated in the packet-processing pipeline, |
| * typically with the 'updateCounterNoFlush" methods in IDebugCounter. |
| */ |
| public void flushCounters(); |
| |
| /** |
| * Resets the value of counters in the hierarchy to zero. Note that the reset |
| * applies to the level of counter hierarchy specified AND ALL LEVELS BELOW it |
| * in the hierarchy. |
| * For example: If a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops" |
| * specifying a reset hierarchy: "00:00:00:00:01:02:03:04" |
| * will reset all counters for the switch dpid specified; |
| * while specifying a reset hierarchy: ""00:00:00:00:01:02:03:04/pktin" |
| * will reset the pktin counter and all levels below it (like drops) |
| * for the switch dpid specified. |
| */ |
| void resetCounterHierarchy(String moduleName, String counterHierarchy); |
| |
| /** |
| * Resets the values of all counters in the system. |
| */ |
| public void resetAllCounters(); |
| |
| /** |
| * Resets the values of all counters belonging |
| * to a module with the given 'moduleName'. |
| */ |
| public void resetAllModuleCounters(String moduleName); |
| |
| /** |
| * This method applies only to CounterType.COUNT_ON_DEMAND. It is used to |
| * enable counting on the counter. Note that this step is necessary to start |
| * counting for these counter types - merely registering the counter is not |
| * enough (as is the case for CounterType.ALWAYS_COUNT). Newly |
| * enabled counters start from an initial value of zero. |
| * |
| * Enabling a counter in a counterHierarchy enables only THAT counter. It |
| * does not enable any other part of the counterHierarchy. For example, if |
| * a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops", where the |
| * 'pktin' and 'drops' counters are CounterType.COUNT_ON_DEMAND, then enabling |
| * the 'pktin' counter by specifying the counterHierarchy as |
| * "00:00:00:00:01:02:03:04/pktin" does NOT enable the 'drops' counter. |
| */ |
| public void enableCtrOnDemand(String moduleName, String counterHierarchy); |
| |
| /** |
| * This method applies only to CounterType.COUNT_ON_DEMAND. It is used to |
| * enable counting on the counter. Note that disabling a counter results in a loss |
| * of the counter value. When re-enabled the counter will restart from zero. |
| * |
| * Disabling a counter in a counterHierarchy disables only THAT counter. It |
| * does not disable any other part of the counterHierarchy. For example, if |
| * a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops", where the |
| * 'pktin' and 'drops' counters are CounterType.COUNT_ON_DEMAND, then disabling |
| * the 'pktin' counter by specifying the counterHierarchy as |
| * "00:00:00:00:01:02:03:04/pktin" does NOT disable the 'drops' counter. |
| */ |
| public void disableCtrOnDemand(String moduleName, String counterHierarchy); |
| |
| /** |
| * Get counter value and associated information for the specified counterHierarchy. |
| * Note that information on the level of counter hierarchy specified |
| * AND ALL LEVELS BELOW it in the hierarchy will be returned. |
| * |
| * For example, |
| * if a hierarchy exists like "00:00:00:00:01:02:03:04/pktin/drops", then |
| * specifying a counterHierarchy of "00:00:00:00:01:02:03:04/pktin" in the |
| * get call will return information on the 'pktin' as well as the 'drops' |
| * counters for the switch dpid specified. |
| * |
| * @return A list of DebugCounterInfo or an empty list if the counter |
| * could not be found |
| */ |
| public List<DebugCounterInfo> getCounterHierarchy(String moduleName, |
| String counterHierarchy); |
| |
| /** |
| * Get counter values and associated information for all counters in the |
| * system |
| * |
| * @return the list of values/info or an empty list |
| */ |
| public List<DebugCounterInfo> getAllCounterValues(); |
| |
| /** |
| * Get counter values and associated information for all counters associated |
| * with a module. |
| * |
| * @param moduleName |
| * @return the list of values/info or an empty list |
| */ |
| public List<DebugCounterInfo> getModuleCounterValues(String moduleName); |
| |
| /** |
| * Convenience method to figure out if the the given 'counterHierarchy' corresponds |
| * to a registered counterHierarchy for 'moduleName'. Note that the counter may or |
| * may not be enabled for counting, but if it is registered the method will |
| * return true. |
| * |
| * @param param |
| * @return false if moduleCounterHierarchy is not a registered counter |
| */ |
| public boolean containsModuleCounterHierarchy(String moduleName, |
| String counterHierarchy); |
| |
| /** |
| * Convenience method to figure out if the the given 'moduleName' corresponds |
| * to a registered moduleName or not. Note that the module may or may not have |
| * a counter enabled for counting, but if it is registered the method will |
| * return true. |
| * |
| * @param param |
| * @return false if moduleName is not a registered counter |
| */ |
| public boolean containsModuleName(String moduleName); |
| |
| /** |
| * Returns a list of moduleNames registered for debug counters or an empty |
| * list if no counters have been registered in the system |
| */ |
| public List<String> getModuleList(); |
| |
| /** |
| * Returns a list of all counters registered for a specific moduleName |
| * or a empty list |
| */ |
| public List<String> getModuleCounterList(String moduleName); |
| |
| |
| } |