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 }