Skip to content
DevTest Solutions - 8.0.1
Documentation powered by DocOps

CAI Command-Line Tool

Last update January 13, 2015

The PFCmdLineTool command lets you perform various CA Continuous Application Insight tasks from the command line.

The main options are --count, --roots, --paths, --export, --import, --baseline, and --virtualize.

This command has the following format:

PFCmdLineTool [--count|--roots|--paths|--export|--import|--baseline|--virtualize|--help|--version] [task-specific options] [search-criteria]

Search Criteria

For all the main options except --import, the set of transaction frames that are acted on is defined by those matching the search criteria specified. Use any of the following options to specify the search criteria: --from, --to, --localIP, --remoteIP, --category, --class, --method, --session, --transaction, - agent, --min-time, --tag, and --max-frames. These options are used to narrow the set of root transaction frames that are acted on.

Alternately, you can use the --frame option to limit the search results to a single transaction frame.

  • --from=start-time
    Specifies the start time of the window of transaction frames you want. Use either of the following formats: yyyy-mm-dd or yyyy-mm-ddThh:mm:ss. If this option and the --frame option are not specified, the start of the current day is used.
  • --to=end-time
    Specifies the end time of the window of transaction frames you want. Use either of the following formats: yyyy-mm-dd or yyyy-mm-ddThh:mm:ss. If this option and the --frame option are not specified, the end of the current day is used.
  • --localIP=IP address
    Specifies the client-side IP address that CAI records.
  • --remoteIP=IP address
    Specifies the server-side IP address that CAI records.
  • --category=category
    Specifies the type of transaction frame. You can search for more than one category at a time by repeating this option.
    Values: amx, client, dn_default, dn_remoting, dn_sql, ejb, gui, jca, jdbc, jms, logging, mq, rest_http, rmi, rmi_http, rmi_ssl, thread, throwable, tibco, web_http, web_https, wm, wps, ws_http, ws_https
  • --class=class-name
    Specifies the class name. The value can be either the full class name or a string ending with '%' to perform a "starts with" type of match.
  • --method=method-name
    Specifies the method name. The value can be either the full method name or a string ending with '%' to perform a "starts with" type of match.
  • --session=session-id
    Specifies the session identifier.
  • --transaction=transaction-id
    Specifies the transaction identifier.
  • --agent=agent-name
    Specifies the name of the agent that is the source for the transaction frames you want.
  • --min-time=min-time
    Specifies the minimum execution time (in milliseconds) of transaction frames you want to see. Frames that are executed faster than this value are filtered out.
  • --tag=name, --tag=name=value
    Specifies a frame tag that is associated with a transaction frame. You can specify the name only, or both the name and value. You can search for more than one tag at a time by repeating this option.
  • --max-frames=max-frames
    Specifies the maximum number of root transaction frames that are retrieved. If this option is not specified, it defaults to 10000. There can be circumstances when more frames are processed than the maximum.
  • --frame=frame-id
    Specifies the identifier of the particular transaction frame desired.

Querying and Display

The following options let you query and display transactions.

  • -c, --count
    Displays the number of root transaction frames that match the specified search criteria.
  • -r, --roots
    Displays the root transaction frames that match the specified search criteria.
  • -p, --paths
    Displays the transaction frame hierarchy for a set of root transaction frames.

Export and Import

The following options let you export and import paths.

  • -e output-zip-file-name, --export=output-zip-file-name
    Exports the selected transaction frames from the database.
  • -i input-zip-file-name, --import=input-zip-file-name
    Imports transactions into the database. Any search criteria that you specify is ignored.
  • --no-persist
    Specifies that the import operation does not persist the data, causing the import file to be validated only.

Note: When DevTest is connected to a database other than the default Derby, you need to specify the database to the broker element of the rules.xml file.

<database driver="yourdatabasedriver" url="yourdatabaseurl" user="yourdatabaseuser" password="yourdatabasepassword"/>

This setting is used for the lifetime of the agent.

Baselines

