opendaylight/md-sal/mdsal-trace/dom-impl/src/main/java/org/opendaylight/controller/md/sal/trace/dom/impl/TracingBroker.java

   1 /*
   2  * Copyright (c) 2016 Red Hat, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.controller.md.sal.trace.dom.impl;
   9
  10 import java.util.ArrayList;
  11 import java.util.HashMap;
  12 import java.util.List;
  13 import java.util.Map;
  14 import java.util.Objects;
  15 import javax.annotation.Nonnull;
  16
  17 import org.opendaylight.controller.md.sal.common.api.data.AsyncDataBroker;
  18 import org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType;
  19 import org.opendaylight.controller.md.sal.common.api.data.TransactionChainListener;
  20 import org.opendaylight.controller.md.sal.dom.api.DOMDataBroker;
  21 import org.opendaylight.controller.md.sal.dom.api.DOMDataBrokerExtension;
  22 import org.opendaylight.controller.md.sal.dom.api.DOMDataChangeListener;
  23 import org.opendaylight.controller.md.sal.dom.api.DOMDataReadOnlyTransaction;
  24 import org.opendaylight.controller.md.sal.dom.api.DOMDataReadWriteTransaction;
  25 import org.opendaylight.controller.md.sal.dom.api.DOMDataTreeChangeListener;
  26 import org.opendaylight.controller.md.sal.dom.api.DOMDataTreeChangeService;
  27 import org.opendaylight.controller.md.sal.dom.api.DOMDataTreeIdentifier;
  28 import org.opendaylight.controller.md.sal.dom.api.DOMDataWriteTransaction;
  29 import org.opendaylight.controller.md.sal.dom.api.DOMTransactionChain;
  30 import org.opendaylight.controller.md.sal.trace.api.TracingDOMDataBroker;
  31 import org.opendaylight.controller.md.sal.trace.closetracker.impl.CloseTrackedRegistry;
  32 import org.opendaylight.mdsal.binding.dom.codec.api.BindingNormalizedNodeSerializer;
  33 import org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.mdsaltrace.rev160908.Config;
  34 import org.opendaylight.yangtools.concepts.ListenerRegistration;
  35 import org.opendaylight.yangtools.yang.binding.DataObject;
  36 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  37 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  38 import org.slf4j.Logger;
  39 import org.slf4j.LoggerFactory;
  40
  41 @SuppressWarnings("checkstyle:JavadocStyle")
  42 //...because otherwise it whines about the elements in the @code block even though it's completely valid Javadoc
  43
  44 /**
  45  * TracingBroker logs "write" operations and listener registrations to the md-sal. It logs the instance identifier path,
  46  * the objects themselves, as well as the stack trace of the call invoking the registration or write operation.
  47  * It works by operating as a "bump on the stack" between the application and actual DataBroker, intercepting write
  48  * and registration calls and writing to the log.
  49  * <h1>Wiring:</h1>
  50  * TracingBroker is designed to be easy to use. In fact, for bundles using Blueprint to inject their DataBroker
  51  * TracingBroker can be used without modifying your code at all in two simple steps:
  52  * <ol>
  53  * <li>
  54  * Simply add the dependency "mdsaltrace-features" to
  55  * your karaf pom:
  56  * <pre>
  57  * {@code
  58  *  <dependency>
  59  *    <groupId>org.opendaylight.controller</groupId>
  60  *    <artifactId>mdsal-trace-features</artifactId>
  61  *    <classifier>features</classifier>
  62  *    <type>xml</type>
  63  *    <scope>runtime</scope>
  64  *    <version>0.1.6-SNAPSHOT</version>
  65  *  </dependency>
  66  * }
  67  * </pre>
  68  * </li>
  69  * <li>
  70  * Then just load the odl-mdsal-trace feature before your feature and you're done.
  71  * </li>
  72  * </ol>
  73  * This works because the mdsaltrace-impl bundle registers its service implementing DOMDataBroker with a higher
  74  * rank than sal-binding-broker. As such, any OSGi service lookup for DataBroker will receive the TracingBroker.
  75  * <p> </p>
  76  * <h1>Avoiding log bloat:</h1>
  77  * TracingBroker can be configured to only print registrations or write ops pertaining to certain subtrees of the
  78  * md-sal. This can be done in the code via the methods of this class or via a config file. TracingBroker uses a more
  79  * convenient but non-standard representation of the instance identifiers. Each instance identifier segment's
  80  * class.getSimpleName() is used separated by a '/'.
  81  * <p> </p>
  82  * <h1>Known issues</h1>
  83  * <ul>
  84  *     <li>
  85  *        Filtering by paths. For some registrations the codec that converts back from the DOM to binding paths is
  86  *        busted. As such, an aproximated path is used in the output. For now it is recommended not to use
  87  *        watchRegistrations and allow all registrations to be logged.
  88  *     </li>
  89  * </ul>
  90  *
  91  */
  92 public class TracingBroker implements TracingDOMDataBroker {
  93
  94     static final Logger LOG = LoggerFactory.getLogger(TracingBroker.class);
  95
  96     private static final int STACK_TRACE_FIRST_RELEVANT_FRAME = 2;
  97
  98     private final BindingNormalizedNodeSerializer codec;
  99     private final DOMDataBroker delegate;
 100     private final List<Watch> registrationWatches = new ArrayList<>();
 101     private final List<Watch> writeWatches = new ArrayList<>();
 102
 103     private final boolean isDebugging;
 104     private final CloseTrackedRegistry<TracingTransactionChain> transactionChainsRegistry;
 105     private final CloseTrackedRegistry<TracingReadOnlyTransaction> readOnlyTransactionsRegistry;
 106     private final CloseTrackedRegistry<TracingWriteTransaction> writeTransactionsRegistry;
 107     private final CloseTrackedRegistry<TracingReadWriteTransaction> readWriteTransactionsRegistry;
 108
 109     private class Watch {
 110         final String iidString;
 111         final LogicalDatastoreType store;
 112
 113         Watch(String iidString, LogicalDatastoreType storeOrNull) {
 114             this.store = storeOrNull;
 115             this.iidString = iidString;
 116         }
 117
 118         private String toIidCompString(YangInstanceIdentifier iid) {
 119             StringBuilder builder = new StringBuilder();
 120             toPathString(iid, builder);
 121             builder.append('/');
 122             return builder.toString();
 123         }
 124
 125         private boolean isParent(String parent, String child) {
 126             int parentOffset = 0;
 127             if (parent.length() > 0 && parent.charAt(0) == '<') {
 128                 parentOffset = parent.indexOf('>') + 1;
 129             }
 130
 131             int childOffset = 0;
 132             if (child.length() > 0 && child.charAt(0) == '<') {
 133                 childOffset = child.indexOf('>') + 1;
 134             }
 135
 136             return child.startsWith(parent.substring(parentOffset), childOffset);
 137         }
 138
 139         public boolean subtreesOverlap(YangInstanceIdentifier iid, LogicalDatastoreType store,
 140                                                                 AsyncDataBroker.DataChangeScope scope) {
 141             if (this.store != null && !this.store.equals(store)) {
 142                 return false;
 143             }
 144
 145             String otherIidString = toIidCompString(iid);
 146             switch (scope) {
 147                 case BASE:
 148                     return isParent(iidString, otherIidString);
 149                 case ONE: //for now just treat like SUBTREE, even though it's not
 150                 case SUBTREE:
 151                     return isParent(iidString, otherIidString) || isParent(otherIidString, iidString);
 152                 default:
 153                     return false;
 154             }
 155         }
 156
 157         public boolean eventIsOfInterest(YangInstanceIdentifier iid, LogicalDatastoreType store) {
 158             if (this.store != null && !this.store.equals(store)) {
 159                 return false;
 160             }
 161
 162             return isParent(iidString, toPathString(iid));
 163         }
 164     }
 165
 166     public TracingBroker(DOMDataBroker delegate, Config config, BindingNormalizedNodeSerializer codec) {
 167         this.delegate = Objects.requireNonNull(delegate);
 168         this.codec = Objects.requireNonNull(codec);
 169         configure(config);
 170
 171         if (config.isTransactionDebugContextEnabled() != null) {
 172             this.isDebugging = config.isTransactionDebugContextEnabled();
 173         } else {
 174             this.isDebugging = false;
 175         }
 176         this.transactionChainsRegistry     = new CloseTrackedRegistry<>(this, "createTransactionChain", isDebugging);
 177         this.readOnlyTransactionsRegistry  = new CloseTrackedRegistry<>(this, "newReadOnlyTransaction", isDebugging);
 178         this.writeTransactionsRegistry     = new CloseTrackedRegistry<>(this, "newWriteOnlyTransaction", isDebugging);
 179         this.readWriteTransactionsRegistry = new CloseTrackedRegistry<>(this, "newReadWriteTransaction", isDebugging);
 180     }
 181
 182     private void configure(Config config) {
 183         registrationWatches.clear();
 184         List<String> paths = config.getRegistrationWatches();
 185         if (paths != null) {
 186             for (String path : paths) {
 187                 watchRegistrations(path, null);
 188             }
 189         }
 190
 191         writeWatches.clear();
 192         paths = config.getWriteWatches();
 193         if (paths != null) {
 194             for (String path : paths) {
 195                 watchWrites(path, null);
 196             }
 197         }
 198     }
 199
 200     /**
 201      * Log registrations to this subtree of the md-sal.
 202      * @param iidString the iid path of the root of the subtree
 203      * @param store Which LogicalDataStore? or null for both
 204      */
 205     public void watchRegistrations(String iidString, LogicalDatastoreType store) {
 206         LOG.info("Watching registrations to {} in {}", iidString, store);
 207         registrationWatches.add(new Watch(iidString, store));
 208     }
 209
 210     /**
 211      * Log writes to this subtree of the md-sal.
 212      * @param iidString the iid path of the root of the subtree
 213      * @param store Which LogicalDataStore? or null for both
 214      */
 215     public void watchWrites(String iidString, LogicalDatastoreType store) {
 216         LOG.info("Watching writes to {} in {}", iidString, store);
 217         Watch watch = new Watch(iidString, store);
 218         writeWatches.add(watch);
 219     }
 220
 221     private boolean isRegistrationWatched(YangInstanceIdentifier iid,
 222                                                             LogicalDatastoreType store, DataChangeScope scope) {
 223         if (registrationWatches.isEmpty()) {
 224             return true;
 225         }
 226
 227         for (Watch regInterest : registrationWatches) {
 228             if (regInterest.subtreesOverlap(iid, store, scope)) {
 229                 return true;
 230             }
 231         }
 232
 233         return false;
 234     }
 235
 236     boolean isWriteWatched(YangInstanceIdentifier iid, LogicalDatastoreType store) {
 237         if (writeWatches.isEmpty()) {
 238             return true;
 239         }
 240
 241         for (Watch watch : writeWatches) {
 242             if (watch.eventIsOfInterest(iid, store)) {
 243                 return true;
 244             }
 245         }
 246
 247         return false;
 248     }
 249
 250     static void toPathString(InstanceIdentifier<? extends DataObject> iid, StringBuilder builder) {
 251         for (InstanceIdentifier.PathArgument pathArg : iid.getPathArguments()) {
 252             builder.append('/').append(pathArg.getType().getSimpleName());
 253         }
 254     }
 255
 256     String toPathString(YangInstanceIdentifier  yiid) {
 257         StringBuilder sb = new StringBuilder();
 258         toPathString(yiid, sb);
 259         return sb.toString();
 260     }
 261
 262
 263     private void toPathString(YangInstanceIdentifier yiid, StringBuilder sb) {
 264         InstanceIdentifier<?> iid = codec.fromYangInstanceIdentifier(yiid);
 265         if (null == iid) {
 266             reconstructIidPathString(yiid, sb);
 267         } else {
 268             toPathString(iid, sb);
 269         }
 270     }
 271
 272     private void reconstructIidPathString(YangInstanceIdentifier yiid, StringBuilder sb) {
 273         sb.append("<RECONSTRUCTED FROM: \"").append(yiid.toString()).append("\">");
 274         for (YangInstanceIdentifier.PathArgument pathArg : yiid.getPathArguments()) {
 275             if (pathArg instanceof YangInstanceIdentifier.AugmentationIdentifier) {
 276                 sb.append('/').append("AUGMENTATION");
 277                 continue;
 278             }
 279             sb.append('/').append(pathArg.getNodeType().getLocalName());
 280         }
 281     }
 282
 283     String getStackSummary() {
 284         StackTraceElement[] stack = Thread.currentThread().getStackTrace();
 285
 286         StringBuilder sb = new StringBuilder();
 287         for (int i = STACK_TRACE_FIRST_RELEVANT_FRAME; i < stack.length; i++) {
 288             StackTraceElement frame = stack[i];
 289             sb.append("\n\t(TracingBroker)\t").append(frame.getClassName()).append('.').append(frame.getMethodName());
 290         }
 291
 292         return sb.toString();
 293     }
 294
 295     @Override
 296     public DOMDataReadWriteTransaction newReadWriteTransaction() {
 297         return new TracingReadWriteTransaction(delegate.newReadWriteTransaction(), this, readWriteTransactionsRegistry);
 298     }
 299
 300     @Override
 301     public DOMDataWriteTransaction newWriteOnlyTransaction() {
 302         return new TracingWriteTransaction(delegate.newWriteOnlyTransaction(), this, writeTransactionsRegistry);
 303     }
 304
 305     @Override
 306     public ListenerRegistration<DOMDataChangeListener> registerDataChangeListener(
 307                                                         LogicalDatastoreType store, YangInstanceIdentifier yiid,
 308                                                         DOMDataChangeListener listener, DataChangeScope scope) {
 309         if (isRegistrationWatched(yiid, store, scope)) {
 310             LOG.warn("Registration (registerDataChangeListener) for {} from {}",
 311                     toPathString(yiid), getStackSummary());
 312         }
 313         return delegate.registerDataChangeListener(store, yiid, listener, scope);
 314     }
 315
 316     @Override
 317     public DOMTransactionChain createTransactionChain(TransactionChainListener transactionChainListener) {
 318         return new TracingTransactionChain(
 319                 delegate.createTransactionChain(transactionChainListener), this, transactionChainsRegistry);
 320     }
 321
 322     @Override
 323     public DOMDataReadOnlyTransaction newReadOnlyTransaction() {
 324         return new TracingReadOnlyTransaction(delegate.newReadOnlyTransaction(), this, readOnlyTransactionsRegistry);
 325     }
 326
 327     @Nonnull
 328     @Override
 329     public Map<Class<? extends DOMDataBrokerExtension>, DOMDataBrokerExtension> getSupportedExtensions() {
 330         Map<Class<? extends DOMDataBrokerExtension>, DOMDataBrokerExtension> res = delegate.getSupportedExtensions();
 331         DOMDataTreeChangeService treeChangeSvc = (DOMDataTreeChangeService) res.get(DOMDataTreeChangeService.class);
 332         if (treeChangeSvc == null) {
 333             return res;
 334         }
 335
 336         res = new HashMap<>(res);
 337
 338         res.put(DOMDataTreeChangeService.class, new DOMDataTreeChangeService() {
 339             @Nonnull
 340             @Override
 341             public <L extends DOMDataTreeChangeListener> ListenerRegistration<L> registerDataTreeChangeListener(
 342                     @Nonnull DOMDataTreeIdentifier domDataTreeIdentifier, @Nonnull L listener) {
 343                 if (isRegistrationWatched(domDataTreeIdentifier.getRootIdentifier(),
 344                         domDataTreeIdentifier.getDatastoreType(), DataChangeScope.SUBTREE)) {
 345                     LOG.warn("Registration (registerDataTreeChangeListener) for {} from {}",
 346                             toPathString(domDataTreeIdentifier.getRootIdentifier()), getStackSummary());
 347                 }
 348                 return treeChangeSvc.registerDataTreeChangeListener(domDataTreeIdentifier, listener);
 349             }
 350         });
 351
 352         return res;
 353     }
 354 }