View Javadoc
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 }