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 }