View Javadoc

1   /*
2    * $Id: YourKitProfilerServiceMBean.java 10269 2008-01-09 22:47:07Z aperepel $
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.management.mbeans;
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 }