Running a distributed analysis

An example setup follows this section.

To run a distributed analysis:

1. Start the Distributed Analysis Server.

   If it is not already running, start the Klocwork Distributed Analysis Server with kwdist:

   Distributed-Analysis-server-host$ kwdist [--port <port-number>]
   

   where<port-number> is the port on which you want to run the Klocwork Distributed Analysis Server (default: 3440)

2. Register one or more Distributed Analysis Agents.

   On each machine that will be sharing the analysis load, register at least one Klocwork Distributed Analysis Agent (if none are already registered) with kwagent. See 'Guidelines for how many agents and jobs to run' below for help in deciding how many agents to register.

   Agent-host$ kwagent --host <Distributed-Analysis-server-host> --port <Distributed-Analysis-server-port>
   

   where

   <Distributed-Analysis-server-host> is the host where you started the Distributed Analysis Server with kwdist (default: localhost)

   <Distributed-Analysis-server-port> is the port on which the Distributed Analysis Server is running (default: 3440)

3. Start the Klocwork analysis.

   On the machine that runs the Klocwork integration build analysis, run kwbuildproject with the following options:

   --remote to run the analysis engine remotely through the Distributed Analysis Server

   --dist-host to specify the Distributed Analysis Server host (default: localhost)

   --dist-port to specify the Distributed Analysis Server port (default: 3440)

   --jobs-num to specify the maximum number of parallel compilation and issue detection processes to run. See 'Guidelines for how many agents and jobs to run' below for help in deciding how many jobs to run.

   build-host$ kwbuildproject --tables-directory <tables_directory> --remote --dist-host <Distributed-Analysis-Server-host> --dist-port <Distributed-Analysis-Server-port> --jobs-num <int> <build-specification>

   Example

   build-host$ kwbuildproject --tables-directory /opt/Klocwork/work/krusader/build_1/tables --remote --dist-host server01.acme.com --dist-port 3460 --jobs-num 6 /usr/local/krusader-1.60.0/krusader.out

   For more information on running a Klocwork integration build analysis, see Running the C/C++ integration build analysis.

4. Complete the Klocwork analysis.

   See Load the analysis results into the Klocwork database.

   Note: During and after the analysis, you can manage and retrieve all statistics for a distributed analysis session with the command kwdistadmin stat. kwdistadmin is run on the Distributed Analysis Server host.

Guidelines for how many agents and jobs to run

For best performance, use the following guidelines to calculate the recommended number of distributed analysis agents and kwbuildproject jobs to run.

Please note that performance depends on many factors, including hardware configuration, your operating system, the complexity of your software project, and the average source file size.

Notes:

• The Build Host is the host where kwbuildproject is run.
• You specify the number of kwbuildproject jobs with the --jobs-num option.
• The "auto" value for the --jobs-num option is not supported for distributed analysis. You must specify an integer between 1 and 32.

For example, if we have a quad-core Build Host machine:

Minimum recommendation

• Number of agents: 12 (4 processors * 3 agents per Build Host processor)
• Number of jobs: 13

Maximum recommendation

• Number of agents: 24 (4 processors * 6 agents per processor)
• Number of jobs: 25

Recommended number of Agent hosts

Klocwork suggests running one agent per Agent host processor core. For example, to run 24 agents:

• Quad-core Agent host machines: 6 (24 agents / 4 processors)
• Dual-core Agent machines: 12 (24 agents / 2 processors)

Example setup

The following diagram shows an example setup, which is used in the following walk-through. Note that the Distributed Analysis Server can also run on the Build Host.

Example: Running a distributed analysis

In this example, we have a quad-core Build Host machine (the machine running kwbuildproject).

We need to calculate the maximum number of agents and jobs this machine can support.

• We calculate the maximum number of agents by multiplying the number of Build Host processors by 6, so our maximum number of agents is 24.
• We calculate the number of jobs by adding 1 to this number, so our maximum number of jobs is 25.

Now we need to calculate how many Agent Host machines we need.

• Given the recommendation of one agent per processor core, if our machines are quad-core machines, we will be able to run 4 agents on each host. This means we will need 6 remote Agent host machines.

As shown in the diagram, our configuration will be as follows:

• Machine A: Distributed Analysis Server Host (kwdist)
• Machine B: Build Host (kwbuildproject)
• Machines C through H: Remote Build Hosts (kwagent)

We can now run a distributed analysis:

1. Machine A: Start the Distributed Analysis Server.

   kwdist

   We're running the server on the default port, 3440, so we don't need to specify the --port option.

