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