General Topics

1. What is remote data collection?

Remote data collection is the ability to:

The VTune™ Performance Environment enables you to launch applications and perform data collection on Remote Agent systems. The Remote Agent system only needs a small subset of the VTune™ Performance Environment product files. You can perform data collection on a number of Remote Agent systems, each running a different supported operating system.

2. What is required for remote data collection?

For remote data collection, two systems are required:

•  Client system running on a Microsoft* Windows* operating system, which configures and manages Activities, and displays data collection results

• Server system running on a Linux* operating system, the Remote Agent, which handles the remote data collectors and sends the results to the client system for display

The following scheme shows the relationship between the components on these systems:

              Windows* <-+->   ittserver  <--->  collector1.so ... . . collectorN.so
        Client in VTune™|         server                      data collectors
Performance Environment  |
                         |
                         |
        <-- Windows* --> | <------------------ Linux ---------------------->

The Remote Data Collection Server ittserver is a shared component of Intel® Thread Checker and Intel® Thread Profiler. Before starting the remote data collection server, configure your Linux* system properly. See product Release Notes for configuration requirements.

Remote data collection procedure as shown above follows the steps below. 

1.  At startup, ittserver initializes all its data collectors and begins listening for requests on a specified IP port 50002.

2. The Windows* client sends a message to the server and waits for reply.

3. The server dispatches that message to the remote collector and then continues listening for more requests from the Windows* client.

4.  After finishing the current Activity run the collector notifies the server, which in turn notifies the Windows* client. If requested, the server also sends data resulting from the task back to the Windows* client. The Windows* client displays the resulting data for your analysis.

Each collector has its own set of requirements. If a collector's requirements are not met, or if an error occurred during a collector's initialization, then the server may continue to run, but access to the collector is disabled.

Intel(R) Thread Checker Specific Issues

1. How does Intel(R) Thread Checker remote data collection work?

Thread Checker remote data collection works in the following way:

 Upon successful completion, data generated during the Thread Checker remote data collection is transferred to the Thread Checker on Windows* for you to view and analyze.

2. How can I stop an application during remote work?

 In Thread Checker for Windows*, click the red stop button.

 If that fails, kill the application process manually using the command kill -9 <PID>.

WARNING

If you interrupt data collection, Thread Checker might not display complete Activity results.

3. What can I do if Intel(R) Thread Checker hangs?

 In your Windows* terminal, consider the screen where ittserver was running. You may have pressed Ctrl-S or clicked a mouse to select another mode in the Windows* terminal.

 Make sure that the ittserver is not suspended: press Ctrl-Q or ESC.

TIP

Avoid suspending ittserver output. Doing so can cause the application to hang until you restore normal ittserver output.

4. The set of signals used by Thread Checker remote data collector conflicts with signal handling in my application. How can I resolve this?

One of the methods to stop a running application is to send a special signal to the  processes of the application. The default signal is SIGUSR2, but if this signal is already used by the application, specify an alternative signal number, which can be handled by applications in the __Bistro_Exit_Signal__ environment variable. Signal numbers may be found in <bits/signum.h> standard header file.

5. Where are temporary Thread Checker remote data collector files stored on the Linux* side?

Two potentially different directories are used on the Linux* system to store temporary data.

1. Thread Checker remote data collector cache directory. The default location is /tmp/tc_<windows_login>_cache.
   You can change the default in the Thread Checker on Windows*, Configure->Options->Intel® Thread Checker->Collector->Cache Directories.

2.  ittserver data directory. The default locations are <current directory>/.bistro_server and <current directory>/.bistro_temp.

NOTE

Both directories must be world writable.

6. Can I set the duration for a Thread Checker remote data collection session?

No. Currently, the Thread Checker remote data collector ignores the duration setting.

7. How can I pass environment variable settings to an application on Linux*?

You can pass environment variables to an application on Linux* in one of the following ways:

Before starting ittserver

1. Set any environment variables required by the application.

2. Start ittserver.

Before launching an application

1. In Thread Checker for Windows*, go to the Advanced Activity Configuration dialog box and under Application/Module Profiles, select the application and then click Configure. The General dialog box appears.

2. Click Advanced, deselect Use default environment, and enter environment variables in the form "VARIABLE=value" (for example, "FOO=3").

3. Click OK to save your settings.

Create a shell script

1. Write a shell script that sets the variables and runs the application.

2. In Thread Checker on Windows*, configure your Activity by specifying your shell script as the application to launch and define an executable name as the module of interest.

NOTE

If you set an environment variable that is intended to change default paths for dynamically linked libraries, such as LD_LIBRARY_PATH or LD_ASSUME_KERNEL, you must do so before starting ittserver.

