CreateCustomScenarios < Deployment

r27 - 2019-04-15 - 19:01:29 - TimFeeneyYou are here: TWiki >
Deployment Web > DeploymentMonitoring > CreateCustomScenarios
<div id="header-title" style="padding: 10px 15px; border-width:1px; border-style:solid; border-color:#FFD28C; background-image: url(<nop>https://jazz.net/wiki/pub/Deployment/WebPreferences/TLASE.jpg); background-size: cover; font-size:120%">
---+!! Register Custom Scripts As a Resource-intensive Scenario  
%DKGRAY% Authors: Main.ShubjitNaik, Main.DineshKumar, [[Main.RalphSchoon][Ralph Schoon]]  <br>
Build basis: CLM 6.0.5 or Higher
%ENDCOLOR%</div></sticky>

<!-- Page contents top of page on right hand side in box -->
<sticky><div style="float:right; border-width:1px; border-style:solid; border-color:#DFDFDF; background-color:#F6F6F6; margin:0 0 15px 15px; padding: 0 15px 0 15px;">
%TOC{title="Page contents"}%
</div></sticky>

<sticky><div style="margin:15px;"></sticky>

There are specific user and system scenarios across the CLM portfolio that can potentially drive higher load on a Jazz application. Starting with CLM 6.0.3 IBM has identified a set of known resource-intensive scenarios in each application and are exposing them as JMX MBeans. Refer [[CLMExpensiveScenarios][Known Resource-intensive Scenarios]]

However there are cases where a custom functionality could be a potential resource-intensive scenario, for example a custom Java script or a plugin making REST APIs call to a CLM application.  Such custom functionality needs to be monitored as well when looking at the overall application performance.  This article focuses on a method to record and publish such custom functionality as resource-intensive scenario to help track their usage.
<br>
---++ About Starting and Stopping Custom Resource-Intensive Scenarios

The workflow is to first register a JMX MBean stating that a Resource Intensive Scenario is about to start before any Script/API first accesses the targeted application Server. At the end of the script , once the operation is complete, update the MBean stating the specific Resource Intensive Scenario has completed. This MBean has several attributes like Start, End, isActive, Username, Elapsed time and invocation Count. These MBean attributes can be monitored/tracked and relevant notifications/thresholds can be configured against them. <br>

Let us first look at the workflow of registering a Resource Intensive Scenario MBean using a REST client including monitoring via !RepoDebug. We will then present different examples using APIs and Scripts
<br>

---++ Workflow of Registering a Resource-Intensive Scenario using REST Client

To perform any of the activities below, you must be logged in to the application <verbatim>https://<servername>:<port>/<APP>/web</verbatim>

---+++ Starting a Scenario

To start a Scenario MBean make a POST request to the URL 
<verbatim>https://<servername>:<port>/<APP>/service/com.ibm.team.repository.service.serviceability.IScenarioRestService/scenarios/startscenario </verbatim>

Provide the following headers:<verbatim>
Content-Type=application/json
Accept=application/json
X-Jazz-CSRF-Prevent=JSESSIONID
</verbatim>
Where =JSESSIONID= is the value of the JSESSIONID cookie of the logged-in session. If this header is not provided the call will not succeed. You will instead see a permission denied error.
<br><br>
The POST body must contain the scenario name in the following JSON format.
<verbatim>{"scenarioName":"<your scenario name here>"}</verbatim>
Example:
<verbatim>{"scenarioName":"MyCustomExpensiveScenario"}</verbatim>

If the call succeeds, the response returns 200 as HTTP status. The response body contains the scenario registration information required to register the end of the scenario later. In the example the scenario name used was !MyCustomExpensiveScenario.

<verbatim>{
"scenarioName":"MyCustomExpensiveScenario",
"scenarioInstanceId":"_Jbe94DaQEempFf7xSdsBAQ",
"scenarioHeaderKey":"x-com-ibm-team-scenario",
"scenarioHeaderValue":"_Jbe94DaQEempFf7xSdsBAQ%3Bname%3DMyCustomExpensiveScenario"
}</verbatim>


---+++ Stopping the Scenario

To stop a Scenario MBean once the scenario has ended, make a POST request as below<verbatim>https://<servername>:<port>/<APP>/service/com.ibm.team.repository.service.serviceability.IScenarioRestService/scenarios/stopscenario</verbatim>

