Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
YourKitProfilerServiceMBean |
|
| 1.0;1 |
1 | /* | |
2 | * $Id: YourKitProfilerServiceMBean.java 11917 2008-06-03 13:42:02Z dfeist $ | |
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.module.management.mbean; | |
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 | } |