Recording business use cases and timing information with use case recorder

Prerequisites

Ensure to meet the system requirements and the following requirements.

• Ensure that you have the contents of the command line tool bundle.

• Ensure that you have enough disk space to run business use cases.

  Running the Java monolithic application with instrumentation can generate a large volume of trace statements in log files. For a Java monolithic application that has many business functions, you might generate runtime trace files of 1 - 2 GB each. If you want to run all the business use cases, you must ensure that your server has enough available disk space to contain the generated logs. In most cases, your Java monolithic applications run in middleware regardless of whether they are containerized.

  Before you run test cases, you might need to increase the maximum size of the log files and the number of log versions to be retained. Do these increases for the specific instances of middleware that host the Java monolithic applications. For more information, see the following information:

  • Configuring the JVM logs for WebSphere Application Server
  • Logging and tracing for Liberty or Open Liberty

  • Relevant documentation for Java monolithic applications hosted in other Java middleware.

  Depending on the size of your Java monolithic application and the number of use cases that you run, the number of log files might still exceed the maximum amount your application server can retain. In this situation, copy the log files to a safe location before you start the application server to prevent writing over older logs with new ones.

  You might alternatively run test cases in batches to reduce the disk space and total log file size requirements. Be aware, though, that this technique increases operational complexity. With this technique, run a few test cases. Copy the generated log files, which contain the trace statements, to some permanent storage. Then, remove the log files before you run the next batch of test cases.

• Ensure that a relevant and comprehensive set of test cases covers all the business functions of your Java monolithic application so that you get sound partition recommendations.

  To generate runtime traces from the deployed Java monolithic applications with instrumentation, you need relevant test cases that cover all the different business functions of the Java monolithic applications. A test case corresponds to a business use case. For some Java monolithic applications, you might have automated test suites. For other Java monolithic applications, you might have manual test cases. In some cases, you might have a combination of both automated test suites and manual test cases. The runtime traces that are generated when you run business use cases represent temporal flows that are across the started methods of various classes. These classes correspond to specific use cases. Partition recommendations hinge on these temporal flows. A comprehensive set of runtime traces generates sound partition recommendations. You get a comprehensive set of runtime traces when you run a comprehensive set of test cases, which cover all the functions of your Java monolithic applications.

  For Mono2Micro to match relevant portions of the runtime traces with individual business use cases, Mono2Micro must know the start and stop timestamps of these use cases. Since CPU time settings for computers on a network vary, start and stop timestamps for use cases must be recorded based on a central time server such as an NTP server.

When to run the use case recorder interactively versus automatically

You can run test cases with the use case recorder interactively or automatically depending on whether you automated test suites.

You must run the use case recorder interactively if you run business use cases manually. The interactive version of the use case recorder is a command line utility of IBM Mono2Micro for recording business use cases along with their start and stop timestamps.

If you automated your test suite, you can choose how you run the use case recorder:

• Run the use case recorder interactively when you manually run all the test cases in your test suite.

• Enhance your test suite by incorporating relevant portions of the Embedded-Flicker.java file or its equivalent so that you can run the test suite automatically.

  An enhanced test suite creates one or more JSON files that contain the test case names along with the timestamps in the format that is required by the AI engine.

  If your test suite is written in a language other than Java and you want to run the test suite automatically, write your own version of the embedded use case recorder logic. It must be written in the same language as your test suite and then added to your test suite. Capture times to the millisecond.

Running the embedded use case recorder with automated test suites

After you download and extract the IBM Mono2Micro command line tool bundle, the embedded use case recorder is in the flicker-embedded subdirectory. The following example shows how to integrate the example Java code for the embedded use case recorder into your test code. The code creates the ContextWriter class and then calls the start() method with the testLabel variable for various test cases in a for loop. Your test case runs. Then, the code calls the stop() method on the ContextWriter class within the loop. After the test cases run, the results are written to a file.

ContextWriter cw = new ContextWriter();
for (...) {
String testLabel = ... // test name
ContextWriter.Test t = cw.start(testLabel);
...
// run test
...
t.stop();
}
File file = ... // output file
cw.write(file);

The ContextWriter class takes care of the timestamps and JSON formatting, and does not require any additional libraries. The following information is an example of output that is produced from the previous pseudocode:

[
  {
    "offset": 0,
    "session": [
      {
        "STOP": 1598903879631,
        "LABEL": "Logintest",
        "START": 1598903879513
      },
      {
        "STOP": 1598903880631,
        "LABEL": "Logofftest",
        "START": 1598903879631
      }
    ],
    "appserver": ""
  }
]

The Embedded-Flicker.java file does not need extra libraries to compile or run when you add it to a larger program. When you run it, you must specify an output file.

Running the use case recorder interactively

The following information describes the use case recorder command line utility and various scenarios for running it.

To run the use case recorder interactively, use the following command line syntax.

mono2micro usecase [-o <filename>.json | --ntp <ipaddress>]

If the <filename>.json file is not specified with the -o parameter, the use case recorder creates a default context_<timestamp>.json file. If you specify a file name, the use case recorder first checks whether the file exists in the path from which you are running the mono2micro tool. If the file exists, the use case recorder opens the file and appends the results of the present run into it. Otherwise, the use case recorder creates a new file with the specified name. The appending mode is useful if you want a consolidated output from multiple runs of the use case recorder for the same Java monolithic application.

Your application environment might fall into one of the following three scenarios.

