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