Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Linux Tools Project/OProfile/User Guide"
Line 12: | Line 12: | ||
== Step 1 - Locate Plug-in Installation Directory == | == Step 1 - Locate Plug-in Installation Directory == | ||
Open up a terminal and locate the <code>scripts</code> directory. The install script is located in the <code>org.eclipse.linuxtools.oprofile.core</code> plug-in directory, but this directory can be in a few places: | Open up a terminal and locate the <code>scripts</code> directory. The install script is located in the <code>org.eclipse.linuxtools.oprofile.core</code> plug-in directory, but this directory can be in a few places: | ||
− | * If you are using a distro-supplied version of Eclipse and installed the plug-in via the update site, it will most likely be under the <code>~/.eclipse</code> directory, hence | + | * If you are using a distro-supplied version of Eclipse and installed the plug-in via the update site, it will most likely be under the <code>~/.eclipse</code> directory, hence use the command: |
::<code>find ~/.eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'</code> | ::<code>find ~/.eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'</code> | ||
− | * Alternatively, if you are using an extracted tarball of Eclipse (ie: you downloaded a .tar.gz from [http://www.eclipse.org/downloads/ here]) then the plug-in will most likely be in the plugins sub-directory of where you extracted it. Let's say you extracted the tarball to <code>/home/ksebasti</code>, so your Eclipse installation would be in <code>/home/ksebasti/eclipse</code>, then | + | * Alternatively, if you are using an extracted tarball of Eclipse (ie: you downloaded a .tar.gz from [http://www.eclipse.org/downloads/ here]) then the plug-in will most likely be in the plugins sub-directory of where you extracted it. Let's say you extracted the tarball to <code>/home/ksebasti</code>, so your Eclipse installation would be in <code>/home/ksebasti/eclipse</code>, then use the command: |
::<code>find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'</code> | ::<code>find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'</code> | ||
Line 87: | Line 87: | ||
=== View Tree === | === View Tree === | ||
− | * Double-clicking on a [[Image:Icon-oprofile_sample.gif]]sample will open the source file and place the cursor at that line | + | * Double-clicking on a [[Image:Icon-oprofile_sample.gif]]sample will open the source file in an editor and place the cursor at that line. |
− | ** Note this requires that the source code is available and is in the correct directory (as described in the binary's debug info) | + | ** Note this requires that the source code is available and is in the correct directory (as described in the binary's debug info). |
+ | |||
=== View Menu === | === View Menu === | ||
+ | * Open OProfile Daemon Log | ||
+ | ** This will launch a dialog showing the contents of the oprofile daemon log (by default in /var/lib/oprofile/samples/oprofiled.log): | ||
+ | [[Image:Screenshot-oprofiled_log_reader.png]] | ||
+ | |||
+ | |||
+ | * Refresh View | ||
+ | ** This will re-read the OProfile data on the system, re-create the internal data model and re-display the profile tree. Useful to display data already on the system without launching a profile. | ||
= Profiling Configuration = | = Profiling Configuration = | ||
Line 105: | Line 113: | ||
* install script fails | * install script fails | ||
* no samples | * no samples | ||
+ | * log reader hanging |
Revision as of 17:21, 16 April 2009
{{#eclipseproject:technology.linux-distros}}
Getting Started
The OProfile plug-in requires a little extra set up compared to other Eclipse plug-ins. However, it only takes a few simple steps and only needs to be done once. After the plug-in is first installed, running most profile-related commands will bring up a dialog similar to the following:
As the dialog suggests, you must run the supplied install script to allow the plug-in to perform OProfile tasks as root (since OProfile can not be run as an unprivileged user). The steps below are the same as the dialog but described in more detail.
Step 1 - Locate Plug-in Installation Directory
Open up a terminal and locate the scripts
directory. The install script is located in the org.eclipse.linuxtools.oprofile.core
plug-in directory, but this directory can be in a few places:
- If you are using a distro-supplied version of Eclipse and installed the plug-in via the update site, it will most likely be under the
~/.eclipse
directory, hence use the command:
find ~/.eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'
- Alternatively, if you are using an extracted tarball of Eclipse (ie: you downloaded a .tar.gz from here) then the plug-in will most likely be in the plugins sub-directory of where you extracted it. Let's say you extracted the tarball to
/home/ksebasti
, so your Eclipse installation would be in/home/ksebasti/eclipse
, then use the command:
find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'
Note that the quotes (') and asterisk (*) are necessary. Example output will look something like this:
$ find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core_*'
/home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core_0.2.0.200904131051
Then, change the sub-directory natives/linux/scripts
of this plug-in directory:
cd /home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core_0.2.0.200904131051/natives/linux/scripts
Note that if you are not the root user while performing these commands, you may have to become the root user and re-execute them in Step 3.
Step 2 - Choose Which Installation Script To Run
In the scripts
directory there are two scripts, install.sh
and install-noconsolehelper.sh
. Both scripts will do some sanity checks to ensure OProfile is installed and that opxml, a C++ program required to interface with OProfile, exists and can be run. The difference is in how root authentication with the plug-in is set up.
-
install.sh
uses the pluggable authentication modules (PAM) mechanism. This is the default and recommended method for root authentication. When an OProfile task is required, you will be presented with this dialog to enter the root password:
-
install-noconsolehelper.sh
can be used when consolehelper is not present on the system, or if required PAM modules are not on the system. It uses the sudo mechanism and a small wrapper script. The install script will describe the text which should be written in thesudoers
file, then run the commandvisudo
to edit it. Note that thesudoers
file is a sensitive system file and altering it in other ways may lead to system instability. Only users with enough knowledge of running a Linux system should use this method. For these reasons, this method of root authentication is discouraged. However, it may be the only option available to some users and it has been tested to work by developers and users of the plug-in.
Step 3 - Running The Install Script
Now simply run the install script (assuming you are in the scripts
directory as in #Step 1 - Locate Plug-in Installation Directory):
./install.sh
Successful output will look like this:
# ./install.sh
Eclipse-OProfile plugin install successful.
Note that the install script must be run as the root user, since both install scripts have some actions which require root -- install.sh
places files in /etc
sub-directories and install-noconsolehelper.sh
runs the command visudo
. If you are not already the root user, this command will run only the install script as the root user, then return control to the regular user:
su -c './install.sh'
Successful output will be the same as above. If instead you receive error messages, refer to the Troubleshooting section at the bottom of this page.
Step 4 - Restart Eclipse
That's it! Simply restart Eclipse by clicking File -> Restart and you should be good to go.
Note that if you need to uninstall the plug-in, run the uninstall.sh
or uninstall-noconsolehelper.sh
script in the scripts
directory before uninstalling it from within Eclipse.
OProfile View
The OProfile view is the central point of interaction of the plug-in with the results of profiling.
Tree Structure
The tree structure shown above describes one or more profiles of one or more events in the following manner:
- Events -- the name of the profiling event used by OProfile
Note that if source code is not available, then there may be symbols shown (including source file name) but no samples. This is usually the case with shared libraries. As well, depending on the #Global Settings, there may be no dependent images shown.
Features
This section describes the features of the plug-in exposed through the view.
View Tree
- Double-clicking on a sample will open the source file in an editor and place the cursor at that line.
- Note this requires that the source code is available and is in the correct directory (as described in the binary's debug info).
View Menu
- Open OProfile Daemon Log
- This will launch a dialog showing the contents of the oprofile daemon log (by default in /var/lib/oprofile/samples/oprofiled.log):
- Refresh View
- This will re-read the OProfile data on the system, re-create the internal data model and re-display the profile tree. Useful to display data already on the system without launching a profile.
Profiling Configuration
- blah
Global Settings
- blah
Event Configuration
- blah
Troubleshooting
- install script fails
- no samples
- log reader hanging