Share:|

We have seen a rise in interest regarding custom Knowledge Modules (KM) and importing them into BMC ProacitveNet Performance Manager (BPPM). While we have touched on this topic before, we can expand it a bit more with a few more details and even a Best Practices Document for future reference. The questions does come up from time to time about how to import the custom KMs so let’s refresh our knowledge and/or learn something new depending on your comfort level with custom KMs.

 

First off, if you have not done so, please watch the BPPM Webinar recording done by BMC’s own Hutson Meeks where he discusses this topic for BPPM. Enabling Custom Knowledge Modules for BPPM 9.5 can be found here:  https://communities.bmc.com/docs/DOC-31482

This presentation is very similar to the details in this post but Hutson provides his expertise and tips.

 

High-level Process Workflow

It is recommend that you enable custom KMs for BPPM 9.5 in three major phases in the order listed below.

 

 

1)    Data Collection Enablement

2)    Policy Configuration Management Enablement

3)    Menu Command Enablement

 

 

You should completely test and validate the results of each phase before moving on to the next phase.

 

 

NOTE: If you choose to not enable Policy Configuration Management or Menu Commands the KM can still collect data into the BPPM 9.5 server and the KM configuration can be managed by agent configuration settings defined as rules in the Configuration Variables section of a monitoring policy.

 

 

Required Tools

The following tools are required to support the process of enabling, importing, testing and enabling PATROL Knowledge Modules for BMC ProactiveNet Performance Management 9.5.

 

 

1) BPPM 9.5 Server with CMA installed and operational

2) BPPM 9.5 Integration Service node installed and operational

3) BPPM 9.5 PATROL Agent installed and integrated with the BPPM 9.5 infrastructure

4) PATROL Classic Console version 3.6.00.1 (version 3.6.00 with the patch applied) or higher

5) PCIG Utility (Available with the PATROL common installer v9.6 under …\bmc_products\tools\pcig\ )

6) A common compression utility such as zip delivered with RHEL 6.4

 

 

All of these tools should be installed in a development environment.  Do not attempt to configure KMs for BPPM 9.5 in a production environment.

 

 

Enabling Data Collection Workflow Steps in Detail

The following steps provide details covering the entire process of enabling data collection with a custom KM for BPPM 9.5.  These steps should be completed in the order listed.  Attention to specific details should be observed, and recommendations should be followed.  Failure to follow these steps may result in unexpected or unintended results.

 

 

1) Validate that the custom Knowledge Module monitors and collects data in PATROL as designed and expected.  This is irrespective of BPPM.

2) Install and configure the tools listed under the Required Tools section above.

3) Deploy the custom Knowledge Module to be enabled to a test agent and the PATROL Classic Console using the latest version of the console.

4) Launch the PATROL Classic Console in Developer mode and load the custom Knowledge Module.  Load any dependent Knowledge Modules as well.

5) Configure the agent to operate in non-Policy mode and ensure the agent is not connected to a BPPM Integration Service node.

6) Add meta data settings to the Knowledge Module.

AppPropertiers160.pngParameterPropers2.png

 

 

7) Save the KM.

8) Commit the KM.

9) Validate that the Knowledge Module continues to monitor properly in PATROL.

10) Exit the PATROL Classic Console

11) Edit or create the KML file.  This file should contain a list all *.KM files to be loaded like it has been used in previous versions of PATROL.  Additionally, it is a best practice to add values for both the MetaKMLDisplayName and the MetaKMLDiscription in the KML file as shown in the example below.

!PATROLV3.2.0   FF08BBD43AC9210A8C6C41C85A315D3F

!++

!

! PATROL Session Knowledge Module

!

!--

! MetaKMLDisplayName = "Log Values"

! MetaKMLDescription = “KM that monitors numeric values from log file annotations”

KM_LIST = {

    "LOG_VALUES.km"

}

! 9999

12) Edit the Knowledge Module file adding release and revision information to the header of the KM file.  This should include the following information.

•    RELEASE number

•    REVISION number

•    PACKAGE value

•    DESCRIPTION

•    PRODUCTCODE

Example data from a KM file is shown highlighted below.

