Coverage Report - org.mule.module.management.mbean.YourKitProfilerServiceMBean
 
Classes in this File Line Coverage Branch Coverage Complexity
YourKitProfilerServiceMBean
N/A
N/A
1
 
 1  
 /*
 2  
  * $Id: YourKitProfilerServiceMBean.java 19355 2010-09-03 18:21:50Z ddossot $
 3  
  * --------------------------------------------------------------------------------------
 4  
  * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
 5  
  *
 6  
  * The software in this package is published under the terms of the CPAL v1.0
 7  
  * license, a copy of which has been included with this distribution in the
 8  
  * LICENSE.txt file.
 9  
  */
 10  
 
 11  
 package org.mule.module.management.mbean;
 12  
 
 13  
 import com.yourkit.api.ProfilingModes;
 14  
 
 15  
 public interface YourKitProfilerServiceMBean
 16  
 {
 17  
     // YourKit 8.x API merged all & adaptive into a single constant (2L), but we are
 18  
     // keeping them different
 19  
     // for our interface backwards compatibility with MuleHQ
 20  
     long ALLOCATION_RECORDING_ALL = ProfilingModes.ALLOCATION_RECORDING;
 21  
     long ALLOCATION_RECORDING_ADAPTIVE = 66L;
 22  
     long CPU_SAMPLING = ProfilingModes.CPU_SAMPLING;
 23  
     long CPU_TRACING = ProfilingModes.CPU_TRACING;
 24  
     long MONITOR_PROFILING = ProfilingModes.MONITOR_PROFILING;
 25  
     long CPU_J2EE = ProfilingModes.CPU_J2EE;
 26  
     long SNAPSHOT_WITHOUT_HEAP = ProfilingModes.SNAPSHOT_WITHOUT_HEAP;
 27  
     long SNAPSHOT_WITH_HEAP = ProfilingModes.SNAPSHOT_WITH_HEAP;
 28  
     long SNAPSHOT_HPROF = ProfilingModes.SNAPSHOT_HPROF;
 29  
     /**
 30  
      * this mark is added to getStatus to indicate that captureEverySec was stated
 31  
      */
 32  
     long SNAPSHOT_CAPTURING = 256;
 33  
 
 34  
     /**
 35  
      * @return name of host where controlled profiled application is running. The
 36  
      *         method never returns null.
 37  
      */
 38  
     String getHost();
 39  
 
 40  
     /**
 41  
      * @return port profiler agent listens on.
 42  
      */
 43  
     int getPort();
 44  
 
 45  
     /**
 46  
      * This method is just a convenient replacement of
 47  
      * captureSnapshot(YourKitProfilerServiceMBean.SNAPSHOT_WITH_HEAP)
 48  
      * 
 49  
      * @return absolute path to the captured snapshot.
 50  
      */
 51  
     String captureMemorySnapshot() throws Exception;
 52  
 
 53  
     /**
 54  
      * Captures snapshot: write profiling information to file.
 55  
      * <p/>
 56  
      * If some profiling is being performed (e.g. started with
 57  
      * {@link #startCPUProfiling(long, String)}, {@link #startMonitorProfiling()} or
 58  
      * {@link #startAllocationRecording(long)}, or remotely), it won't stop after the
 59  
      * capture. To stop it, explicitly call {@link #stopCPUProfiling()},
 60  
      * {@link #stopMonitorProfiling()} or {@link #stopAllocationRecording()}.
 61  
      * 
 62  
      * @param snapshotFlags defines how much information should be stored:
 63  
      *            <ul>
 64  
      *            <li>YourKitProfilerServiceMBean.SNAPSHOT_WITHOUT_HEAP - capture
 65  
      *            snapshot with all the recorded information (CPU profiling,
 66  
      *            monitors, telemetry), but without the heap dump. <li>
 67  
      *            YourKitProfilerServiceMBean.SNAPSHOT_WITH_HEAP - capture snapshot
 68  
      *            with all the recorded information (CPU profiling, monitors,
 69  
      *            telemetry, allocations), as well as with the heap dump. <li>
 70  
      *            YourKitProfilerServiceMBean.SNAPSHOT_HPROF - capture snapshot in
 71  
      *            HPROF format (it will including the heap dump only).
 72  
      *            </ul>
 73  
      * @return absolute path to the captured snapshot.
 74  
      * @throws Exception if capture failed. The possible reasons are:
 75  
      *             <ul>
 76  
      *             <li>there's no Java application with properly configured profiler
 77  
      *             agent listening on port at host <li>profiled application has
 78  
      *             terminated <li>agent cannot capture snapshot for some reason
 79  
      *             </ul>
 80  
      */
 81  
     String captureSnapshot(long snapshotFlags) throws Exception;
 82  
 
 83  
     /**
 84  
      * Advance current object generation number. Since that moment, all newly created
 85  
      * objects will belong to the new generation. Note that generations are also
 86  
      * automatically advanced on capturing snapshots. Generations are only available
 87  
      * if the profiled application runs on Java 5 or newer.
 88  
      * 
 89  
      * @param description optional description associated with the generation
 90  
      * @throws Exception if generation could not be advanced.
 91  
      */
 92  
     void advanceGeneration(String description) throws Exception;
 93  
 
 94  
     /**
 95  
      * Start object allocation recording.
 96  
      * 
 97  
      * @param mode YourKitProfilerServiceMBean.ALLOCATION_RECORDING_ALL or
 98  
      *            YourKitProfilerServiceMBean.ALLOCATION_RECORDING_ADAPTIVE
 99  
      * @throws Exception if capture failed. The possible reasons are:
 100  
      *             <ul>
 101  
      *             <li>there's no Java application with properly configured profiler
 102  
      *             agent listening on port at host
 103  
      *             <li>profiled application has terminated
 104  
      *             <li>agent cannot capture snapshot for some reason
 105  
      *             </ul>
 106  
      * @see #captureMemorySnapshot()
 107  
      * @see #stopCPUProfiling()
 108  
      */
 109  
     void startAllocationRecording(long mode) throws Exception;
 110  
 
 111  
     /**
 112  
      * @throws Exception if capture failed. The possible reasons are:
 113  
      *             <ul>
 114  
      *             <li>there's no Java application with properly configured profiler
 115  
      *             agent listening on port at host
 116  
      *             <li>profiled application has terminated
 117  
      *             <li>agent cannot capture snapshot for some reason
 118  
      *             </ul>
 119  
      */
 120  
     void stopAllocationRecording() throws Exception;
 121  
 
 122  
     /**
 123  
      * Start CPU profiling.
 124  
      * 
 125  
      * @param mode YourKitProfilerServiceMBean.CPU_SAMPLING or
 126  
      *            YourKitProfilerServiceMBean.CPU_TRACING or
 127  
      *            YourKitProfilerServiceMBean.CPU_SAMPLING |
 128  
      *            YourKitProfilerServiceMBean.CPU_J2EE or
 129  
      *            YourKitProfilerServiceMBean.CPU_TRACING |
 130  
      *            YourKitProfilerServiceMBean.CPU_J2EE
 131  
      * @param filters string containing '\n'-separated list of classes whose methods
 132  
      *            should not be profiled. Wildcards are accepted ('*'). More methods
 133  
      *            are profiled, bigger the overhead. The filters are used with
 134  
      *            YourKitProfilerServiceMBean.CPU_TRACING only; with
 135  
      *            YourKitProfilerServiceMBean.CPU_SAMPLING the value is ignored. If
 136  
      *            null or empty string passed, all methods will be profiled (not
 137  
      *            recommended due to high overhead). For example, you can pass
 138  
      *            DEFAULT_FILTERS.
 139  
      * @throws Exception if capture failed. The possible reasons are:
 140  
      *             <ul>
 141  
      *             <li>there's no Java application with properly configured profiler
 142  
      *             agent listening on port at host
 143  
      *             <li>specified profiling mode is not supported by the JVM of the
 144  
      *             profiled application, e.g. tracing is supported with Java 5 and
 145  
      *             newer and thus is not available with Java 1.4.
 146  
      *             <li>profiled application has terminated
 147  
      *             <li>agent cannot capture snapshot for some reason
 148  
      *             </ul>
 149  
      * @see #captureSnapshot(long)
 150  
      * @see #stopCPUProfiling()
 151  
      */
 152  
     void startCPUProfiling(long mode, String filters) throws Exception;
 153  
 
 154  
     /**
 155  
      * Stop CPU profiling.
 156  
      * 
 157  
      * @throws Exception if capture failed. The possible reasons are:
 158  
      *             <ul>
 159  
      *             <li>there's no Java application with properly configured profiler
 160  
      *             agent listening on port at host
 161  
      *             <li>profiled application has terminated
 162  
      *             <li>agent cannot capture snapshot for some reason
 163  
      *             </ul>
 164  
      * @see #captureSnapshot(long)
 165  
      * @see #startCPUProfiling(long , String)
 166  
      */
 167  
     void stopCPUProfiling() throws Exception;
 168  
 
 169  
     /**
 170  
      * Force GC
 171  
      * 
 172  
      * @return Message contains size of objects in heap before GC, bytes and size of
 173  
      *         objects in heap after GC, bytes
 174  
      * @throws Exception
 175  
      */
 176  
     String forceGC() throws Exception;
 177  
 
 178  
     /**
 179  
      * Start monitor profiling (requires that the profiled application runs on Java 5
 180  
      * or newer)
 181  
      * 
 182  
      * @throws Exception if capture failed. The possible reasons are:
 183  
      *             <ul>
 184  
      *             <li>there's no Java application with properly configured profiler
 185  
      *             agent listening on port at host
 186  
      *             <li>specified profiling mode is not supported by the JVM of the
 187  
      *             profiled application, e.g. tracing is supported with Java 5 and
 188  
      *             newer and thus is not available with Java 1.4.
 189  
      *             <li>CPU profiling has already been started
 190  
      *             <li>profiled application has terminated
 191  
      *             <li>agent cannot capture snapshot for some reason
 192  
      *             </ul>
 193  
      * @see #stopMonitorProfiling()
 194  
      * @see #captureSnapshot(long)
 195  
      */
 196  
     void startMonitorProfiling() throws Exception;
 197  
 
 198  
     /**
 199  
      * Stop monitor profiling (requires that the profiled application runs on Java 5
 200  
      * or newer)
 201  
      * 
 202  
      * @throws Exception if capture failed. The possible reasons are:
 203  
      *             <ul>
 204  
      *             <li>there's no Java application with properly configured profiler
 205  
      *             agent listening on port at host
 206  
      *             <li>profiled application has terminated
 207  
      *             <li>agent cannot capture snapshot for some reason
 208  
      *             </ul>
 209  
      * @see #startMonitorProfiling()
 210  
      * @see #captureSnapshot(long)
 211  
      */
 212  
     void stopMonitorProfiling() throws Exception;
 213  
 
 214  
     /**
 215  
      * Starts new daemon thread which calls {@link #captureMemorySnapshot()} every N
 216  
      * seconds.
 217  
      * 
 218  
      * @param seconds delay between calls
 219  
      * @see #captureMemorySnapshot()
 220  
      */
 221  
     void startCapturingMemSnapshot(final int seconds);
 222  
 
 223  
     /**
 224  
      * Stops daemon thread started by {@link #startCapturingMemSnapshot(int)}
 225  
      */
 226  
     void stopCapturingMemSnapshot();
 227  
 
 228  
     /**
 229  
      * Get current profiling status. The following code snippet demonstrates how to
 230  
      * use this method: <code><pre>
 231  
      * long status = controller.getStatus();
 232  
      * <p/>
 233  
      * if ((status & YourKitProfilerServiceMBean.ALLOCATION_RECORDING_ADAPTIVE) != 0) {
 234  
      *  System.out.println("Allocation recording is on (adaptive)");
 235  
      * }
 236  
      * else if ((status & YourKitProfilerServiceMBean.ALLOCATION_RECORDING_ALL) != 0) {
 237  
      *  System.out.println("Allocation recording is on (all objects)");
 238  
      * }
 239  
      * else {
 240  
      *  System.out.println("Allocation recording is off");
 241  
      * }
 242  
      * <p/>
 243  
      * if ((status & YourKitProfilerServiceMBean.CPU_TRACING) != 0) {
 244  
      *  System.out.println("CPU profiling is on (tracing)");
 245  
      * }
 246  
      * else if ((status & YourKitProfilerServiceMBean.CPU_SAMPLING) != 0) {
 247  
      *  System.out.println("CPU profiling is on (sampling)");
 248  
      * }
 249  
      * else {
 250  
      *  System.out.println("CPU profiling is off");
 251  
      * }
 252  
      * <p/>
 253  
      * if ((status & YourKitProfilerServiceMBean.MONITOR_PROFILING) != 0) {
 254  
      *  System.out.println("Monitor profiling is on");
 255  
      * }
 256  
      * else {
 257  
      *  System.out.println("Monitor profiling is off");
 258  
      * }
 259  
      *  if ((status & YourKitProfilerServiceMBean.SNAPSHOT_CAPTURING) != 0) {
 260  
      *  System.out.println("Snaphot capturing is on");
 261  
      * }
 262  
      * else {
 263  
      *  System.out.println("Snaphot capturing is off");
 264  
      * }
 265  
      * </pre></code>
 266  
      * 
 267  
      * @return a bit mask to check against Profiling Modes
 268  
      * @throws java.lang.Exception
 269  
      */
 270  
     long getStatus() throws java.lang.Exception;
 271  
 
 272  
 }