Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
YourKitProfilerServiceMBean |
|
| 1.0;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 | } |