!PATROLV3.6.00.1i 3EC3A0E66408BF2FDB85D058CB4597BBE7EC56BBDB4BCA4A2D59D74EE5B65E7F

!#MSG_DOMAIN    km_sec

!++

!

! PATROL Session Knowledge Module

!

!—

!RELEASE    1.0.00

!REVISION    00

!PACKAGE    plv

!DESCRIPTION    PATROL Knowledge Module for Log Values

!PRODUCTCODE    plv

!PRAGMA allow: all

NOTE:  Both the PACKAGE value and the PRODUCTCODE should be a unique value specific to the custom KM.  Do not use BMC Software package values and/or product codes.  You can get a list of currently used values in your environment from the BPPM server where CMA is installed and used.  A list of these values is in the solution_list.xml and Solution_Mapping.xml files.  You can find these files in the following directory on the BPPM server where CMA is installed.

 

On UNIX/Linux: $BPPM_SERVER_HOME/pw/pproxy/depot_directory/bmc_products

On Windows:     %BPPM_SERVER_HOME%/pw/pproxy/depot_directory/bmc_products

Review the content of these files on your system if you are not certain.

 

NOTE:  If you do not enter the release and revision information into the KM file(s) the related application classes will not be processed in the BPPM server.  When the agent connects to the IS node the application classes without release and revision information will be rejected and an error event will be generated as shown below.

 

UnableToPRocess.png

13) Copy all the files related to the custom Knowledge Module to a backup directory.

a.    KML file

b.    KM files

c.    PSL files

d.    LIB files

e.    Etc.

14) Apply agent configuration rules to the agent so that the custom KML is in the KM preloaded list and the agent is configured to connect to the BPPM 9.5 test Integration Service node.

15) Stop the PATROL Agent.

16) Delete all the files related to the Knowledge Module from their respective PATROL Agent directories and the PATROL Classic Console cache.  You will be reinstalling them using a silent install package that you create in the BPPM 9.5 CMA Deployable Packages Repository.

17) Create a subdirectory for the custom Knowledge Module under the location where you have installed the PCIG utility. For example if you installed the PCIG utility in the directory shown below, create a directory for the custom Knowledge Module there as shown.  In this example the custom Knowledge Module is named LOGVALUES.

LinuxOutput4.png

 

18) Create respective sub-directories for all the Knowledge Module files under the location where you have installed the PCIG utility.   See example below.

Output4.png

 

 

 

19) Copy all the Knowledge Module files from the backup location to their respective directories under the directory you created for the custom Knowledge Module.  If you are providing a default configuration settings in a PATROL agent configuration “cfg” file (or a filename.current file) copy the file to the lib directory under the directory you created for the custom Knowledge Module with the same name.  See example shown below.

Output5.png

 

20) Run the PCIG utility from the directory it is installed in and source the Knowledge Module files from the subdirectory you created for the custom Knowledge Module.  Enter the same syntax as shown below for all command line arguments.  In this example, the Knowledge Module files are in their respective subdirectories under the LOGVALUES directory as noted above.

./pcig -p plv -r 1.0.00 -s LOGVALUES/ -l ALL -t LogValues

The following table lists the command line arguments with the example values from the command above.  (This was run on Linux.Windows follows the same format.)

Table6.png

Argument    Purpose    Example    Comments

-p    product    plv    Enter a value that does not match or conflict with any other products.

-r    release number    1.0.00    Enter a 3 segment value.  Do not enter only one or two segments.  (For example 1 and 1.0 would not work.)

-s    location of all source files and their respective sub directories    LOGVALUES/    This is the top level directory under which custom KM files are stored.  The subdirectories must follow the same structure as a normal PATROL Agent and KM install.  This directory should be a subdirectory in the directory where you are running PCIG. Use this syntax exactly with the proper subdirectory name followed by a forward slash at the end.  The following is an example.  Suppose you are running the PCIG utility in /home/patrol to create a package for the “Log Values” custom KM.  The directory structure for the tag you are creating a package for would look like this:

 

/home/patrol/LOGVALUES

/home/patrol/LOGVALUES/lib

/home/patrol/LOGVALUES/lib/psl

/home/patrol/LOGVALUES/lib/knowledge

 

