Using Probekit in stand-alone mode on Linux

Linux platform icon This section provides step-by-step instructions for using Probekit in stand-alone mode on Linux™ systems.

To use Probekit in stand-alone mode, Agent Controller must be installed on the target system. The data collection agent and the extension library for Probekit are automatically installed with Agent Controller.

Follow these steps to run your application using Probekit in stand-alone mode:

  1. Import a probe, or build your probe in the workbench.
  2. In your probe definition, include the special target specifications described in Specifying targets in probes for stand-alone Probekit.
  3. Copy all of the probe files to a folder on the target machine. If you are using multiple probes, concatenate the contents of the probescript files together into one probescript file.
  4. Add the folder that contains the probe files to the class path for the target machine.
  5. Add the RAC library folder and the Probekit plug-in folder to the target machine's LD_LIBRARY_PATH environment variable:
    <racInstallDir>/lib
    <racInstallDir>/plugins/org.eclipse.hyades.probekit/lib
  6. This final step differs depending on whether you are using JVMPI or JVMTI Probe Insertion.

    For JVMPI Probe Insertion in Stand-alone Mode:

    Add the following option string to the command line that launches your program:
    -XrunpiAgent:server=standalone,
    mode=none,
    extensionLibrary=ProbeAgentExtension.so,
    ext-pk-BCILibraryName=BCIEngProbe.so,
    ext-pk-probescript=<absolute_path_of_probescript_file>
    where <absolute_path_of_probescript_file> is the absolute path to the .probescript file for your probe. (e.g. <absolute_path_of_probescript_file> = /home/Project/Probes/myprobe.probescript). Note that this should point to the .probescript file and not the .probe file.
    Note: The option string above is displayed on multiple lines for readability. When you include the option string on your command line, it must be all on one line, with no embedded spaces.
    To have the Probekit agent write log messages, add the following options to the command line:
    Option Description
    ext-pk-logFile=<file> Specifies the name of the file you want the Probekit agent to write log messages to. <file> can be a full path and file name. If you specify standard error instead of a file name, the log output will be written to the standard error channel. If this option is not specified, no log output is written.
    ext-pk-logLevel=<level> Specifies the logging level you want to use. See the table below for the logging levels and their descriptions.
    You can specify the following logging levels:
    Level Description
    none Produces no log output.
    severe Logs only severe errors, such as unable to load libraries.
    warning Logs warning messages. This level is the default.
    info Logs status messages, such as "Initializing."
    config Logs configuration events and information, such as the contents of the .probescript file.
    finest Produces maximum log output. The log file will contain the name of every class that is instrumented by the Probekit agent.

    For JVMTI Probe Insertion in Stand-alone Mode:

    You will also need to ensure that $AC_HOME/plugins/org.eclipse.tptp.javaprofiler is included in your LD_LIBRARY_PATH.
    Add the following option string to the command line that launches your program:
    -agentlib:JPIBootLoader=JPIAgent:server=standalone;
    ProbekitAgent:ext-pk-BCILibraryName=BCIEngProbe,
    ext-pk-probescript=<absolute_path_of_probescript_file>
    where <absolute_path_of_probescript_file> is the absolute path to the .probescript file for your probe. (e.g. <absolute_path_of_probescript_file> =/home/Project/Probes/myprobe.probescript). Note that this should point to the .probescript file and not the .probe file.
    Note: You can also use -agentpath instead of LD_LIBRARY_PATH setting and -agentlib, please refer to Eclipse TPTP help document "Profiling and instrumenting applications > Profiling applications > Profiling an application > Profiling an application in stand-alone mode ".
        The option string above is displayed on multiple lines for readability. When you include the option string on your command line, it must be all on one line, with no embedded spaces.
    Option Description
    ext-pk-BCILibraryName optional; specifies base name of BCI library, default value "BCIEngProbe"
    ext-pk-probescript optional; standalone mode; specifies .probescript file
    ext-pk-dump optional; specifies location to write temporary dump files - must exist