Scenario 1

To run the use case recorder in the same machine where your application runs, do not specify the --ntp option because both the use case recorder and the application server are using the time from the same machine.

mono2micro usecase [-o <filename>.json]

Scenario 2

If you must run the use case recorder in a machine different from where the application server runs, you must first start an NTP server in the application server machine.

You can use the SimpleNTPServer Java utility that is part of the open source commons-net-examples-3.6.jar file as a minimal UDP NTP server. When the SimpleNTPServer Java utility runs on the application server machine, the use case recorder runs on a client machine. The use case recorder can get the difference in the system time values of the client and application server machines by using its built-in support.

You first go to directory where you extracted the Mono2Micro-CLI.zip bundle and then to the simplentpserver subdirectory. Then, run the SimpleNTPServer Java utility in the application server machine.

• The following example runs the utility on Linux® or Mac operating systems.

  java -cp commons-net-3.6.jar:commons-net-examples-3.6.jar:. examples/ntp/SimpleNTPServer

• The following example runs the utility at a Windows™ command line.

  java -cp .\commons-net-3.6.jar;.\commons-net-examples-3.6.jar;. examples/ntp/SimpleNTPServer

• The following example runs the utility on Windows PowerShell.

  java -cp "commons-net-3.6.jar;commons-net-examples-3.6.jar;." "examples.ntp.SimpleNTPServer"

This command starts the minimal UDP NTP server in the application server machine with an output statement like Running NTP service on port 123/UDP.

After the SimpleNTPServer Java utility starts, run the use case recorder in the client with the -ntp option. This option provides the IP address of the application server, which is also the IP address of the minimal NTP server.

mono2micro usecase -n <ipaddress> [-o <filename>.json]

CPU clocks tend to drift. However, the drift is usually not much. You can run the SimpleNTPServer Java utility once a day before you run any test case for your Java monolithic applications. After the testing completes for the day, you can stop the SimpleNTPServer Java utility.

If your Java monolithic application runs inside a container, you must check the CPU clock of the container. Check whether it has the same timestamp as the host machine, bare metal, or the VM where your container is running. If they are the same, you can run the SimpleNTPServer Java utility on the host machine while the application runs in a container. Otherwise, you have two choices:

• When you build the container for the application, ensure that the container and its host machine have identical timestamps, so that you can run the SimpleNTPServer Java utility on the host machine. This option is the simpler one.
• Package the commons-net-3.6.jar and commons-net-examples-3.6.jar file in the simplentpserver directory along with the application when you build the container. After the container starts, bash into the container and keep the SimpleNTPServer Java utility running in the workstation window. When you run the use case recorder, you must provide the IP address of the container on the --ntp option.

Scenario 3

You might not be able to run the use case recorder on the application server machine because of security policies of specific environments. The security restrictions might prevent you from running the SimpleNTPServer Java utility in application server machines. Alternatively, they might prevent you from connecting the use case recorder of the client machine to the SimpleNTPServer Java utility that runs in an application server.

In such cases, try running the test cases with a pause of approximately 2 minutes between test cases. IBM Mono2Micro uses this relatively large time difference between individual test cases to properly associate segments of runtime traces with the completed business use cases.

Use case recorder output

The output of a successful use case recorder run is a JSON file that contains the test case names and their start and stop timestamps. The following command line invocation demonstrates an example use case recorder run for the Daytrader application.

/m2m$ mono2micro usecase -o Usecase_Daytrader.json

Enter <Label> to start recording current context or enter 1 to exit.
Trade Processor
Enter 9 to stop the recording of the current context.
9
LABEL                         START               STOP
Trade Processor               1622494511471       1622494516201
Enter <Label> to start recording current context enter 1 to exit.
Trade Logic
Enter 9 to stop the recording of the current context.
9
LABEL                         START               STOP
Trade Processor               1622494511471       1622494516201
Trade Logic                   1622494534638       1622494540418
Enter <Label> to start recording current context or enter 1 to exit.
1

The example use case recorder run displays the following information:

• The command to start the interactive version of the use case recorder.
• A command that tells the user to enter a label so that the use case recorder starts recording the current context.
• The Trade Processor label that the user entered.
• A command that tells the user to enter 9 to stop the recording of the current context.
• The 9 value entered by the user.
• A table with the LABEL column, the START column, and the STOP column. The Trade Processor label is in the LABEL column. The start timestamp is in the START column. The stop timestamp is in the STOP column.
• A repeat of the previous actions, but this time a label of Trade Logic is used. The table is displayed again, but includes a row for the Trade Logic label after the row for the Trade Processor label.

The following JSON document contains the contents of the Usecase_Daytrader.json file for the Daytrader example. In this example, the offset value is 0 and the appserver entry for the application server is an empty string because the use case recorder was run without the --ntp option. If the --ntp option is specified, the offset value is a nonzero value and the appserver entry for the application server has a valid IP address.

[
  {
    "offset": 0,
    "session": [
      {
        "STOP": 1622494516201,
        "LABEL": "Trade Processor",
        "START": 1622494511471
      },
      {
        "STOP": 1622494540418,
        "LABEL": "Trade Logic",
        "START": 1622494534638
      }
    ],
    "appserver": ""
  }
]

Flow chart of running the use case recorder interactively with test cases

The following figure summarizes the process of running test cases that you defined for your business use cases.

What to do next

Run the AI engine to get application partitioning recommendations with the mono2micro recommend command.