-l    comma separated list of supported OS types    ALL    Make sure this matches the Knowledge Module design

-t    product title name    LogValues    This is the name of the compressed ZIP file that is generated to be imported.

 

 

 

Note: Command line argument information can be displayed at a command prompt by running the PCIG utility with no arguments as shown.

[root@BPPMRHEL62-HM LINUX-X64-64]# ./pcig

PATROL Common Install generator v9.5.00 (build:20140921815)

Usage: pcig.exe -p product -r release -s source_path [-l os_list] [-t title] [-c]

-p <product>:  Required name (also specifies name of output ppf file without ".ppf")

-s <source_path>: Required path to package member files.  The files under <source_path> are copied to <dest_path>/products/<product_name> and gzipped, and their respective entries are added under the files section of the ppf.  The ppf and cat file are placed in  <dest_path>/Products/<product_name>, and a copy of the ppf is also placed in <dest_path>/Index/.

-r <release>: the version (vv.mm.rr) of the package to be used with BPPM in the format of.

-l <os_list>: comma separated list of OS types (possible values: AIX,SOLARIS,HP-UX,LINUX,WINDOWS,ALL,ALL-UNIX).

-t <title>: Product name, to be used on the BPPM CMA repository UI

 

The PCIG utility will create a bmc_products directory and a ZIP file for the solution.   Below is an example output when running the PCIG utility.

Output7.png

 

NOTE:  At the time this documentation was created the compressed ZIP file generated by the PCIG utility was not importable to the CMA Monitoring Repository.  To resolve this you should recursively compress the bmc_products directory that is created by the PCIG utility and import the ZIP file generated

21) Compress the bmc_products directory that was created by the PCIG utility into a ZIP file.  Do not attempt to use the folder compression capability that is built into Microsoft Windows.  Use a commonly used compression utility such as the zip command on Linux or 7-Zip on Windows.

Output8.png

 

22) Import the Zip file you created into the BPPM 9.5 CMA Monitoring Repository.  Import as a single solution.

Output9.png

 

23) Create a silent install package in the BPPM 9.5 CMA Deployable Package Repository.  Provide a unique and meaningful name for the package following configuration best practices.  Do not include the agent or any other KMs in the package.

 

Output10.png

 

24) Download the silent install package that you created for the Knowledge Module from the BPPM 9.5 CMA Deployable Package Repository and move it to the test managed node.

25) Run the silent installer for the package

26) Start the PATROL Agent.

27) Verify that the Knowledge Module application class(es) appear(s) as monitor type(s) in the BPPM server operations UI

Output11.png

 

28) Validate that data is being collected as expected.

 

Output12.png

 

Enabling Policy Configuration

Enabling policies for the KM configuration requires entering XML data into the Input tab of the properties for the KM container.  The screen shot below shows an example of the Input tab.

Output13.png

 

Practice and leveraging examples will help you learn what data is needed.  Note the following points.

 

 

1) Much of the structure and content of the XML data is the same for various KMs.  This includes the host configuration sections and various labels.  This means you can easily copy existing Input XML data and edit it to create the XML data for your custom KM.

2) XML data that is unique to your KM is mainly titles and content in the attribute sets that define the specific configuration settings for your custom KM.

3) The XML Input data is saved into the KM XML file.  It is not saved in a separate file to be managed with the PCIG utility.

This illustrates an example of Input XML data.  Only the data highlighted in blue text was edited from a copy, and an additional attribute was added.

 

NOTE: Notice the ID values in red text.  These values correspond to PATROL agent configuration variables.  When the policy is applied, PATROL Agent configuration variables that contain the ID values are created under the /ConfigData/<KM name> branch.  An example of the /ConfigData/<KM name> data is shown after the XML example.

 

 

<KMConfigurationMetadata>

<KMLevelConfiguration dataModelMajorVersion="1" dataModelMinorVersion="1">

</KMLevelConfiguration>

<ConfigurationParameters>

<ConfigurationParameter>

<List description="List of remote hosts" id="HOSTS" indexedBy="host" isMandatory="true" label="Host Log Values Configuration">

<AttributeSet description="Enter Host Name for which the specified configuration applies" i18nIdForDescription="4" i18nIdForLabel="3"  id="HostConfiguration" label="Host Details">

