Develop Instrumentation

The ConfigExchange command-line interface is located in:

<OMi_HOME>/opr/bin

For details on ConfigExchange, see ConfigExchange Command-Line Interface.

The instrumentation development utility is designed to help you to develop instrumentation. It is used to:

• Create instrumentation directory structures

• Upload and download instrumentation directory structures

• Upload and download instrumentation directory structures as a patch

• Upload and download instrumentation directory structures as a hotfix

After completing instrumentation development, the instrumentation components must be included in a content pack for distribution to the OMi servers.

Instrumentation packages (including patch and hotfixes) must be deployed to managed nodes.

When deploying instrumentation to agent nodes, you must consider the following:

• Deployment order:

  • Base package

  • Highest patch

  • Hotfixes for the highest patch or of base package in alphabetical order

• If one of the following modifications is made:

  • New patch or hotfix is uploaded to the database

  • Base package is modified

  • Patches or hotfix is modified

  The next deployment of instrumentation to a system where the base package is already deployed, automatically deploys the new instrumentation to the agent node.

The merge of base package, patches, and hotfixes is performed on the Gateway Server, eliminating superfluous network traffic when deploying to agent nodes.

The following instrumentation artifacts exist:

• Instrumentation package (also referred as base package)

  Instrumentation package names should only include alphanumeric characters and the underscore character (_) (similar to category names in OM).

• Instrumentation package patch

  Patch names should only include alphanumeric characters, the underscore character ( _ ), and include the following suffix: __PATCH__<num>.

• Instrumentation package hotfix

  Hotfix names should only include alphanumeric characters, the underscore character ( _ ), and include the following suffix: __PATCH__<num>__HOTFIX__<name>.

The following outlines the strategy you should follow for creating instrumentation patches and hotfixes:

• Base Package Definition. The base package definition is a zipped directory structure for a category.

  Removal of the base package also removes any hotfixes and patches.

  Re-upload of a base package can be achieved using the -force option.

• Instrumentation Patch Definition. Patch naming convention:

  <base_pkg_name>__PATCH__<num>

  Instrumentation patch definitions are deployed to the associated base package and will overwrite files of the base package. The directory structure must be the same as the base package. The file set is usually a subset of the base package files.

  Multiple patches can exist for a base package and they are ordered by version number.

  Version number syntax: <major>.<minor> where <major> or <minor> is an integer ≥ 1.

  Rollback of a patch removes the patch and any associated hotfixes from the database. Other patches associated with the same base package remain unchanged.

  Re-upload of a patch can be achieved using the -force option.

• Hotfix Definition. Hotfix naming convention:

  <categoryname>[__PATCH__<num>]__HOTFIX__<hotfixname>

  Hotfix definitions are deployed in alphabetical order to the associated base package and will overwrite files with identical names of the base package and any preceding patches. The directory structure must be the same as the base package. The file set is usually a subset of the base package files.

  Multiple Hotfixes can exist for a base package or a patch and they are ordered by version number.

  Version number syntax: <major>.<minor> where <major> or <minor> is an integer ≥ 1.

  Rollback of a hotfix removes the hotfix only from the database.

  Note No check is made to ascertain whether two hotfixes have conflicting files, but deployment order is defined (alphabetical).

  Re-upload of a hotfix can be achieved using the -force option.

• Deployment Strategy for Patches and Hotfixes. Patches with higher version numbers supersede patches with lower version numbers.

  An agent node always gets the base package merged with the latest available patch, and with any available hotfixes of the latest patch. If no patch is present, any available hotfixes for the base package are merged.

  Note

  • If a patch or hotfix exists, it is deployed with the base package.
  • If a hotfix exists, the related base package or patch cannot be deployed independently.
  • A patch which does not have the highest version number cannot be deployed.

  For example, the following two patches are available for the mySPI: mySpi__PATCH__1 and mySpi__PATCH__2. It is not possible to deploy mySpi__PATCH__1. mySpi__PATCH__2 will always be selected.

• Branching of Instrumentation Packages. If you need several variants of an instrumentation package which shall branch off from the same base package then this must be solved by instrumentation package naming. Just duplicate the base package to a new name.

1. Instrumentation patches and hotfixes are artifacts, and can be handled in the same way as instrumentation base packages. They are individually identifiable and can be specified for export and import using the Content Manager.

   Note Ignore a patch or hotfix package at upload time if no base package is available in the database, and ignore a hotfix for a patch if the patch not yet in the database.

2. When selecting and exporting a base package using the Content Manager UI, its patches and hotfixes are automatically selected and exported. If a patch is selected, all associated hotfixes are downloaded.

1. Create the directory structure for the mySPI instrumentation package:

   ConfigExchange -createinstrumdir -output mySPI

2. Copy any mySPI files to the newly created directory structure.