Provide the following headers:<verbatim>
Content-Type=application/json
Accept=application/json
X-Jazz-CSRF-Prevent=JSESSIONID
</verbatim>
Where =JSESSIONID= is the value of the JSESSIONID cookie of the logged-in session. If this header is not provided the call will not succeed. You will instead see a permission denied error.
<br><br>
The POST body must contain the scenario information from the start response in JSON format. Example:
<verbatim>
{"scenarioName":"MyCustomExpensiveScenario",
"scenarioInstanceId":"_Jbe94DaQEempFf7xSdsBAQ",
"scenarioHeaderKey":"x-com-ibm-team-scenario",
"scenarioHeaderValue":"_Jbe94DaQEempFf7xSdsBAQ%3Bname%3DMyCustomExpensiveScenario"}</verbatim>

If the call succeeds, the response returns 200 as HTTP status. The response body contains the scenario ID. Example:
<verbatim>"_Jbe94DaQEempFf7xSdsBAQ"</verbatim>


---+++ Monitoring or Viewing the Scenario MBean

You must first enable specific MBeans so as to be able to Monitor it. To enable the MBeans, Login to the application admin page as a Jazz Admin User via <verbatim>https://<servername>:<port>/<APP>/admin </verbatim>
Click on Application > Advanced Properties and enable the following MBeans value to "true"
   * Enable Scenario Details MBean		
   * Enable Scenario Metrics MBean <br>
<img src="%ATTACHURLPATH%/Enable_Mbean.png" alt="Enable_Mbean.png" width="644" height="361" />
<br><br>

Once the Custom Resource Intensive Scenario MBean (Example !MyCustomExpensiveScenario) has been started and with the MBeans enabled, you should be able to see the MBean via !RepoDebug under the domain *com.ibm.team.foundation.scenarios*
<verbatim>https://<servername>:<port>/<APP>/repodebug/mxBeans</verbatim>