<Attribute>

<String default="localhost" description="Enter the Host Name" i18nIdForDescription="6" i18nIdForLabel="5" id="host" isMandatory="true" label="Host Name">

</String>

</Attribute>

<Attribute>

<AttributeSet id="LogValues" label="Log Values Configuration Options">

<Attribute>

<String default="" description="Enter the log instance to monitoring." id="LVInstance" isMandatory="false" label="Log Instance">

</String>

</Attribute>

<Attribute>

<String default="" description="Enter the alarm search string value." id="LVSearchString" isMandatory="false" label="Search String">

</String>

</Attribute>

<Attribute>

<String default="" description="Enter the data delimiter." id="LVDelimiter" isMandatory="false" label="Delimeter">

</String>

</Attribute>                 

</AttributeSet>

</Attribute>

</AttributeSet>

</List>

</ConfigurationParameter>

</ConfigurationParameters>

</KMConfigurationMetadata>

 

 

The PATROL configuration variables below illustrate content corresponding to the Input XML data above.

 

 

PATROL_CONFIG

"/ConfigData/LOG_VALUES/HOSTS/localhost/host" = { REPLACE = "localhost" },

"/ConfigData/LOG_VALUES/HOSTS/localhost/LVDemiliter" = { REPLACE = "2" },

"/ConfigData/LOG_VALUES/HOSTS/localhost/LVInstance" = { REPLACE = "MyTestLogPN0" },

"/ConfigData/LOG_VALUES/HOSTS/localhost/LVSearchString" = { REPLACE = "sessions" }

 

 

The policy configuration screen below illustrates the result of the Input XML data after it is imported as part of the KM into the CMA repository.

Output14.png

After you have entered the XML data, save the KM and work through the same packaging and import process using PCIG that you followed to enable the KM for data collection.  Test the policy configuration before moving on to enabling Menu commands.

NOTE:  Most KMs will need to be edited where the pconfig PSL command is used to interact with the agent pconfig database so that it leverages the PATROL agent configuration variables under the /ConfigData/<KM name> branch.  It is generally easier to configure the agent to collect data into the BPPM server in non-policy mode first, then apply the policy and finally edit the KM based on the agent configuration variables applied by the policy.

 

 

Enabling Menu Commands in the BPPM UI

The following steps illustrate how to enable Menu Commands in the BPPM UI.

 

 

1) Open the properties for the Menu Command and go to the Command tab.

2) Copy the command text and save it in a backup text file.

3) Click on the General tab and select Generate Auto ID as shown below.  Do not select the Annotate choice if the menu command prompts for user input. (Annotate can be used to automate the command.)

Output15.png

 

Click Yes to continue.  The command text can be copied from the backup file and pasted into the Command tab if it is lost.

4) After clicking Yes notice the Command ID is generated as shown in the example below.

 

Output65.png

5) The menu command function is saved as a file in the PATROL Console Cache PSL directory as shown in the example below.

 

Output17.png

6) Include the Menu Command ID <name>.lib file in the PSL source directory for PCIG.

7) Work through the same packaging and import process using PCIG that you followed to enable the KM for data collection and Policy configuration management.

8) Verify the Menu Command was created in the BPPM UI

Output18.png

General Recommendations

Do not use the Microsoft Windows compressed folders capability to compress the package.  Use a compression utility like 7-Zip.

 

Do not attempt to combine multiple KM solutions into one package.  Create separate packages for each.


Monitoring in BPPM will not function for Knowledge Modules which are not XML compliant and that are loaded on a 9.5 agent.

 

PSL code should be stored in PSL files using the "Save to file" option in the developer console while developing Knowledge Module.
This should be done instead of storing the code in the Knowledge Module files.  This will reduce the size of the XML file.

 

Keep in mind the XML file for the Knowledge Module is generated by the PATROL console and saved into the PATROL Console cache.

 

Start with a working Knowledge Module in PATROL.

 

Do not try to mix Knowledge Module development for monitoring and development/editing for BPPM 9.5 compatibility.  Work in a logical order.

 

Observe and follow general Knowledge Module development best practices.

 

Observe and follow general software development best practices.

 