The following options let you create baseline test cases and suites. The --to-dir option or the --to-project option is required.

  • -b name, --baseline=name
    Generates baseline tests for the selected transaction frames.
  • --refer=frame-id
    Specifies the identifier of the particular transaction frame that is designated as the key transaction frame. If this option is not specified, the first transaction frame in the query result is designated as the key transaction frame.
  • --consolidated
    Specifies that a baseline test case is generated. If this option is not specified, a baseline suite is generated.
  • --stateful
    Specifies that a stateful baseline is generated.
  • --force-tf-steps
    Specifies that baseline tests are generated using the Execute Transaction Frame step only. If this option is not specified, any available CA Application Test test steps are used whenever possible.
    Note: For more information about the Execute Transaction Frame step, see Using CA Application Test.
  • --magic-dates
    Specifies that baseline tests have magic date processing applied.
  • --http-user=http-user
    Specifies the web application user name. CAI encrypts the value and adds the result to the Authorization header field in the baseline. This option is applicable to stateful baselines for the following protocols: REST, Web HTTP, and Web Service.
  • --http-passwd=http-passwd
    Specifies the web application user password. CAI encrypts the value and adds the result to the Authorization header field in the baseline. This option is applicable to stateful baselines for the following protocols: REST, Web HTTP, and Web Service.
  • --param-level=param-level
    Specifies the parameterization level for REST stateful baselines. The valid values are 1 (match on value only) and 2 (match on key and value).
  • --assertion=assertion-type
    Specifies the stateful baseline assertion type.
    Values: 1, 2, 3. If the value is set to 1 and the assertion returns false, the test fails. If the value is set to 2 and the assertion returns false, the test generates a warning. If the value is set to 3 and the assertion returns false, the test generates an error. The default value is 1. 
  • --jndi-factory=factory-class-name
    Specifies the JNDI factory class to use when generating EJB baseline tests.
  • --jndi-url=url
    Specifies the JNDI URL to use when generating EJB baseline tests.
  • --jndi-user=user-id
    Specifies the JNDI user to use when generating EJB baseline tests.
  • --jndi-user-cred=user-credentials
    Specifies the JNDI user credentials to use when generating EJB baseline tests.
  • --to-dir=output-pfi-file-name
    Specifies the name of the directory where the generated PFI file is written.
  • --to-project=lisa-project-dir
    Specifies the root directory of a project into which the generated artifacts are written, without the requirement of an intermediate import file. You can specify this option instead of, or in addition to, the --to-dir option.

Virtualization Artifacts

The following options let you generate virtualization artifacts. The --to-dir option or the --to-project option is required.

  • -v name, --virtualize=name
    Generates virtualization artifacts for the selected transaction frames.
  • --refer=frame-id
    Specifies the identifier of the particular transaction frame that is designated as the key transaction frame. If this option is not specified, the first transaction frame in the query result is designated as the key transaction frame.
  • --force-stateless
    Specifies that VSE conversational processing is applied when generating a service image.
  • --unknown-request-action=no_match|no_hijack
    Specifies the action that is taken for unknown requests. This option applies to generated virtualization artifacts based around Java VSE. The valid values are no_match (return a "no match") and no_hijack (bypass the virtual service).
  • --to-dir=output-pfi-file-name
    Specifies the name of the directory where the generated PFI file is written.
  • --to-project=lisa-project-dir
    Specifies the root directory of a project into which the generated artifacts are written, without the requirement of an intermediate import file. You can specify this option instead of, or in addition to, the --to-dir option.

Agent Condition

The following options let you check for a specified condition in an agent. The only supported condition is whether the agent is currently dispatching. The term dispatching refers to the action of capturing transactions.

  • --check
    Checks for a specified condition in an agent.
  • --agent=agent-name
    Specifies the name of the agent.
  • --condition=condition
    Specifies the condition to check for.
    Values: Dispatching
  • --check-timeout=number-of-seconds
    Specifies the number of seconds to wait for the condition before timing out.

Capture Levels

The following options let you modify the capture level for each protocol that the Java agent can capture.

