Overview
AIE ships with support for performing query load testing using the Apache JMeter tool. Apache JMeter is an open source pure-Java application designed to load-test Java systems and measure their performance. AIE's JMeter module adapts Apache JMeter to work with a multi-node AIE project.
The JMeter module was removed from Attivio Platform 5.5.1. Users can view the Administrator UI's Performance Monitor, System Status, and System Events pages to see the output that used to be available in JMeter, as noted on this page, and they can use the aie-exec loadgen or aie-exec querygen tools to simulate ingestion load or query load, respectively, on the system.
If desired, users can download JMeter from the Apache website (http://jmeter.apache.org/) and run it on their own.
See the Performance Monitor
Many of the JMeter monitoring features provided before release 3.5 have been subsumed by the Performance Monitor , System Status, and System Events displays of the Use the Attivio Administrator.
As a side-effect of these improvements, it is no longer possible to use JMeter to monitor ingestion rates, query rates, garbage-collection, or memory utilization. Current use of JMeter is restricted to simulating multiple users making query demands on the system.
View incoming links.
Running JMeter with AIE
Follow these procedures to get JMeter running with your AIE project.
Multi-Node Procedure
The following procedure sets up a multi-node system and then connects the JMeter interface to it.
- JMeter is already part of your AIE installation. You don't have to download or install any JMeter files.
Use createproject to create an AIE project that includes the JMeter module:
<install-dir>\bin\createproject -n <projectName> -m jmeter -o <parent-of-project-dir>
- Set up the topology of your multi-node system in the usual way, by editing <project-dir>\conf\environments\default\topology-nodes.xml and <project-dir>\conf\topology-layout.xml. (Step-by-step instructions for setting up a four-node system may be found on the Multi-Node Topologies page.)
Start AIE using the AIE Agent and its Command-Line Interface (CLI).
Use aie-exec jmetertestgen to create a test plan for the project. This plan takes the form of a file, <projectName>.jmx, that configures JMeter to connect to the AIE project.
Start the system first; then generate the test plan.
<install-dir>\bin\aie-exec.exe jmetertestgen -z host:16080 -n <project-name>
The file will be written to the <install-dir>\bin directory by default.
Start JMeter. (Note: When you start JMeter, it will open a display window. So, if you start AIE JMeter on a Linux machine, make sure the window can be displayed correctly. Cygwin or similar tools are good choices.)
<install-dir>\modules\jmeter\bin\aie-jmeter.bat -t <install-dir>\bin\<projectName>.jmx
This opens the JMeter user interface and connects it to the nodes of the AIE project.
Single-Node Procedure
AIE presumes that you are using JMeter to monitor a multi-node system. To apply JMeter monitoring to a single-node system, we must configure the project as a multi-node system that just happens to have only one node!
Add the following code snippets to the indicated configuration files:
<topology agentPort="16999" projectdir=".">
<nodes>
<node name="local" host="localhost" port="17000" />
</nodes>
</topology>
<topology>
<layout default-service-nodeset="local" default-ingest-nodeset="local" default-query-nodeset="local" />
</topology>
Then follow the procedure in the previous section. When it is time to start to AIE node, use start-aie-multi.bat to start the local node.
<project-dir>\start-aie-multi.bat local host:16080
Then complete the start-up procedure as before.
Notes on the Auto-Generated Test Plan
The aie-exec jmetertestgen executable combines a built-in template with a project configuration to generate a project-specific test plan. The generated test plan will include elements for generating query load and commits.
Example
aie-exec.exe jmetertestgen -z vmnode-073:16080 -n name
The standard configuration server (-z) and project name (-n) arguments are all that are required. The output file defaults to projectName.jmx or can be set using the -o option.
Please be aware that, while JMeter allows for modification of the individual thread groups and other features generated in this test plan, modifications beyond the default configuration created by jmetertestgen are for expert users only and are not supported.
Fortunately, you can always go back to jmetertestgen and create a new, default test plan file.
Notes on Launching JMeter
JMeter ships with AIE in the $AIE_HOME/modules/jmeter directory. Running JMeter requires using a custom bat or bash file in order to properly set up the classpath to access AIE jars.
Example (windows)
%AIE_HOME%\modules\jmeter\bin\aie-jmeter.bat -t <projectName>.jmx
Example (linux)
$AIE_HOME/modules/jmeter/bin/aie-jmeter -t <projectName>.jmx
Using JMeter with AIE
Once you have JMeter open and connected to AIE, we can use it to place various loads on ingestion and query workflows, and the observe the results in the Performance Monitor.
Test Plan, Thread Groups, and Tests
The automatically-generated Test Plan appears in the tree pane. Each thread group node may be thought of as a test. It is configured by the individual samplers, timers, and listeners that are grouped under that node. (The Apache JMeter User Manual is very thorough. This section describes only the features that are pertinent to AIE.)
The nodes that are gray are not enabled. To enable a node, right-click the node and look for the enable option in the context menu.
To run the enabled tests, use the video control buttons in the control bar at the top of the screen.
Feed Content
You can control and monitor the activity of your ingestion feeds from JMeter.
Feed Content Thread Group
These are the parameters for the Feed Content Thread Group. Samplers used in this group will run connectors, so it is probably best to have them run once and then stop.
Control | Description |
|---|---|
Action to be taken | Select the action you want to take when there is an error in JMeter. "Stop Test Now" was selected in this example. |
Number of Threads (users) | Specifies how many concurrent users you want to simulate. |
Ramp-Up Period | Specifies how many seconds to take to "ramp-up" to the full number of users (threads) chosen. |
Loop Count | Specifies how many times you want to execute the test. |
Search Client Sampler
The Search Client Sampler lets you configure one connector.
If you want to monitor all the connectors in your system, you have to define them in the "Feed Content" thread group.
To add a new connector, you can right click on a existing one and select "Copy", then modify the following configuration parameters to meet your needs:
- Name (under Java Request) - The name will display under Feed Content for a connector. It's NOT necessary to use the name you defined in the config file.
- Comments - Optional.
- Classname - Use the default (ConnectorSampler).
- connector - Specifies the name of the connector. You have to use the identical name as you defined in your config file.
- baseUri - Specifies the URI for the connector, http://hostRunningTheConnector:nodePort+1
- targetDPS - Specifies the maxim DPS.
Run Queries
JMeter can use an external text file to generate keyword queries, simulating multiple users bombarding the system with queries.
Sample Query File
Below is an example of what a sample query file might look like. This would be a simple text file with one column of keywords:
Lettuce Nigeria England Apple Banana Carrots Peas Rice Pine Nuts China Norway
We put it in the *<project-dir>\conf* directory, but the location of the file is not critical.
Run Queries Thread Group
You must enable the Run Queries thread group. Use the right-click menu as described above on this page.
Control | Description |
|---|---|
Action to be taken | Select the action you want to take when there is an error in JMeter. "Stop Test Now" was selected in this example. |
Number of Threads (users) | Specifies how many concurrent users you want to simulate. |
Ramp-Up Period | Specifies how many seconds to take to "ramp-up" to the full number of users (threads) chosen. |
Loop Count | Specifies how many times you want to execute the test. |
Search Client Sampler
The Run Queries Thread Group has a Java Request window labeled Search Client where you can custom-configure aspects of your query setup.
Uses for each of the fields shown in this UI are outlined in the table below:
Field | Description |
|---|---|
baseUri | Specifies the URI for connecting to the AIE instance. |
queryFile | Specifies the file to be used for query criteria. In the default implementation, the class specified is com.attivio.jmeter.querygen.KeywordQueryGenerator, which takes as input a file with one term per line, and uses that file, in combination with com.attivio.jmeter.sampler.RandomSearchClient (specified in the Classname dropdown), to randomly send query terms from the list. Custom classes can also be used for other types of query generation as long as they also implement the QueryGenerator interface. |
userFile | Specifies the principals to be used for the queries in systems where security is enabled. |
realm | Specifies the realm ID (also for secure systems). |
facets | A comma-separated list of facet fields to make requests on. |
facetsPerQuery | Number of facets to use on each request. if less than the number of facets a random sub-select is made. If -1, all facets are requested. |
seed | The random-number seed to be used if repeatability is desired. |
keepResponse | Accumulate the query-response documents for inspection. |
Target QPS Timer
The query mechanism can be throttled to produce no more than a given number of queries per second. This is the role of the Target QPS Timer.
The object is to describe an increasing load. It begins with a certain number of requests-per-second (RPS), gradually increases for some duration, and reaches a maximum RPS value just before shutting down. The UI helpfully shows the profile of expected query loading in the graph at the bottom of the screen.
Viewing the Results
To see the query loading of AIE, view the totalQps metric in the Performance Monitor. The following graph shows three bursts of query activity.
In addition, the Run Query Thread Group includes several Listeners that report the results of the query event.
- Response Times Percentiles
- Response Times Over Time
- Response Times Distribution
- Error Results
- Aggregate Report