2. Machines C through H: Register four Distributed Analysis Agents on each of the six Remote Build Hosts, specifying the host name of MachineA with the --host option.

   kwagent --host <MachineA>

3. Machine B: Start the Klocwork analysis, specifying 25 jobs.

   kwbuildproject --tables-directory /opt/Klocwork/work/krusader/build_1/tables --remote --dist-host <MachineA> --jobs-num 25 /usr/local/krusader-1.60.0/krusader.out

4. Machine B: Complete the Klocwork analysis by loading the database.

   kwadmin load krusader1_60 /opt/Klocwork/work/krusader/build_1/tables

Running a distributed analysis on multiple Unix platforms

If you have installed Klocwork on multiple Unix platforms, you can start the Distributed Analysis Server from any of the installations, and you can run Distributed Analysis Agents on Linux, Solaris, and AIX hosts.

Notes

• All of the Klocwork Distributed Analysis installations must be visible from the same file system. The Distributed Analysis Server needs access to the C/C++ analysis engines for the various platforms.
• Klocwork recommends that you run all agents from the same version of Klocwork software. Otherwise, their reports will differ, and different issue types will be detected for source files compiled on different agents.

The following procedure uses a Linux and Solaris example.

To configure distributed analyses for multiple Unix platforms:

1. In your Linux installation of Klocwork, open the following file for editing:

   <Linux_Klocwork_dir>/config/compilation_kits.xml
   

2. Edit the "path" attribute for the second "kit" tag so that it contains the absolute path to the Solaris installation.

   <kit config="sparc-sun-solaris2" path="/opt/kw/developers/work/Klocwork_Solaris">
   

3. Save and close the file.
4. In your Solaris installation of Klocwork, open the following file for editing:

   <Solaris_Klocwork_dir>/config/compilation_kits.xml
   

5. Edit the "path" attribute for the first "kit" tag so that it contains the absolute path to the Linux installation.

   <kit config="ix86-pc-linux" path="/opt/kw/developers/work/Klocwork_Linux">
   

6. Restart the Analysis Server with the command kwdist.
7. Restart the Analysis Agents with the command kwagent.

Example

In this example, we have two installations:

• /opt/kw/developers/work/Klocwork_Linux
• /opt/kw/developers/work/Klocwork_Solaris

Each of them contains binaries for a single platform.

Edit compilation_kits.xml for the Linux installation as follows:

<?xml version="1.0"?>
<compilation_kits>
    <common_files>
        <file relative_path="plugins/builtin_ccxx_plugins.xml"/>
    </common_files>
    <kit config="ix86-pc-linux"> <!-- no path attribute here -->
        <file relative_path="exec/ix86-pc-linux/REPCXX"/>
        <file relative_path="plugins/ix86-pc-linux/kwsecliba.so"/>
        <file relative_path="plugins/ix86-pc-linux/kwseclibp.so"/>
    </kit>
    <kit config="sparc-sun-solaris2" path="/opt/kw/developers/work/Klocwork_Solaris">
        <file relative_path="exec/sparc-sun-solaris2/REPCXX"/>
        <file relative_path="plugins/sparc-sun-solaris2/kwsecliba.so"/>
        <file relative_path="plugins/sparc-sun-solaris2/kwseclibp.so"/>
    </kit>
</compilation_kits>

Edit compilation_kits.xml for the Solaris installation as follows:

<?xml version="1.0"?>
<compilation_kits>
    <common_files>
        <file relative_path="plugins/builtin_ccxx_plugins.xml"/>
    </common_files>
    <kit config="ix86-pc-linux" path="/opt/kw/developers/work/Klocwork_Linux">
        <file relative_path="exec/ix86-pc-linux/REPCXX"/>
        <file relative_path="plugins/ix86-pc-linux/kwsecliba.so"/>
        <file relative_path="plugins/ix86-pc-linux/kwseclibp.so"/>
    </kit>
    <kit config="sparc-sun-solaris2">  <!-- no path attribute here -->
        <file relative_path="exec/sparc-sun-solaris2/REPCXX"/>
        <file relative_path="plugins/sparc-sun-solaris2/kwsecliba.so"/>
        <file relative_path="plugins/sparc-sun-solaris2/kwseclibp.so"/>
    </kit>
</compilation_kits>

You can start the Distributed Analysis Server from either the Solaris or the Linux installation, and in each case you can use either Linux or Solaris agents.

Stopping the Distributed Analysis Server or agents

To stop the Distributed Analysis Server, use the command kwdistadmin stop-server.

To stop one or more agents, use the command kwdistadmin stop-agent.