Note: Setting different capture levels is not supported for queue-based client and server communication, for example, WebSphere MQ and JMS.
  • --set-weights
    Modifies the capture level for one or more protocols.
  • --agent=agent-name
    Specifies the name of the agent.
  • --protocols="protocol[,protocol]"
    Specifies the protocol names. If you include more than one value, separate the values by commas.
    Values: ALL, HTTP Client, HTTP Server, Logging, Category, Exception, GUI, EJB, JMS, MQ, JCA, RCP, RMI, SAP, Tibco, WPS, WebMethods, JDBC
  • --weights="weight[,weight]"
    Specifies the protocol weights. If you include more than one value, separate the values by commas.
    Values: 0, 4, 8. The value 0 corresponds to the Counts level. The value 4 corresponds to the Counts and Paths level. The value 8 corresponds to the Full Data level.

Miscellaneous

The following options are also available.

  • --broker=broker-url
    Specifies the broker connection string. The default value is tcp://localhost:2009.
  • --search-frame
    Searches for the transaction frame that matches the specified search criteria and frame name.
  • --frame-name=frame-name
    Specifies the name of a transaction frame to search for.
  • --help -h
    Displays help text.
  • --version

    Prints the VSE version number.

Example: Display Root Transaction Frames

This example shows how to display the root transaction frames for a specified agent and start time.

PFCmdLineTool --roots --agent=JBoss_LISABank --from=2014-03-14T12:28:00

Frame ID                              Time                     Category  Local IP       Remote IP      Name     Exec Time

------------------------------------  -----------------------  --------  -------------  -------------  -------  ---------

c3a9c830-abae-11e3-b937-0024d6ab5ce2  2014-03-14 12:28:04 660  web_http  10.132.92.143  10.132.92.143  Unknown  984 ms

Example: Display Transaction Frame Hierarchy

This example shows how to display the transaction frame hierarchy for a set of root transaction frames.

PFCmdLineTool --paths --agent=JBoss_LISABank --from=2014-03-14T12:28:00

984 ms /lisabank/buttonclick.do (c3a9c830-abae-11e3-b937-0024d6ab5ce2)

   50 ms $Proxy93.getUser (c3c73b40-abae-11e3-b937-0024d6ab5ce2)

      37 ms EJB3UserControlBean.getUser (c3c8c1e0-abae-11e3-b937-0024d6ab5ce2)

         3 ms SQL Activity (1) (c3c8c1e0-abae-11e3-b937-0024d6ab5ce2-SQL)

Example: Generate a Baseline Suite

This example shows how to generate a baseline suite.

PFCmdLineTool --baseline=BaselineName --refer=c3c8c1e0-abae-11e3-b937-0024d6ab5ce2 --to-dir=C:\DevTest

Example: Generate a Stateful Baseline

This example shows how to generate a stateful baseline.

PFCmdLineTool --baseline=BaselineName --stateful --from=2014-03-14T12:28:00 --refer=c3c8c1e0-abae-11e3-b937-0024d6ab5ce2 --to-dir=C:\DevTest

Example: Generate Virtualization Artifacts

This example shows how to generate virtualization artifacts.

PFCmdLineTool --virtualize=VSEServiceName --from=2014-03-14T12:28:00 --refer=c3c8c1e0-abae-11e3-b937-0024d6ab5ce2 --category=ejb --to-dir=C:\DevTest

Example: Check the Agent Condition

This example shows how to check whether an agent is capturing transactions. The output indicates that the agent is not capturing transactions.

PFCmdLineTool --check --agent=JBoss_LISABank --condition=Dispatching --check-timeout=10

Agent has not yet started dispatching.

Example: Configure the Capture Level

This example shows how to modify the capture level for one protocol.

PFCmdLineTool --set-weights --agent=JBoss_LISABank --protocols=EJB --weights=8

This example shows how to modify the capture level for multiple protocols. Notice the use of quotation marks.

PFCmdLineTool --set-weights --agent=JBoss_LISABank --protocols="EJB,JMS" --weights="8,4"

Example: Search Transaction Frame by Name

This example shows how to verify whether CAI captured a particular transaction frame by the frame name. If the search finds more than one matching frame, the newest frame is displayed. The output consists of the name, duration, and unique identifier.

PFCmdLineTool --search-frame --frame-name=EJB3AccountControlBean.addAccount --from=2014-03-20T10:20:00

EJB3AccountControlBean.addAccount, 141 ms, 27ca1bd0-b03c-11e3-a8f1-005056ba138a

Was this helpful?

Please log in to post comments.