Keep your code organized and follow the recommended process.  Do not jump ahead.  Do not skip steps.


Establish, document, and follow a version-revision numbering methodology.


Do not work though the enablement process in production.  Complete Knowledge Module enablement for BPPM 9.5 in a development and test environment before you import the final Knowledge Module solution package into production.

 

Do not use product names that match or conflict with other product names including BMC product names.


Do not use Knowledge Module names that match or conflict with other Knowledge Module names including BMC provided names.


Do not use package or solution names that match or conflict with other package or solution names including BMC provided names.


Maintain release and revision numbers properly.  This is especially important if you plan to have multiple release and/or revision numbers in use over time.

 

Use different names for the solution package created by the PCIG utility and the silent install package you create in the BPPM 9.5 CMA Deployable Package Repository.  This will help you keep track of the two files separately and not get them mixed up.  For example:

  1.   Name the file created by the PCIG utility based on the product name (Ex. plv.zip – “plv” is short for the custom KM solution named “Patrol Log Values”).
  2.   Name the deploy-able package according to the Knowledge Module name (Ex. LogValues.zip).

Be careful with text editors.  Do not use Microsoft WordPad or Microsoft Word for editing and saving files.  Use vi on Linux and UNIX.
Use Notepad or a programmer’s text editing utility like Notepad++ on Windows.  This will prevent the introduction of special characters that will cause issues.

 

Do not manually edit files except where recommended and required.


Start with a simple KM and learn the process before moving on to a more complicated KM.

 

It is a best practice to implement a container for each custom KM application class, especially if you expect multiple instances to be monitored.  This will improve UI navigation in BPPM so that all like instances are grouped into a container.

 

Make a backup of all KM related files before you begin editing.


Work in stages and take backups of each stage before moving on to the next stage.  For example get data collection working first, then move on to policy enablement, and finally enable menu commands.

 

Do not install or use other tools in the development environment that may interfere with the development process.  Examples include older PATROL Console versions, older BPPM infrastructure components that may be integrated with the test agent(s), PATROL Central, etc.

 

This entire Best Practices Document is available for download from our Knowledge Base under knowledge article KA400714

For more details about building and packaging custom see our online help: Building and packaging custom KMs.

For information about building a KM, see Building a PATROL Knowledge Module Developers Guide

Computer.png

 

 

Newly Published Knowledge Articles - New Content has been added over the last month!

This is our opportunity to share with you some of the most recently created knowledge articles in case they may help you with something you would like to know more about.

 

KA424135 - Cell loop and running 100% CPU while processing MC_SM_IMPACTS_REPORT event and deleting MC_SM_IMPACTS data instances.

KA424020 - BMC PATROL for Web URL Monitoring KM, after configuring an URL for monitoring, getting error 'handshake failure'.

KA424017 -  Is BPPM affected by the OpenSSL vulnerabilities CVE-2015-0204 and CVE-2015-0291?

KA422603 - Where is the send_trap utility in Windows?

KA423763 - What can we use instead of Tunnel proxy and TCP proxy in BPPM version 9.5 and higher?

KA422471 - Promotion from Impact Model Designer (IMD) is failing with the errors 'Publication for job ID null has failed'. and 'Promotion of Sandbox Changes has Failed. - Failed while doing promotion.' 

KA422559 - Tips for Email2Event problems

 

Popular Knowledge Articles

This list represents our most widely used knowledge articles, take a look to see if they may help you too!

 

KA403892 - Troubleshooting Guidelines for BPPM with Oracle Database

KA356644 - ProactiveNet Agent error - "java.lang.OutOfMemoryError: Java heap space"

KA287306 - How to Delete ProactiveNet Auto Sync Monitor Instances and devices from the system with respect to BMC Patrol Adapters?

KA316131 - What are the different ways of enabling cell trace?

KA352032 - Diagnosing problems with ProactiveNet PATROL Adapter without Service Integration

 

Looking for a previous blog posting? Find it here: BMC TrueSight Support BlogsBMC TrueSight Pulse Blogs

 

Feedback1.jpg

 

Feedback Request:

Help us determine how we are doing. Use the rating system at the bottom of this blog to rate this post! Feel free to comment as well. We want to hear from you!