001: /*
002: * $Id: YourKitProfilerServiceMBean.java 11234 2008-03-06 23:44:34Z tcarlson $
003: * --------------------------------------------------------------------------------------
004: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
005: *
006: * The software in this package is published under the terms of the CPAL v1.0
007: * license, a copy of which has been included with this distribution in the
008: * LICENSE.txt file.
009: */
010:
011: package org.mule.module.management.mbean;
012:
013: import com.yourkit.api.ProfilingModes;
014:
015: public interface YourKitProfilerServiceMBean {
016: public static final long ALLOCATION_RECORDING_ALL = ProfilingModes.ALLOCATION_RECORDING_ALL;
017: public static final long ALLOCATION_RECORDING_ADAPTIVE = ProfilingModes.ALLOCATION_RECORDING_ADAPTIVE;
018: public static final long CPU_SAMPLING = ProfilingModes.CPU_SAMPLING;
019: public static final long CPU_TRACING = ProfilingModes.CPU_TRACING;
020: public static final long MONITOR_PROFILING = ProfilingModes.MONITOR_PROFILING;
021: public static final long CPU_J2EE = ProfilingModes.CPU_J2EE;
022: public static final long SNAPSHOT_WITHOUT_HEAP = ProfilingModes.SNAPSHOT_WITHOUT_HEAP;
023: public static final long SNAPSHOT_WITH_HEAP = ProfilingModes.SNAPSHOT_WITH_HEAP;
024: public static final long SNAPSHOT_HPROF = ProfilingModes.SNAPSHOT_HPROF;
025: /**
026: * this mark is added to getStatus to indicate that captureEverySec was stated
027: */
028: public static final long SNAPSHOT_CAPTURING = 256;
029:
030: /**
031: * @return name of host where controlled profiled application is running. The method never returns null.
032: */
033: public String getHost();
034:
035: /**
036: * @return port profiler agent listens on.
037: */
038: public int getPort();
039:
040: /**
041: * This method is just a convenient replacement of captureSnapshot(YourKitProfilerServiceMBean.SNAPSHOT_WITH_HEAP)
042: *
043: * @return absolute path to the captured snapshot.
044: */
045: public String captureMemorySnapshot() throws Exception;
046:
047: /**
048: * Captures snapshot: write profiling information to file.
049: * <p/>
050: * If some profiling is being performed (e.g. started with {@link #startCPUProfiling(long, String)}, {@link #startMonitorProfiling()}
051: * or {@link #startAllocationRecording(long)}, or remotely), it won't stop after the capture. To stop it, explicitly call
052: * {@link #stopCPUProfiling()}, {@link #stopMonitorProfiling()} or {@link #stopAllocationRecording()}.
053: *
054: * @param snapshotFlags defines how much information should be stored:
055: * <ul>
056: * <li>YourKitProfilerServiceMBean.SNAPSHOT_WITHOUT_HEAP - capture snapshot with all the recorded information
057: * (CPU profiling, monitors, telemetry), but without the heap dump.
058: * <li>YourKitProfilerServiceMBean.SNAPSHOT_WITH_HEAP - capture snapshot with all the recorded information
059: * (CPU profiling, monitors, telemetry, allocations), as well as with the heap dump.
060: * <li>YourKitProfilerServiceMBean.SNAPSHOT_HPROF - capture snapshot in HPROF format
061: * (it will including the heap dump only).
062: * </ul>
063: * @return absolute path to the captured snapshot.
064: * @throws Exception if capture failed. The possible reasons are:
065: * <ul>
066: * <li>there's no Java application with properly configured profiler agent listening on port at host
067: * <li>profiled application has terminated
068: * <li>agent cannot capture snapshot for some reason
069: * </ul>
070: */
071: public String captureSnapshot(long snapshotFlags) throws Exception;
072:
073: /**
074: * Advance current object generation number.
075: * Since that moment, all newly created objects will belong to the new generation.
076: * Note that generations are also automatically advanced on capturing snapshots.
077: * Generations are only available if the profiled application runs on Java 5 or newer.
078: *
079: * @param description optional description associated with the generation
080: */
081: public void advanceGeneration(String description);
082:
083: /**
084: * Start object allocation recording.
085: *
086: * @param mode YourKitProfilerServiceMBean.ALLOCATION_RECORDING_ALL or YourKitProfilerServiceMBean.ALLOCATION_RECORDING_ADAPTIVE
087: * @throws Exception if capture failed. The possible reasons are:
088: * <ul>
089: * <li>there's no Java application with properly configured profiler agent listening on port at host
090: * <li>profiled application has terminated
091: * <li>agent cannot capture snapshot for some reason
092: * </ul>
093: * @see #captureMemorySnapshot()
094: * @see #stopCPUProfiling()
095: */
096: public void startAllocationRecording(long mode) throws Exception;
097:
098: /**
099: * @throws Exception if capture failed. The possible reasons are:
100: * <ul>
101: * <li>there's no Java application with properly configured profiler agent listening on port at host
102: * <li>profiled application has terminated
103: * <li>agent cannot capture snapshot for some reason
104: * </ul>
105: */
106: public void stopAllocationRecording() throws Exception;
107:
108: /**
109: * Start CPU profiling.
110: *
111: * @param mode YourKitProfilerServiceMBean.CPU_SAMPLING or YourKitProfilerServiceMBean.CPU_TRACING or
112: * YourKitProfilerServiceMBean.CPU_SAMPLING | YourKitProfilerServiceMBean.CPU_J2EE
113: * or YourKitProfilerServiceMBean.CPU_TRACING | YourKitProfilerServiceMBean.CPU_J2EE
114: * @param filters string containing '\n'-separated list of classes whose methods should not be profiled.
115: * Wildcards are accepted ('*'). More methods are profiled, bigger the overhead. The filters are used with
116: * YourKitProfilerServiceMBean.CPU_TRACING only; with YourKitProfilerServiceMBean.CPU_SAMPLING the value is ignored.
117: * If null or empty string passed, all methods will be profiled (not recommended due to high overhead).
118: * For example, you can pass DEFAULT_FILTERS.
119: * @throws Exception if capture failed. The possible reasons are:
120: * <ul>
121: * <li>there's no Java application with properly configured profiler agent listening on port at host
122: * <li>specified profiling mode is not supported by the JVM of the profiled application, e.g. tracing is
123: * supported with Java 5 and newer and thus is not available with Java 1.4.
124: * <li>profiled application has terminated
125: * <li>agent cannot capture snapshot for some reason
126: * </ul>
127: * @see #captureSnapshot(long)
128: * @see #stopCPUProfiling()
129: */
130: public void startCPUProfiling(long mode, String filters)
131: 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: public 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: public 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: public 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: public 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: public void startCapturingMemSnapshot(final int seconds);
193:
194: /**
195: * Stops daemon thread started by {@link #startCapturingMemSnapshot(int)}
196: *
197: * @see # startCapturingMemSnapshot (int)
198: */
199: public 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: public long getStatus() throws java.lang.Exception;
244:
245: }
|