In Eclipse with appropriate plug-ins installed, you can select File / New / Other / Profiling and Logging / Probe Instance to create a new probe in your workspace. Probe instances should be placed in Java projects. The file name should end with “.probe” to identify it as a probe source file. (Probes need to be in a Java project because those projects already have many of the build actions required by the probe kit.)
Probes are created by writing an XML file whose structure matches the Probekit model. The file’s name should have the “.probe” suffix. This document does not describe the details of creating such files.
If, instead of creating a probe from scratch, you have received a *.probe file from somewhere else (by e-mail, perhaps), you need to import it into a Java project and follow the steps below to use it.
Every probe can contain a series of targeting or filtering expressions that say what classes and methods you want the probe to apply to. (If no targeting is specified, the default is to apply a probe to all methods of all classes.) To change the targeting for a probe, you have to edit the probe source file and recompile it. See the reference documentation for how the target expressions are evaluated to decide whether or not a given probe should be applied to a given class or method.
The *.probe file is the source code for a probe, just like a
*.java file is the source for a Java program: you have to compile it before it
can be used. The probe compiler generates class containing the fragment code
and supporting logic. It also generates a support file whose name ends in
“probescript” which contains instructions for the instrumentation engine,
telling it how to insert the probes into your project’s class and jar files.
To compile a probe, make sure you have saved any changes to it and then right-click on the *.probe file in the Package Explorer or Navigator view. Choose “Probekit / Compile” from the context menu. When the probe compiler runs, it generates a *.probescript file and a *.java file (which, in turn, is compiled into *.class files).
The *.probescript file will appear in the same directory as the *.probe file you selected. The compiled *.class files will appear in the default output directory of the project the *.probe file is in. By default this is the project directory, but Eclipse lets you configure this.
In addition, a new *_probe.java file appears in the same
directory as the *.probe file. This file contains the Java source code
generated from the *.probe file. It is not needed for using probes, but it can
be useful for debugging: you can find fragments and set breakpoints in them,
for example.
These are the new files that appear and their contents:
|
yourprobe.probescript |
The BCI engine script file you will use to instrument projects so they use these probes. |
|
yourprobe_probe.java |
The generated Java code for your probes. Useful for debugging probes. |
|
yourprobe_probe*.class |
Multiple class files, the output from compiling the generated Java code. These appear alongside the *.probe file, or in your project’s output directory if one is set. |
Note: the probescript file and java file will always appear after using the Probekit/Compile action, but the *.class files will only appear if your project is set to auto-build modified resources. If auto-build is not enabled, you have to invoke the build operation for this project manually.
If there are errors in the probe’s structure – if there are two fragments of the same type in the same probe, for example – the probe compiler will display an error message in an alert box and will not generate the Java, script, and class files.
[The fact that errors like this appear in an alert box is
a defect: they should appear in the task view.]
Also, there might be errors in compiling the Java code specified in the probe’s fragments. These are reported in the Tasks view. (Remember to refresh views with F5.) Note: if there are errors in the task view, selecting them will take you to the generated Java source file, not the original *.probe file. You need to examine the offending line in the generated Java file and figure out which of the fragments in the probe to fix.
[This manual “figuring out” step to correlate Java errors to fragments is a defect but it’s not temporary – it’s going to persist into Hyades 1.2 at least.]
Very often, a probe’s fragments will include references to outside classes and methods. In order to resolve these imports, you need to include them in the “Java Build Path” property of the Eclipse project containing the *.probe file. Otherwise the compile step will report errors.
A final note: the probe’s *.class files are placed in your project, but not all Eclipse views display them. Some Eclipse views (including the Java Perspective) filter out class files, so it might at first look like they’re missing. Use the Resource Perspective to see all files.
There is a command-line executable Java program called ProbeInstrumenter that you can use to apply your probes to class files, jar files, and entire directory trees. You will find it in the org.eclipse.hyades.probekit subdirectory of your Eclipse plugins directory. The program takes two arguments: the name of the *. probescript file to use, and the list of items to instrument. Items can be class files, jar files, or directories.
When the program instruments a class file it renames it to *.class.bak and puts the instrumented class file in its place. When the program instruments a jar file it instruments all the *.class files inside the jar file, renames the original jar file to *.jar.bak, and puts the instrumented jar file in its place. When the program instruments a directory it recursively descends into the directory tree processing the class files and jar files it finds, as described above.
Before you can use the command-line program for instrumenting your project, you must do some set-up. Here are the setup steps for Windows, assuming your Eclipse installation is at c:\eclipse:
Once you’ve done these setup steps, you can start a command shell window and run ProbeInstrumenter to rewrite your project’s class files on disk. Here’s an example command line:
java ProbeInstrumenter myprobe.probescript c:\project_path\myprogram.jar
You can supply class file names, jar file names, and/or
directory names. ProbeInstrumenter will replace the original files with
instrumented versions. It will rename the original class and jar files to
*.jar.bak and *.class.bak files.
Once you have instrumented your project’s class files and jar files with probes, the next step is to run the project. You do this the same way you would run it without probes, with one change: the run-time CLASSPATH must include the project directory where the generated *.class files appeared.
Here is one way to make sure the probe’s generated class files are in the run-time CLASSPATH when you run your project:
Now when you run your project using the modified configuration, the run-time CLASSPATH will include the directory where the generated probe class files appear.
If your probes refer to supporting class and jar files, they will need to appear in the run-time CLASSPATH also. Add the appropriate project or external directories to the run-time configuration as well.
[There are other ways to make Eclipse include the proper directories in the run-time CLASSPATH, but this easy enough.]
If you wish to run your instrumented project outside of Eclipse, you should edit the environment variable CLASSPATH so it refers to the directory where the probe’s class files appear. That will either be the directory that the probe file is in, or the default output directory of that project.
If you modify a probe and recompile it, the safest thing to do is to remove the instrumented files (as described above) and reinstrument your project. However, some kinds of changes do not require reinstrumentation – some changes affect only the *_probe.class files, not the instrumentation of your project’s class files.
If you change only the source-code parts of one or more fragments, you don’t need to reinstrument your project to use the modified probe. This includes the Fragment at Class Scope. You can also change the imports of a probe without reinstrumenting. You must reinstrument if you add or remove a fragment, change the type of a fragment, or change, add, or remove any data items in a fragment. Also, if you change a probe’s target specification, you should reinstrument those class and jar files that would be affected by the change.
A single *.probe file can contain multiple probes. Usually this means the probes are interrelated in such a way that you always use them together. If you want to use probes from multiple files simultaneously, you can compile them separately and still use them together. The way to do this is to concatenate the generated *.probescript files together into a single file, use that file as the engine script argument for the ProbeInstrumenter command described above.
Another way to combine multiple probes is to create a single *.probe file that has all the probe elements you want in one place. Compile the combined *.probe file and use the (single) resulting *.probescript file and the generated class files.
When the Instrument command replaces class and jar files on disk with instrumented versions, it saves the original file with a *.bak extension. To remove instrumentation, delete the instrumented class and jar files and restore them from the *.bak files. Alternatively, you can use “Rebuild project” or “Rebuild all” from the Eclipse Project menu to regenerate your project from its source code.