Skip to content
CA Application Performance Management - 10.0
Documentation powered by DocOps

APM Command-Line Workstation

Last update September 9, 2016

The Introscope Command Line Workstation (CLW) is available for performing some of the Introscope Workstation functions. The CLW is useful for automating or scheduling Introscope operations tasks. For example, you can perform repetitive tasks such as disabling multiple alerts in several Management Modules more quickly with the CLW than with the Workstation interface. Similarly, the CLW is useful for scheduling tasks that must be performed automatically or on a periodic basis.

Using CLW commands you can:

  • Manage Management Modules and Elements -- You can list, copy, rename, and delete Management Modules and Elements, see if they are active, and change their current state.
    You can create Management Modules and Elements based on existing ones, using CLW copy and rename commands. You cannot, however, create Management Modules and Elements from scratch, or modify their details using the CLW.
  • Control Agents -- You can start, stop, and resume agent reporting remotely, and copy configuration files to remote agents.
  • Start Transaction Trace Sessions -- You can write scripts to automatically start a Transaction Trace Session as a result of alert conditions.
  • Shut Down the Enterprise Manager -- You can write scripts to shut down the Enterprise Manager on scheduled basis. For example, you might want to stop the Enterprise Manager during off-hours, when using the Workstation might be inconvenient.
  • If the CLW exits -- CLW exits with a 0 value if nothing goes wrong. It will exit with a negative status code if one of the following happens:
    • Enterprise Manager authentication failure.
    • Connection problem with the Enterprise Manager such as a dropped network connection, or invalid host name.
    • There is an invalid WS and Enterprise Manager.

The CLW requires JVM 1.7 or later. You can include CLW commands in script or batch files, or enter them at the command line. The CLW .jar file is installed in the <EM_Home>/lib directory. Run CLW commands from that directory, or include the path to the directory in the commands.

Use CLW Interactive Mode

You can change from the default mode to interactive mode. If you plan on writing scripts for CLW, the interactive mode cannot be used because it will break them.

Follow these steps:

  1. Run CLW commands from <EM_Home>/lib directory, or include the path to the directory in the commands.
  2. Use the -i flag, such as in the following example.
    java-Xmx128M <EM_logon> <TT_properties>-jar CLWorkstation.jar > usage |-i | <command>

Interactive mode will read command line arguments for a command, execute, then exit. However, if no command line arguments are passed, other than JVM options like -DHost=, then it will read and execute one line of standard input and will continue to do so until it reaches the end of the file is reached or you exit the system. If no arguments are passed, and no input is provided, an error will be printed and it will exit the system. All lines that begin with the # symbol will be ignored.

CLW Syntax

CLW commands accept arguments that specify agents, management modules, and other named items in your Introscope deployment. CLW is case-sensitive -- you must enter the names of Introscope objects exactly as they are named. For example, if an agent is named WebLogic1, a CLW command that refers to weblogic1 does not execute for that agent. CLW commands return their output to the command window. You can direct command output to a file, as appropriate. When you supply CLW command arguments that contain spaces, surround the argument with quotation marks ("), and include a backslash in front of each quotation mark, to prevent the shell from interpreting the quotation mark. For example:

\"2005/01/01 12:20:37\"

The CLW command syntax is:

java  -Xmx128M <EM_logon>-jar CLWorkstation.jar <command>


  • - Xmx128M sets the Java heap size, preventing java.lang.OutOfMemoryError errors that might otherwise occur.
  • <EM_logon> is your Enterprise Manager logon information:

    -Duser=<user name>
     - Dpassword=<password>
     - Dhost=<Enterprise Manager host / ip address>
     - Dport=<Enterprise Manager port number>
  • <command> is one of the commands described in the CLW Command Reference.

For example:

java  -Xmx128M -Duser=jdoe -Dpassword=mypassword -Dhost=jdoeDT
 -Dport=5001 -jar CLWorkstation.jar <command>

Default logon values for accessing the Enterprise Manager are used if you invoke the CLW without supplying your logon information:

java  -Xmx128M -jar CLWorkstation.jar <command>

Every CLW command you enter at the command line or in a script must start with the CLW invocation:

java  -Xmx128M -jar CLWorkstation.jar
Note: To avoid getting a java.lang.OutOfMemoryError, set the Java heap size.

CLW and Regular Expressions

You can use CLW commands to manipulate elements of your Introscope environment, such as agents, management modules, dashboards, actions, and alerts. Depending on the type of target, you can perform operations such as copy, list, rename, activate, and deactivate.

Regular expression syntax varies depending on your operating system and command shell, and in some cases, based on whether you enter the expression at the command line or in a script. The sample commands are for a Windows environment, and reflect the syntax required to use regular expression in a batch file.

You designate the target or targets of a CLW command using exact text strings or Perl regular expressions. For example, this CLW command lists all agents connected to the Enterprise Manager:

list agents matching (.*)

Note: For Linux OS, use single quotes. Example: '(.*)'

This command lists only agents whose name contains the string weblogic:

list agents matching .*weblogic.*

Configure the Command Line Workstation Log

You can configure CA APM to log Command Line Workstation (CLW) commands to the Enterprise Manager console and the IntroscopeEnterpriseManager.log file, which is located in the <EM_Home>/logs directory.

Follow these steps:

  1. Open the file located in the <EM_Home>\config directory.
  2. Configure these properties in the file to enable the logging of CLW commands in the log file and on the Enterprise Manager console:
    1. Set log4j.additivity.Manager.CLW=true.

      Note: The default value for this property is false.
    2. Set log4j.logger.Manager.CLW=DEBUG.
      The default value for this property is INFO.
Was this helpful?

Please log in to post comments.