CLM Server Monitoring - Installation and Enablement (DEPRECATED: CLM Server Monitoring is no longer supported and was dropped in version 6.0.3.)

Authors: JorgeAlbertoDiaz
Build basis: Collaborative Lifecycle Management 4.0.4

NOT CURRENT INFORMATION. NOT SUPPORTED CONFIGURATION. CLM pre-4.0.6 did not officially support CLM Server Monitoring (CSM) plugin nor Agent. See [https://jazz.net/wiki/bin/view/Deployment/DeploymentMonitoring].

This page provides information on how to install, enable and disable the CLM Server Monitoring feature. The page covers:

• Installation instructions: for CLM versions pre-4.0.4 it provides you with details on how to install a server side extension with CLM Server Monitoring. The server side extension deliverable is provided as this attachment. An Ant build file is provided to automate the main instllation tasks. Currently the minimum CLM version must be 4.0.1.

• Feature enable/disable instructions: how to change the enablement state of the feature. These instructions will apply to both: a CLM 4.0.4 version (for which CLM Server Monitoring is already included and disabled); or for a pre-4.0.4 version to which the feature has been already installed following the instructions in this page.

Make sure that you the user ID you use for performing the described operations has full read/write permissions to the folders and application files involved.

CLM Server Monitoring Feature Installation (CLM pre-4.0.4 versions)

For CLM pre-4.0.4 versions the CLM Server Monitoring feature is provided as a server side extension for the CLM applications. In addition to this extension deployment, required libraries addition and configuration changes have to be performed to the application to which the monitoring feature is being enabled. The main steps for enabling CLM Server Monitoring for a CLM application are the following:

1. Deploy the server side extension
2. Modify the application: add required libraries and configuration settings
3. Enable JMX in the server: to be able to connect with a JMX client agent

The complete process will require additional steps. Please review the steps documentation and the supporting scripts provided before beginning the process:

1. (Optional) Prepare the application for reload: by calling https:///<server>:/<port>/<app>/admin/cmd/requestReset with a user with JazzAdmin priviledges. Note this step will not be needed if you will re-package and re-reploy the application as advised.
2. Stop the application server. If using WebSphere Application Server you could just stop the application itself.
3. Deploy the server side extension
4. Modify the application: add required libraries and configuration settings. It is advised to re-package the application 'war' file with the changes instead of just making changes to the deployed one at application server runtime location (further details in subsections). If you are re-deploying the application 'war' file modified as advised, step 1 is not needed.
5. Enable JMX in the server: to be able to connect with a client
6. Re-deploy the application: if the 'war' application file has been re-packaged
7. Restart the server/application

Steps 3-4 can be performed in any order. The following subtopics describe the main installation steps; however for simplicity it is recommended that, once reviewed the information; the supporting Ant build file is used as described in Installation using Ant build file, which will automate the majority of steps.

---

Installation steps overview

The subtopics in this section provide further information on the CLM Server Monitoring installation steps. Take into account the provided deliverable structure as described in Server side extension (pre-4.0.4 only). Note that the installation steps are to be performed with the server shutdown (or at least the application if using WebSphere Application Server).
Currently the minimum CLM version must be 4.0.1.

Deploy the server extension

The feature is provided as a server side extension update site. The update site has to be deployed to the application and its provision profile configured as any other extension. For further dertails on server extensios deployment you can check Rational Team Concert 4.0 Extensions Workshop. A deployment to a CLM application at the location <clmInstallPath>/server/conf/<app>/sites/server-monitoring-update-site will look like:

./site.xml
./features:
   |
   |--com.ibm.team.server.monitoring.feature_1.0.400.<build>.jar
./plugins:
   |
   |-com.ibm.team.server.monitoring_1.0.400.<build>.jar

While the contents of "server-monitoring-profile.ini" file located in <clmInstallPath>/server/conf/<app>/provision-profiles/ will look like:

url=file:<app>/sites/server-monitoring-update-site
featureid=com.ibm.team.server.monitoring.feature

---

Modify the application: required libraries and configuration

The monitoring feature relies on AspectJ libraries that have to be provided to every CLM application to which monitoring is being enabled. Then the applications have to be configured so the libraries are loaded at runtime and the AspectJ code weaving support is enabled. Following is a description on how to contribute these libraries and configuration changes to a CLM application. While these changes can be performed to the deployed application binaries; the advised approach is to re-package the binary application 'war' file located in <clmInstallPath>/server/tomcat/webapps with these changes and re-deploy it.

Addition of required libraries to the application: the AspectJ required libraries have to be deployed to the application's WEB-INF/eclipse/plugins folder. The required libraries are:

• org.aspectj.runtime_1.7.2.20130214224500.jar
• org.aspectj.weaver_1.7.2.20130214224500.jar
• org.eclipse.equinox.weaving.aspectj_1.0.0.v20100108.jar
• org.eclipse.equinox.weaving.caching_1.0.0.v20100108.jar
• org.eclipse.equinox.weaving.caching.j9_1.0.0.v20100108.jar
• org.eclipse.equinox.weaving.hook_1.0.0.v20100108.jar

These libraries are located in the "aspectj-dist" folder of the provided Server side extension (pre-4.0.4 only) packaging.
If you are copying the libraries to the deployed application location, note that the runtime folder will vary from Tomcat to WebSphere Application Server:

• Tomcat: <clmInstallPath>/server/tomcat/webapps/<app>
• WebSphere Application Server (typical location, custom deployment path can be specified by WAS admins): <WASInstallPath>/profiles/<profile>/installedApps/<node>/<app>_war.ear/<app>.war/

To simplify this step and avoid accidental removal of the customization; it is advised to repackage the application binary war file with these changes; the "war" file is located in <clmInstallPath>/server/webapps; and redeploy the modified application "war" after all changes. The Ant build file provided will repackage the war with the libraries for you.

Modify application configuration: the eclipse configuration file for each application is located at WEB-INF/eclipse/configuration/config.ini. This file has to be modified so: (1) the contributed libraries are loaded at runtime and; (2) the AspectJ code weaving support is enabled at application start. As with the libraries contribution, it is rather advised to re-package the application binary 'war' file located in <clmInstallPath>/server/tomcat/webapps with these configuration changes, and re-deploy it. The Ant build file provided will re-package the war with the configuration changes for you. The following is a sample configuration file with the modified lines already added (in bold):

osgi.bundles=\
 org.eclipse.equinox.weaving.aspectj@2\:start, \
 org.eclipse.equinox.weaving.caching@start, \
 org.eclipse.equinox.weaving.caching.j9@start, \
 org.aspectj.runtime@start, \
 org.aspectj.weaver@start, \ 
 org.eclipse.osgi.services@start,\
 org.eclipse.equinox.app@start,\
 org.eclipse.equinox.common@start,\
 org.eclipse.equinox.http.registry@start, \
 org.eclipse.equinox.http.servlet@start,\
 org.eclipse.equinox.http.servletbridge@start,\
 org.eclipse.equinox.preferences@start,\
 org.eclipse.equinox.registry@start,\
 org.eclipse.equinox.servletbridge.extensionbundle,\
 org.eclipse.core.contenttype@start,\
 org.eclipse.core.jobs@start,\
 org.eclipse.core.runtime@start,\
 org.apache.commons.logging@start,\
 org.apache.commons.logging.log4j,\
 org.apache.commons.io, \
 org.apache.commons.fileupload, \
 org.apache.log4j@start,\
 javax.servlet.jsp@start,\
 com.ibm.team.json@start,\
 com.ibm.websphere.objectgrid.external,\
 org.opengroup.arm40-fragment, \
 com.ibm.team.repository.provision@start, \
 com.ibm.team.jfs.app.install@start,\
 com.ibm.team.json.nl1, \
 com.ibm.team.json.nl2, \
 com.ibm.team.repository.provision.nl1, \
 com.ibm.team.repository.provision.nl2
osgi.bundles.defaultStartLevel=4
osgi.framework.extensions=org.eclipse.equinox.weaving.hook
osgi.classloader.lock=classname

---

Enable JMX

This step, while not mandatory for the monitoring feature to work, it is needed so you can connect to the application's server JMX interface and leverage the infomation generated by CLM Server Monitoring feature using JMX. See Jazz monitoring through JMX for configuration options.

The provided Ant build file can add simple JMX parameters to the server.startup script.

---

Re-deploy the application

After re-packaging the application 'war' file with the libraries and configuration changes, you have to re-deploy it to the server. Depending on the application server used in your CLM deployment, different operations have to be performed:

• Tomcat: clean/remove the folders:
  • <clmInstallPath>/server/tomcat/webapps/<app>
  • <clmInstallPath>/server/tomcat/work
• WebSphere Application Server: follow specific instructions like Updating enterprise applications with the console; making sure you update the whole application. Note that updating an application requires WebSphere Application Server to be first started. it is important that the deployment temporary folders used by WebSphere Application Server are properly cleaned up and updated with the new contents; sometimes a uninstall/reinstall of the application is more reliable.

The provided Ant build file will automatically clean the Tomcat folders.

---

Installation using Ant build file

This topic describes the basic usage of the provided Ant build file for installing the CLM Server Monitoring feature. The usage description aims to automate the steps of:

1. Deploy the server side extension
2. Re-package the application: add required libraries and configuration settings
3. Clean Tomcat deployment folders (for Tomcat based installations)
4. (Optionally) add basic JMX statements to server.startup script

Following usage details are provided:

Ant properties: a set of properties are required for the Ant script to run

Property	Description	Example
temp.dir	MANDATORY. Temporary folder for the installation. Preferred non-existent one. It will be deleted after the execution	-Dtemp.dir=/tmp/monitoring
server.dir	MANDATORY. CLM installation server directory	-Dserver.dir=/opt/IBM/JazzTeamServer/server
app	MANDATORY. CLM application to enable monitoring to	-Dapp=jts
update.site.zip	MANDATORY. Location of the provided extension packaged zip file	-Dupdate.site.zip=server-monitoring-update-site.zip
modify.startup	OPTIONAL. Whether to add basic JMX propeties to the server.startup script. Default is false	-Dmodify.startup=true

Main target description: the default target for the build file is the 'help' one; therefore, the script will just print help information. The recommended target for installing the feature is called 'deploy.all'. Calling that target with the required properties will perform the following operations:

1. Verify the properties has been set
2. Unzip the package to the temporary location
3. Perform variable substitution on the sample profile.ini file provided
4. Make a backup of the 'war' file of the application to be processed in <clmInstallPath>/server/tomcat/monitoring_backup
5. Add the required libraries to the application 'war' file located in <clmInstallPath>/server/tomcat/webapps
6. Add the configuration changes to the application 'war' file located in <clmInstallPath>/server/tomcat/webapps
7. Clean Tomcat runtime deployment folders if they are found
8. (Optonally) add basic JMX to server.startup script
9. Clean the temporary folder

Sample execution: the following is a sample installation of the feature for the 'jts' applciation deployed on a Tomcat server:

1. Copy the provided package to a known location. We will refer to it as <BaseDir>
2. Stop the server by running <clmInstallPath>/server/server.shutdown
3. From <BaseDir>, run ant -Dtemp.dir=/tmp/monitoring -Dserver.dir=/opt/IBM/JazzTeamServer/server -Dapp=jts -Dupdate.site.zip=server-monitoring-update-site.zip -Dmodify.startup=true deploy.all

As a result of the execution:

1. The 'war' file is repackaged and the server will re-deploy it with the libraries and configuration added on next start
2. The server side extension is deployed to /opt/IBM/JazzTeamServer/server/conf/jts/sites
3. Basic JMX properties have been added to the server.startup script. This properties are added commented, so you have to uncomment them before starting the server.
4. A backup of the 'war' file is copied in /opt/IBM/JazzTeamServer/server/tomcat/monitoring_backup

Note that for installing the feature for more applications in the same server, you will have to re-run the build file specifying a different application each time.

The successful execution generated log will look like the following:

Buildfile: build.xml

check.main.deployment.props:

deploy.all:
    [mkdir] Created dir: /tmp/monitoring

check.main.deployment.props:

unzip-update-site:
    [unzip] Expanding: server-monitoring-update-site.zip into /opt/IBM/JazzTeamServer/server/conf/jts
    [mkdir] Created dir: /opt/IBM/JazzTeamServer/server/tomcat/monitoring_backup
     [copy] Copying 1 file to /opt/IBM/JazzTeamServer/server/tomcat/monitoring_backup
      [war] Updating war: /opt/IBM/JazzTeamServer/server/tomcat/webapps/jts.war
   [delete] Deleting directory /opt/IBM/JazzTeamServer/server/conf/jts/sites/server-monitoring-update-site/aspectj-dist

check.main.deployment.props:

process.config.ini:

extract.config.ini:
    [unzip] Expanding: /opt/IBM/JazzTeamServer/server/tomcat/webapps/jts.war into /tmp/monitoring/config-working

modify.config.ini:
      [war] Updating war: /opt/IBM/JazzTeamServer/server/tomcat/webapps/jts.war

process.server.startup:

process.server.startup.win:

process.server.startup.nix:

clean.temp:
   [delete] Deleting directory /tmp/ss

clean.tomcat.foders:

delete.tomcat.workdir:
   [delete] Deleting directory /opt/IBM/JazzTeamServer/server/tomcat/work

delete.app.deploydir:
   [delete] Deleting directory /opt/IBM/JazzTeamServer/server/tomcat/webapps/jts

BUILD SUCCESSFUL

If using WebSphere Application Server, after the succesful script execution, you would perform the application re-deploy steps. For Tomcat, you can go ahead and run the server.startup script.

CLM Server Monitoring Feature Enable/Disable

This topic provides information on how to enable/disable the CLM Server Monitoring feature. The instructions in this topic applies to you if either:

1. You have installed the feature by the instructions in CLM Server Monitoring Feature Installation in a pre-4.0.4 version CLM application: the just installed feature is by default enabled. You can follow instructions in this topic to disable it.
2. You have a CLM 4.0.4 version installation: the feature is by default disabled. You can follow instructions in this topic to enable it.

Enabling/disabling the CLM Server Monitoring feature is achieved by (un)commenting the following line from each application's WEB-INF/eclipse/configuration/config.ini file:

osgi.framework.extensions=org.eclipse.equinox.weaving.hook

Commenting the line will disable the feature at next restart; consequently the line uncommented will enable it.

You can take the following approaches for modifying the feature enablement:

1. Modify the deployed configuration file: this approach consists on directly modifying the file from your application server deployment location. Once the application is restarted the feature state will change. Note that to avoid potential issues or accidental removal, it is advised that you rather re-package the application 'war' file located in <clmInstallPath>/server/tomcat/webapps with the configuration change, and re-deploy it. Supporting Ant tasks are provided for automating the re-packaging as described in Enable/Disable monitoring using Ant build file. Different application servers deploy the CLM applications in different paths:
   1. Tomcat: <clmInstallPath>/server/tomcat/webapps/<app>
   2. WebSphere Application Server (typical location, custom deployment path can be specified by WAS admins): <WASInstallPath>/profiles/<profile>/installedApps/<node>/<app>_war.ear/<app>.war/
2. Modify the applicaiton 'war' packaged file and redeploy it: this is the preferred approach. Modify the configuration file within the 'war' file itself and re-reploy it.
3. Use the provided Ant build file: instructions can be found at Enable/Disable monitoring using Ant build file. The Ant build file provide tasks for re-packaging the 'war' file for you.

Note that once the application 'war' file has been modified, it can be re-deployed following the same instructions as in Redeploy the application.

Enable/Disable monitoring using Ant build file

This section describes the basic usage of the provided Ant build file to enable/disable the CLM Server Monitoring feature. The described usage automates the re-packaging of CLM application 'war' file with the configuration modified to change the feature enablement state.

Following usage details are provided:

Ant properties: a set of properties are required for the Ant script to run

Property	Description	Example
temp.dir	MANDATORY. Temporary folder. Preferred non-existent one. It will be deleted after the execution	-Dtemp.dir=/tmp/monitoring
server.dir	MANDATORY. CLM installation server directory	-Dserver.dir=/opt/IBM/JazzTeamServer/server
app	MANDATORY. CLM application to enable/disable monitoring to	-Dapp=jts

Main target description: the default target for the build file is the 'help' one. For modifying the CLM Server Monitoring state two targets are provided

• Enablement: enable.monitoring
• Disablement: disable.monitoring

The targets perform the following steps:

1. Verify the properties has been set
2. Extract the config.ini file to a temporary location
3. Modify the config.ini file
4. Update the the 'war' file of the application to be processed in <clmInstallPath>/server/tomcat/webapps
5. Clean Tomcat runtime deployment folders if they are found
6. Clean the temporary folder

Sample execution: running ant -Dtemp.dir=/tmp/monitoring -Dserver.dir=/opt/IBM/JazzTeamServer/server -Dapp=jts enable.monitoring will modify jts.war enabling the feature. Note that for enabling the feature for more applications in the same server, you will have to re-run the build file specifying a different application each time.

The successful execution generated log will look like the following:

Buildfile: build.xml

check.main.deployment.props:

disable.monitoring:

extract.config.ini:
    [unzip] Expanding: /opt/IBM/JazzTeamServer/server/tomcat/webapps/jts.war into /tmp/monitoring/config-working
      [war] Updating war: /opt/IBM/JazzTeamServer/server/tomcat/webapps/jts.war

clean.tomcat.foders:

delete.tomcat.workdir:
   [delete] Deleting directory /datos/devel/smarterServer/clm404/server/tomcat/work

delete.app.deploydir:
   [delete] Deleting directory /datos/devel/smarterServer/clm404/server/tomcat/webapps/jts

clean.temp:
   [delete] Deleting directory /tmp/ss

BUILD SUCCESSFUL

CLM Server Monitoring assets

This section provides information on the provided assets. This information will allow you to further understand the installation steps described earlier.

Server side extension (pre-4.0.4 only)

Currently the minimum CLM version must be 4.0.1.

The packaged file provided at server side feature package, contains the following folders and assets:

• provision_profiles: containing a provision file to be copied to the application's "provision_profiles" folder. The file contained is general for any application, and it has to be customized for the one being installed. The provided Ant build file automates the copy and customization of the file.

• sites/server-monitoring-update-site: containing two types of assets
  • aspectj-dist: folder containing the required AspectJ libraries.
  • The rest of assets form the server side feature update site contents.

Ant build file

The provided Ant build file contains tasks that helps you automate the main steps described in this page. It has be written so just base Ant tasks are used, to minimize the usage dependencies.
The most important properties and their meaning are:

Property	Description
temp.dir	Temporary folder used for the different tasks
server.dir	CLM installation server directory
app	CLM application
update.site.zip	Location of the provided extension packaged zip file
modify.startup	Whether to add basic JMX propeties to the server.startup script. Default is false

The build file itself contains several targets for the supported operations, however you will typically just need to use a few of them:

Target	Description
help	DEFAULT. Prints general help information
deploy.all	Perform full deployment/installation steps operations. 'temp.dir', 'server.dir', 'app' and 'update.site.zip' properties are required. 'modify.startup' can be optionally specified
enable.monitoring	Re-packages the application uncommenting the configuration property line for enabling monitoring
disable.monitoring	Re-packages the application commenting the configuration property line for disabling monitoring

Related topics: None

External links:

• None

Additional contributors: None