3. Import to database for testing:

   ConfigExchange -upload -input mySPI -instrumname mySPI

4. Continue development and fix bugs. Export package to the database:

   ConfigExchange -upload -input mySPI -instrumname mySPI -force

5. Create a content pack and add the instrumentation package mySPI to the other mySPI artifacts in the Content Pack. Export the content pack.

6. Publish the mySPI content pack for production use.

The following workflow outlines how to develop a new patch or hotfix for the mySPI instrumentation package:

1. Download the mySPI instrumentation package to the file system for editing:

   ConfigExchange -download -output . -instrumname mySPI

2. Edit, enhance, and add the files you need for the patch or hotfix.

3. Upload new content as a patch or hotfix:

   ConfigExchange -upload -input mySPI -instrumname mySPI -patch 1

   or when hotfixing the base package:

   ConfigExchange -upload -input mySPI -instrumname mySPI -hotfix hf1 forpatch 0

   or if you want a hotfix for patch 1:

   ConfigExchange -upload -input mySPI -instrumname mySPI -hotfix hf1 forpatch 1

   Note alternatively create a new directory structure and only add the files you need for patch or hotfix.

4. Test new content and rework if required. Upload with the -force option to replace the previous updates in the database:

   ConfigExchange -upload -input mySPI -instrumname mySPI -patch 1 -force

   or

   ConfigExchange -upload -input mySPI -instrumname mySPI -hotfix hf1 -forpatch 0 -force

5. Create a content pack. You can consider whether the mySPI base package should also be included in the content pack.

6. Publish mySPI patch or hotfix content pack for production use.

• ConfigExchange -upload -input <upload_dir> -instrumname <categoryname>

  Uploads <upload_dir> to database under the name <categoryname>. Fails if package <categoryname> already exists in the database.

• ConfigExchange -upload -input <upload_dir> -instrumname <categoryname> -force

  Uploads <upload_dir> to database under the names <categoryname>. Overwrites the package <categoryname> if it already exists in the database.

• ConfigExchange -upload -input <upload_dir> -instrumname <categoryname> -patch 3 -label <label>

  Uploads <upload_dir> and stores it as patch 3 for package <categoryname> in the database. Also applies label <label> to Patch 3.

• ConfigExchange -upload -input <upload_dir> -instrumname <categoryname> -hotfix <hotfix_name> -forpatch 0 -description <descr>

  Uploads <upload_dir> and stores it as hotfix <hotfixname> for base package <categoryname> in the database. Also applies description <descr> to the hotfix <hotfixname>.

• ConfigExchange -upload -input mySPI -instrumname mySPI -hotfix hf_CPUfix -forpatch 3 -force -description "mySPI hotfix for patch 3; fix CPU issue"

  Uploads from directory ./mySPI and stores the data as hotfix hf_CPUfix for mySPI's patch 3 to the database, using the description mySPI__PATCH__3__HOTFIX__hf_CPUfix.

  -force ensures that the package is re-uploaded if the hotfix package is already in the database.

• ConfigExchange -download -output <download_dir> -instrumname <categoryname>

  Download instrumentation package with name <categoryname> from the database and unzips it to the directory <download_dir>.

  Note Patch and hotfixes are not downloaded.

• ConfigExchange -download -output <download_dir> -instrumname <categoryname> -patch 1

  Downloads patch 1 for instrumentation package <categoryname> from the database and unzips to the directory <download_dir>.

  Note Base package and hotfixes are not downloaded.

• ConfigExchange -download -output <download_dir> -instrumname <categoryname> -hotfix <hotfix_name> -forpatch 1

  Downloads hotfix <hotfix_name> of patch 1 for instrumentation package <categoryname> from the database and unzips it to the directory <download_dir>.

  Note Base package and patch 1 are not downloaded.

• ConfigExchange -merge -instrumname <categoryname> -output <download_dir>

  Downloads instrumentation package <categoryname>, associated patches, and hotfixes from the database and unzips them to the directory <download_dir> in the following order (as they would be deployed to the agent node):

  • Base package

  • Highest patch

  • Hotfixes for the highest patch in alphabetical order

• ConfigExchange -remove -instrumname <categoryname> -hotfix hf1 -forpatch 0

  Rolls back hotfix hf1 of the base instrumentation package <categoryname>.

• ConfigExchange -remove -instrumname <categoryname> -patch 1

  Rolls back patch 1 and its hotfixes.

  Note Patches with higher version numbers than patch 1 are not downloaded.

• ConfigExchange -createinstrumdir -output <categoryname>

  Generates an empty directory structure under <categoryname> which can be used to contain instrumentation files.

• ConfigExchange -list -instrumname <categoryname>

  Lists all patches and hotfixes for instrumentation package <categoryname>.