Important This documentation space contains information about PATROL Agents when deployed in a BMC Helix Operations Management environment. If you are a TrueSight Operations Management user, see PATROL Agent 21.02.

Using fix_cache utility

The Event and Statistics cache can get corrupted at time due to various incidents such as an abrupt shut down of the PATROL Agent. You can fix the corrupted cache in two ways:

  1. [Recommended] Run fix_cache command-line utility.
  2. Set the /AgentSetup/integration/GDD/enableEventFixCache and /AgentSetup/integration/GDD/enableStatFixCache configuration variables to "yes" to automatically run recovery when the agent restarts.
    This method should not be used as default. Fixing the cache is a resource intensive process and if automatic cache fixing is set by default, during the PATROL Agent start-up there might be cyclic abnormalities.

This topic provides information about repairing the corrupted Event and Statistics cache using fix_cache utility.

Before running the fix_cache utility

  1. Create a backup of the existing cache files prior to running the fix_cache utility. The files are located at:
    • On Windows system: %PATROL_HOME%\log\streamcache\<HOSTNAME>\<PORTNUMBER>
    • On UNIX system: $PATROL_HOME/log/streamcache/<HOSTNAME>/<PORTNUMBER>
  2. Set the PATROL_HOME environment variable. 
    • On UNIX system running Korn and Bourne shell: ../patrolrc.sh 
    • On UNIX system running C shell: source.patrolrc
    • On older Windows systems Start > Settings > Control Panel > System > Environment; and type the variable name (PATROL_HOME) and value (the path), and click Set.
    • On newer Windows system Start > Settings > Control Panel > System > Advance, and click Environment Variables. Click New and type the variable name (PATROL_HOME) and value (the path). Then, click OK.

Running the fix_cache utility

Running the fix_cache utility requires shutting down the PATROL Agent for the entire duration of running the fix_cache utility. The length of the down time is directly related to the size of the cache. If these files are very large or any down time for the agent is undesirable, consider automatic recovery instead of running the fix_cache utility.

Warning

Ensure that adequate disk space is available on the system. A minimum of ten times the size of the cache will be required. During the cache repair, if the system runs out of disk space, all PATROL files will become inaccessible and other applications might also stop running.

  1. Stop the PATROL Agent.
  2. At the command line, run the fix_cache utility and monitor the output.

  3. Issue the following command to get the return code of the process: 

    #Unix
    $ echo $?
    #Microsoft Windows

    echo %errorlevel%

    See Return values for fix_cache utility section below for more information about return values.

  4. Repeat Step 3 and 4 till no more errors are reported.

Return values for the fix_cache utility

The fix_cache utility exits with one of the following values:

  • 0 — fix_cache completed successfully
  • 1 — fix_cache was aborted because of an error

Syntax for the fix_cache utility

The fix_cache utility has the following format:

  • [-port port]
  • [-host hostname]
  • [-queue_size]
  • [-rebuild_cache]
  • [-v]

The following table lists and defines the options recognized by the fix_cache utility:

 Options recognized by the fix_cache utility

Sample usage of the fix_cache utility

The following examples illustrate how to use the fix_cache utility.

  • To repair cache for an agent on a specific port
fix_cache -port 5000

This command fixes the cache and creates a backup of the cache file at port 5000.

  • To rebuild the cache
fix_cache -rebuild_cache

This command fixes the cache and rebuilds it.

  • To repair cache at a particular host
fix_cache -host host123 -port 3181

This command fixes the cache for host host123 at port 3181.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*