8. In Thread Checker, I specify a Linux* application to launch, but the application does not run. Why is that?

Verify that the following conditions are met to launch a Linux* application:

9. I'm running ittserver as root, but ittserver has problems accessing files. Why is that?

If the files are located on a networked file system (for example, through NFS*, AFS*, or Samba*), then restrictions may exist on root access to those files or directories containing those files. Check with your system administrator for details.

NOTE

It is highly recommended that ittserver be run as a non-root user. If multiple users need to use ittserver, then add those users to a special group and make sure that the relevant files and directories can be accessed by members of the group. Then run ittserver as one of the non-root members of the group.

10. When I try to look at Source View for Linux* binary, Thread Checker prompts for the location of the source file. Why is that?

Currently, the matching of Thread Checker data to source is done in Thread Checker on the Windows* side. When Thread Checker encounters a reference to a Linux* source file for the first time, it prompts you for the location of where to retrieve the file. Retrieve the file in one of the following ways:

• Manually copy it from Linux* to Windows*. The file location must follow the Windows* filename syntax, for example, DRIVE:\path\to\sourceFile.

•  Export the remote Linux* file system through NFS*, AFS*, Samba*, or similar. The file location must follow the appropriate Windows* filename syntax, for example, \\linuxMachineName\path\to\sourceFile if not mapped to a DRIVE: <letter>, or DRIVE:\path\to\sourceFile contact your system administrator for details.

Once Thread Checker matches the source against Thread Checker data, the tool caches the source location. Subsequent use of the same source will re-use the cached location. If Thread Checker detects that the binary has changed, or if the cached source location for that binary has been cleared, then the Thread Checker again prompts you for the location of where to retrieve the source file.

NOTE

The source location cache can be cleared by going to the Configure->Options->Directories->File Association dialog box in the VTune™ Environment on Windows*.

11. Can Thread Checker collect data remotely on multiple (different) applications simultaneously?

No. Currently, only one application may have a Thread Checker remote data collection session. This single application must be specified inside the application in the module of interest field in the Application/Module Profile Configuration dialog box.

12. Can multiple users on the same Linux* system run their own Thread Checker remote data collection sessions simultaneously?

No. Currently, multiple users on a Linux* system cannot perform Thread Checker remote data collection at the same time. Users must coordinate their Thread Checker remote data collection sessions at different (non-overlapping) times on the same Linux* system.

13. How do I fix issues with the Intel® Compiler and its -tcheck switch?

The following are known issues and recommended solutions related to using the Intel® Compiler the -tcheck switch:

1. While building with the -tcheck switch and during the linkage phase of my compilation, I get messages such as "Undefined reference to local symbols in discarded section .gnu.linkonce.t".
   
   The solution to this linkage failure is to install the Intel® Compiler package as recommended in the Release Notes. With this compiler, you also need to use the linker option -ltcdata. This option includes a linker script into the build to combine all of the "Implicit Program Database Mode" (the default) information, so that the information from all of the object files is available in the final build executable or library:
% icc -tcheck foo.c -ltcdata

2. I can compile my application with -tcheck and run the instrumented application, but I do not see any symbolic information when I view the Activity result file on Windows* with Thread Checker.
   The problem may be the use of inline-assembler in the compiled code. This inline-assembler may come from a system header file or might have been found in the application source code.
   When the GNU* gcc library compatibility mode is enabled, system header files include inline assembly code. To disable the mode, switch to the Intel® Compiler library compatibility mode as follows:

   % icc -ccxlib-icc -tcheck foo.c -ltcdata

   If you still do not see the line numbers and functions names in the Thread Checker diagnostics view on your Windows* system, you may still be using inline assembler. To get symbolic information in the presence of in-line assembly code, try one of the following:

   o        Switch from source instrumentation to binary instrumentation.

   o        Switch from the default Implicit Program Database Mode to the Explicit Program Database Mode.

3. I can compile the application with the -tcheck option, but I get linkage failures indicated by error messages such as "relocation truncated to fit: PCREL21B".
   The problem is that the instrumented object files are larger than the system limit (typically 16MB). To work around this limitation, switch to the Explicit Program Database Mode. In this mode, the symbolic information is stored in a separate external database directory and does not count against the size limit of the object files.

14. How do I use Intel® Thread Checker in Explicit Program Database Mode?

To analyze an application using Explicit Program Database Mode, do the following:

Note

All of the following examples are for the Intel® C++ Compiler for Linux*. You can also use this mode with the Intel® Fortran Compiler for Linux*.