webMethods Integration Server Service Profiler (ISSPROF) v1.3 ================================================================================ Wrightia (c) 2006-2012 (README file for Windows 2K, XP & 2003 Server) 1. Introduction 2. Installation 2.1 Instructions for webMethods versions prior to v8.2 2.1.1 IS running as Windows Service 2.2 Instructions for webMethods versions from v8.2 onwards 2.2.1 IS running as Windows Service 3. Uninstall 4. Upgrading 5. Further Reading 1. Introduction The ISSPROF is a tool to collect and analyze runtime information about IS Services. It is intended to have a small footprint while running, be easy and fast to install and uninstall, and to require no configuration over the Services being profiled. 2. Installation Install the profiler by installing the following IS Packages, in the order they are presented: - WiaRoot.zip - WiaUtilities.zip - WiaServiceProfiler.zip The presented ZIP filenames may have a version suffix appended to its name. These suffixes are not indicated to have this readme file version independent. Depending on the version of the IS where you are installing this tool, follow the instructions in the corresponding sub-section. 2.1 Instructions for webMethods versions prior to v8.2 After installing the IS Packages the installation must be completed by configuring the Integration Server. Perform the following steps: a) Shutdown the IS; b) Edit the startup script; Save a copy of the file 'server.bat' as 'server.org.bat'; Edit the script file 'server.bat' and insert a call to a 'setenv.bat' script at the point shown below with '---->' and as indicated. ... ----> Call %IS_DIR%\serviceprofiler\bin\setenv.bat set CLASSPATH=%PREPEND_SYSTEM_CLASSPATH%;%CLASSPATH%;%APPEND_SYSTEM_CLASSPATH% set PATH=%PATH%;%IS_DIR%\support\win32;%IS_DIR%\jvm\bin\classic;%IS_DIR%\lib; rem rem Run as an NT service ? If so, save program arguments to Registry rem if "1%1"=="1-service" ( ... d) Start the Integration Server; e) Set the tool License Key. Access the Service Profiler licensing page and set the License Key. The IS can be prevented from starting with the Service Profiler, without the need to uninstall it, by means of putting a file named ISSPROF_VOID in the '\IntegrationServer' folder. The presence of this file skips the loading sequence. A direct result is having the functionality links in the tool menu disabled. IMPORTANT: When installing webMethods upgrades (i.e., Service Packs) the server.bat script may be overwritten thus disabling the Service Profiler start-up. When this happens, just repeat the script edit step described above. 2.1.1 IS running as Windows Service There is no additional setting for using the Service Profiler on an IS running as a Windows (NT, W2K, XP) Service. If the IS is already running as a Windows Service you need to unregister it and register it again. The same is valid when uninstalling the tool. As required and documented by Software AG, all actions that change the Java command line require the Windows Service to be unregistred and be registered again. 2.2 Instructions for webMethods versions from v8.2 onwards The webMethods v8.2 shell scripts introduce the segregation of starting the JVM into a specific script: '\profiles\IS\bin\runtime.bat'. Save a copy of the file 'runtime.bat' as 'runtime.org.bat'; To continue using the 'server.bat' to start the IS, all there is to do is to add the line... Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" ... right before the Java command line in 'runtime.bat', like this: ... title %WINDOW_TITLE% if "%USE_WRAPPER%"=="yes" ( goto use_wrapper ) Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" echo Starting as an application using Java. %JAVA_RUN% %JAVA_OPTS% %JAVA_SYSPROPS% -jar %OSGI_FRAMEWORK_JAR% -debug -configuration %OSGI_CONFIGURATION_AREA% %2 %3 %4 %5 %6 %7 %8 %9 ... To use the Tanuki wrapper, the preparation scripts already create the necessary configuration settings and add them to the '\profiles\IS\configuration\wrapper.conf'. A copy of the file is saved before the changes are made with the name 'wrapper.conf.beforeissprof'. 2.2.1 IS running as Windows Service Save a copy of the file 'server.bat' as 'server.org.bat'; To be able to use the Service Profiler with an IS running as an NT Service, the same statement that was added to 'runtime.bat' needs to be added to the 'server.bat'. So, in 'server.bat' to add the line... Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" ... right the removal of the LOCKFILE statement, like this: ... rem rem Run as an NT service ? If so, save program arguments to Registry rem rem Run as Server JVM set SERVER_VM_OPT=-server if "1%1"=="1-service" ( Call "%IS_DIR%\serviceprofiler\bin\setenv.bat" if exist LOCKFILE del LOCKFILE "%JAVA_EXEC%" -classpath %IS_PROXY_JAR% com.wm.app.server.CustomServiceUpdater -isdir "%IS_DIR%" -wrapperdir "%IS_DIR%\..\profiles\IS\configuration" -binpath "%PATH%" -jvmargs "%SERVER_VM_OPT% %JAVA2_MEMSET% %JAVA_OPTS%" -progargs %3#%4#%5#%6#%7#%8#%9 goto :EOF ) ... If the IS is already registered as a Windows Service you need unregister it and register it again. The registration must be done only after the changes indicated above. The same is valid when uninstalling the tool. As required and documented by Software AG, all actions that change the Java command line require the Windows Service to be unregistred and be registered again. To use the Tanuki wrapper, the preparation scripts already create the necessary configuration settings and add them to the '\profiles\IS\configuration\wrapper.conf' file. A copy of the file is saved before the changes are made to the name 'wrapper.conf.beforeissprof'. 3. Uninstall To uninstall the tool: a) Shutdown the IS; b) Revert the edited start-up scripts back to their saved originals, or just remove the lines inserted upon installation (refer to point 2 in this document); Depending on the IS version, which files are these may vary. c) Delete the folder '\IntegrationServer\serviceprofiler'; d) Delete the folder for the package 'WiaServiceProfiler'; e) If the IS is running as an NT Service, unregister the service and register it again; f) Start the IS. Optionally, you can remove the IS Packages 'WiaUtilities' and 'WiaRoot'. 4. Upgrading Due to the nature of the tool, its architecture and the runtime behaviour, and also depending on the nature of the upgrade it may require steps beyond the simple (re)installation of an IS Package and/or patch. Due to the complexity of this subject, please refer to the User Guide for guidance. 5. Further Reading Reading the Profiling Whitepaper is recommended as the next reading document. This document is available for download from Wrightia's website. A direct link to it is provided in the installed 'WiaServiceProfiler' IS Package (see the Info package), The About page includes an Abstract of the Service Profiler, and links to Release Notes and Version History. The Online Help is useful to quickly check the way to use the tool. The User Guide is a more detailed documentation about using the Service Profiler, concerning all the aspects about using the tool.