View Javadoc

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 }