<img src="%ATTACHURLPATH%/Repodebug_mbean.png" alt="Repodebug_mbean.png" width="644" height="361" />
<br><br>
Please see the article [[https://jazz.net/library/article/91590][CLM Monitoring]] in section *6. Resource-Intensive Scenarios Summary bean* for more information.
<br>

---+++ Viewing the Custom Scenario Statistics

Once the Resource Intensive Scenario MBean has been stopped the Counters will be updated. To view these Scenario Statistics open the following URL.

<verbatim>https://<servername>:<port>/<APP>/service/com.ibm.team.repository.service.internal.counters.ICounterContentService</verbatim>

The Scenarios counters can be found in the section <verbatim>scenarios</verbatim>

The Scenarios summary information can be found in the section <verbatim>scenariosSummary</verbatim>

Custom scenario counter and scenario summary.: <br />
     <img src="%ATTACHURLPATH%/ScenarioCounter.png" alt="ScenarioCounter.png" width="644" height="361" />

<br>
---++ Examples of Registering a Resource-Intensive Scenario

---+++ Using Curl Script

RESTClient allows using JSESSIONID from existing session, as a value to “X-Jazz-CSRF-Prevent” header.  For Curl, below command line can be used to create a valid session.  Below sample further, captures the session in a variable for use with other commands


Declare a USER, PWD and COOKIES variables to begin with: <br><code>
$ USER&#61;JazzUser<br>
$ PWD&#61;JazzUserPassword<br>
$ COOKIES&#61;cookies.txt<br></code>

Perform the authentication and capture the cookies<br>
<code>
$ curl -k -c $COOKIES https://&lt;servername&gt;:&lt;port&gt;/ccm/authenticated/identity<br>
$ curl -k -L -b $COOKIES -c $COOKIES -d j_username=$USER -d j_password=$PWD https://&lt;servername&gt;:&lt;port&gt;/ccm/authenticated/j_security_check
</code>

---++++ Start Scenario 
POST to startscenario url results in marking the beginning of a new instance of the scenario.

Curl provides two ways for passing the JSON content <br>
a.  Using a JSON file representing the scenario object

=$ echo {scenarioName: \"curlScenario01\"} > scenarioName.json=
<br>	
=$ curl -X POST -k  -b $COOKIES -H 'Content-Type: application/json' -H 'Accept: application/json' 'https://&lt;servername&gt;:&lt;port&gt;/ccm/service/com.ibm.team.repository.service.serviceability.IScenarioRestService/scenarios/startscenario' -d @scenarioName.json > scenarioResponse.json=

b.  Using a JSON Object data directly in command line<br>

=$ curl -X POST -k  -b $COOKIES -H 'Content-Type: application/json' -H 'Accept: application/json' 'https://&lt;servername&gt;:&lt;port&gt;/ccm/service/com.ibm.team.repository.service.serviceability.IScenarioRestService/scenarios/startscenario' --data "{\"scenarioName\": \"curlScenario01\"}" > scenarioResponse.json=

Every post creates a newer instance of the Scenario.  The RESPONSE from the POST has the details of the instance.  

Response from the POST above looks like this :  <br>

={"scenarioName":"curlScenario01","scenarioInstanceId":"_4fTGABQTEemlX9f2gd8Dpw","scenarioHeaderKey":"x-com-ibm-team-scenario","scenarioHeaderValue":"_4fTGABQTEemlX9f2gd8Dpw%3Bname%3DcurlScenario01"}=

scenarioHeaderValue in the above response shows which scenario this instance belongs to.

---++++ Run Scenario
Invoke the requests that are part of this scenario

Here is an example request that invokes a work item query : <br>
=$ curl -X GET -k -b $COOKIES https://&lt;servername&gt;:&lt;port&gt;/ccm/oslc/contexts/_kEYLgAUhEemlX9f2gd8Dpw/workitems -H 'Accept: application/rdf+xml'=

---++++ Stop Scenario <br>
=$ curl -X POST -k  -b $COOKIES -H 'Content-Type: application/json' -H 'Accept: application/json' -i 'https://&lt;servername&gt;:&lt;port&gt;/ccm/service_/com.ibm.team.repository.service.serviceability.IScenarioRestService/scenarios/stopscenario' -d @scenarioResponse.json=
<br>
Counters get updated after the scenario stops.
<br>
Updated *scenario and instance counts* can be seen in the “scenarios” section of the application admin counters page, here is the URL: 
	=https://&lt;servername&gt;:&lt;port&gt;/ccm/admin?internal#*action=com.ibm.team.repository.admin.viewCounters*=
<br>
---+++ Example Scripts 

   * [[%ATTACHURL%/Resource_Intensive_Scenario_Windows_cURL_Batch_Examples_V2.zip][Resource_Intensive_Scenario_Windows_cURL_Batch_Examples_V2.zip]]: Example cURL scripts to login and to register a custom scenario

---+++ Using Java OSLC

Open source Java code is available [[https://github.com/jazz-community/custom-expensive-scenario-notifier-oslc4j][in the Jazz Community project custom-expensive-scenario-notifier-oslc4j]].

The code can be deployed as application ESNOJ with executable JAR file esnoj.jar and comes with scripts to start and stop an expensive scenario. The scenario information is persisted in a file which allows to run any code required for the scenario. To deploy the code as executable JAR file follow the File =com.ibm.js.team.monitoring.custom.oslc4j.expensivescenario/ReadMe - HowToRelease.txt=. 

The source code can be used in other Java Based applications. This is the primary purpose of this source code.
---++++ Considerations

The code in this project is based on OSLC4J and independent of libraries shipped with the CLM products. The time it takes to execute one of the commands from a command line is short compared to the next solution based on the Plain Java Client libraries. This solution is best used in build scripts or other occasions, where the code is called from a command line. The overhead is relatively minor and the tool is easily packaged in a jar file. 

   * Consider using this, or the CURL based solution above in command line solutions. 
   * Consider using this code in Java applications that are based on OSLC4J and not based on RTC Plain Java Client Library code. 
   * This code works against the application CCM, RM, QM, other applications that are supported by OSLC4J can be added.
   * The code works against systems with Jazz Authentication Server enabled.
   * The code works against a clustered CCM server. 

---++++ Syntax 

The syntax is as follows

=-command expensiveScenario -url https://&lt;server&gt;:port/&lt;context&gt;/ -user &lt;userId&gt; -password &lt;password&gt; -scenarioName &lt;scenarioName&gt; -mode &lt;mode&gt;=

---++++ Start Scenario

To start a scenario use parameter

=-command expensiveScenario -url https://clm.example.com:9443/ccm/ -user ADMIN -password ****** -scenarioName MyCustomExpensiveScenario -mode start=

---++++ Stop Scenario

To stop a scenario use parameter

=-command expensiveScenario -url https://clm.example.com:9443/ccm/ -user ADMIN -password ****** -scenarioName MyCustomExpensiveScenario -mode stop=
<br><hr>

---++++ How the code works

Here are the details how to use the code in an application based on OSLC4J.

The code provides the Class =ExpensiveScenarioService= that implements the interface =IExpensiveScenarioService= which basically manage the scenario registration information as string. The start command returns the JSON information about the registered expensive scenario as string. This string needs to be passed to the stop command as parameter to stop the expensive scenario.  
The Class =FilePersitentExpensiveScenarioService= that implements the interface =IPersistedExpensiveScenarioService= handles the management of the scenario registration information and persists the information as a JSON file. The start command starts the scenario and stores the JSON information about the registered expensive scenario as file. This file is read by the stop command to stop the expensive scenario. 

The main functionality is implemented in the class

<verbatim>com.ibm.js.team.monitoring.custom.oslc4j.expensivescenario.service.ExpensiveScenarioService.ExpensiveScenarioService(String, String)</verbatim>

implementing the interface

<verbatim>com.ibm.js.team.monitoring.custom.oslc4j.expensivescenario.service.IExpensiveScenarioService</verbatim>

To register a resource intensive scenario instance, you need a client of type =org.eclipse.lyo.client.oslc.jazz.JazzFormAuthClient= that is logged into the server.
It is neccessary to pass the scenario instance information received when starting the scenario to stop the instance. This is done by passing the string scenarioInstance. The following code sequence performs the instantiation, starts and stops the scenario instance using the conext URI ="https://clm.example.com:9443/ccm/"= and the scenarioname ="MyScenario"=.

<verbatim>
IExpensiveScenarioService expensiveScenarioService = new ExpensiveScenarioService(client, "https://clm.example.com:9443/ccm/", "MyScenario");
String scenarioInstance = expensiveScenarioService.start();
expensiveScenarioService.stop(scenarioInstance);
</verbatim>

The code contains an implementation that persists the information in a local file. The implementation is in the class 
<verbatim>com.ibm.js.team.monitoring.custom.oslc4j.expensivescenario.service.FilePersitentExpensiveScenarioService.FilePersitentExpensiveScenarioService(IExpensiveScenarioService)
</verbatim>
implementing the interface

<verbatim>com.ibm.js.team.monitoring.custom.oslc4j.expensivescenario.service.IPersistedExpensiveScenarioService</verbatim>

The class uses the interface =com.ibm.js.team.monitoring.custom.oslc4j.expensivescenario.service.IExpensiveScenarioService=. To create an instance, pass an implementation, e.g. the one created above. The Interface provides =start()= and =stop()= methods. The methods also use the client of type =org.eclipse.lyo.client.oslc.jazz.JazzFormAuthClient= that is logged into the server. The class =FilePersitentExpensiveScenarioService= performs the scenario instance information handling by persisting it in a file.

<verbatim>
IPersistedExpensiveScenarioService filePersistedExpensiveScenario = new FilePersitentExpensiveScenarioService(expensiveScenarioService);
filePersistedExpensiveScenario.start();
filePersistedExpensiveScenario.stop();
</verbatim>

Also see the code in <verbatim>
com.ibm.js.team.monitoring.custom.oslc4j.expensivescenario.service.RegisterScenarioExample
</verbatim>

---+++ Using the Plain Java Client Libraries

Open source Java code is available [[https://github.com/jazz-community/custom-expensive-scenario-notifier-plainjava][in the Jazz Community project custom-expensive-scenario-notifier-plainjava]].

Although the code can be deployed as standalone application and used in batch files, use one of the other available solutions mentioned here. The reason is that starting the Team Platform is relatively costly and comes with a penalty of several seconds. For demonstration purposes, the code can be deployed as application ESNPJ with executable JAR file esnpj.jar and comes with scripts to start and stop an expensive scenario. The scenario information is persisted in a file which allows to run any code required for the scenario. To deploy the code as executable JAR file follow the File =com.ibm.js.team.monitoring.custom.expensivescenario/ReadMe - HowToRelease.txt=. 

The source code can be used in other Java Based applications. This is the primary purpose of this source code.
---++++ Considerations

The code in these projects is based on the RTC Plain Java Client Libraries shipped with the CLM products. The solution can work against all applications based on Jazz Foundation.  The time it takes to execute one of the commands from a command line is approximately twice as long as the OSLC4J based solution. The reason is the initialization of the *TeamPlatform*. But in a situation where the *TeamPlatform* is already loaded and the user login has already been performed, only the code in com.ibm.js.team.monitoring.custom.service.expensivescenario has to be run which will be very fast. This solution is best used in Java server extensions or in Plain Java Client Libraries based automation, where the login into the team repository has already been performed, the *TeamPlatform* is already up and the ITeamRepository object is already available. It can be seamlessly integrated into such a scenario. 

   * Consider using this, in Plain Java Client Library based extensions or automation. 
   * This code supports Open ID Connect or OIDC authentication and works against systems with Jazz Authentication Server enabled.
   * The code seems to work against a clustered CCM server, but test have shown that the custom expensive scenarios are not shown. This is quite surprising and requires investigation. 

---++++ Syntax 

The syntax is as follows

=&lt;publicURI&gt; &lt;userId&gt; &lt;password&gt; mode &lt;scenarionName&gt;=

Where mode is =start= or =stop=.

---++++ Start Scenario

To start a scenario use parameter

=https://clm.example.com:9443/ccm/ ADMIN ****** start MyCustomExpensiveScenario=

---++++ Stop Scenario

To stop a scenario use parameter

=https://clm.example.com:9443/ccm/ ADMIN ****** stop MyCustomExpensiveScenario=
<br>

---++++ How the code works

Here are the details how to use the code in an application based on the Plain Java Client Libraries.

The code provides the Class =ExpensiveScenarioService= that implements the interface =IExpensiveScenarioService= which basically manages the scenario registration information as string. The start command returns the JSON information about the registered expensive scenario as string. This string needs to be passed to the stop command as parameter to stop the expensive scenario.  
The Class =FilePersitentExpensiveScenarioService= that implements the interface =IPersistedExpensiveScenarioService= handles the management of the scenario registration information and persists the information as a JSON file. The start command starts the scenario and stores the JSON information about the registered expensive scenario as file. This file is read by the stop command to stop the expensive scenario. 

The main functionality is implemented in the class

<verbatim>com.ibm.js.team.monitoring.custom.service.expensivescenario.ExpensiveScenarioService.ExpensiveScenarioService(ITeamRepository, String, String)</verbatim>

implementing the interface

<verbatim>com.ibm.js.team.monitoring.custom.service.expensivescenario.IExpensiveScenarioService</verbatim>.

To instanciate a resource intensive scenario instance, you need a teamRepository of type =com.ibm.team.repository.client.ITeamRepository= that is logged into the server, the conext URI and a scenarioname.

It is neccessary to pass the scenario instance information received when starting the scenario to stop the instance. This is done by passing the string scenarioInstance. The following code sequence performs the instantiation, starts and stops the scenario instance using the conext URI ="https://clm.example.com:9443/ccm/"= and the scenarioname ="MyScenario"=.

<verbatim>
IExpensiveScenarioService expensiveScenarioService = new ExpensiveScenarioService(teamRepository,"https://clm.example.com:9443/ccm/", "MyScenario");
String scenarioInstance = expensiveScenarioService.start(client);
expensiveScenarioService.stop(client, scenarioInstance);
</verbatim>

The code contains an implementation that persists the information in a local file. The implementation is in the class 
<verbatim>com.ibm.js.team.monitoring.custom.service.expensivescenario.FilePersitentExpensiveScenarioService.FilePersitentExpensiveScenarioService(IExpensiveScenarioService)
</verbatim>
implementing the interface

<verbatim>com.ibm.js.team.monitoring.custom.service.expensivescenario.IPersistedExpensiveScenarioService</verbatim>

The class uses the interface =com.ibm.js.team.monitoring.custom.service.expensivescenario.IPersistedExpensiveScenarioService=. To create an instance, pass an implementation, e.g. the one created above. The Interface provides =start()= and =stop()= methods. The class =FilePersitentExpensiveScenarioService= performs the scenario instance information handling by persisting it in a file.

<verbatim>
IPersistedExpensiveScenarioService filePersistedExpensiveScenario = new FilePersitentExpensiveScenarioService(expensiveScenarioService);
filePersistedExpensiveScenario.start();
filePersistedExpensiveScenario.stop();
</verbatim>

Also see the code in <verbatim>
com.ibm.js.team.monitoring.custom.service.expensivescenario.RegisterScenarioExample</verbatim>

---+++++!! Related topics: [[DeploymentWebHome][Deployment web home]], [[CLMMonitoringMBeans][CLM Managed Beans Reference]], [[https://jazz.net/library/article/91590][CLM Monitoring]]

---+++++!! External links:          

   * [[https://www.ibm.com][IBM]] 

<sticky></div></sticky>
  
   * [[%ATTACHURL%/Resource_Intensive_Scenario_Windows_cURL_Batch_Examples_V2.zip][Resource_Intensive_Scenario_Windows_cURL_Batch_Examples_V2.zip]]: Example cURL scripts to login and to register a custom scenario
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	Enable_Mbean.png	manage	255.4 K	2019-03-05 - 12:35	ShubjitNaik
png	Repodebug_mbean.png	manage	362.4 K	2019-03-05 - 12:44	ShubjitNaik
zip	Resource_Intensive_Scenario_Windows_cURL_Batch_Examples_V2.zip	manage	1.9 K	2019-04-01 - 08:41	RalphSchoon	Example cURL scripts to login and to register a custom scenario
Deployment
Community information and contribution guidelines
Status icon key:
To do
Under construction
New
Updated
Constant change
None - stable page
Smaller versions of status icons for inline text:
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Ideas, requests, problems regarding the Deployment wiki? Create a new task in the RTC Deployment wiki project