This article discusses how to edit and configure your QuerySurge Agent settings.
Configuring a QuerySurge Agent
Configuration Options
QuerySurge Agents have multiple configuration options that can affect how your Agents behave. You can configure your Agents via the Agents section in the QuerySurge Global Administration Portal. To edit an Agent, navigate to the Global Administrative Portal, and choose the Agent node in the tree. Then select an Agent and click the Edit button.
You can also configure your Agents by modifying the agentconfig.xml file in the config/ subdirectory for any Agent, using a text editor:
- Edit your agentconfig.xml file carefully.
- Always stop your Agent process before starting to edit the config file (see below for commands).
- When you modify this file, always make a backup copy of the file before editing; any improper syntax may cause your Agent to be nonfunctional.
Note: When editing an Agent configuration, it will give priority to the latest changes from either the Global Administration settings or the agentconfig.xml file. It is generally best to configure Agents from the Global Administration area to avoid conflicts and confusion.
Note: Some configuration settings, like Agent Heap Size, will need the QuerySurge Agent service to be restarted before changes take effect.
Core Configuration Settings
Core registration settings are set by the Global QuerySurge Administrator when an Agent is registered with QuerySurge:
-
Thread Pool Size - the total number of threads the Agent can use to execute queries. The optimal number will depend on the resources available to your Agent platform. Three (3) threads is a reasonable number to start experimenting with.
Note: As rough benchmark figures, we regularly use 3 threads on 2 GB RAM Agent deployments, and 5 threads on boxes with 4 GB or greater.Note: There is a tradeoff between launching a larger number of query threads vs. the cpu and memory resources required to service those threads while they are executing. At a certain point, more threads can start to slow the Agent down, and increasing the number of threads will eventually lead to lower throughput, not higher. Because Agent performance has Operating System and hardware dependencies, a bit of experimentation in your environment is worthwhile. -
Maximum Thread Polling Interval - The maximum interval the QuerySurge Agent will wait to poll QuerySurge for query instructions in milliseconds.
Note: Default value for this setting is 300000 ms (5 min). - Test Suite Retrieval Behavior - This governs QuerySurge Agent behavior regarding retrieval of Suites. The first option lets the Agent pick up any Suites whether specifically assigned to that Agent or not; the second option forces the Agent to retrieve only Suites specifically assigned to that Agent.
Advanced Configuration
The following configuration options are available via the Global Administration Portal
- Listen for Special Tasks
- Agent Message Size
- Agent Fetch Size
- Agent Heap Size
- Agent Debug Level
- Max Analysis Polling Interval
- Max Connect Retries
- Max Request Retries
- Request Retry Delay
- Outer Polling Loop Wait
Listen for Special Tasks
This setting controls whether the Agent listens for tasks such as Connection Test tasks. The purpose of this setting is to let you 'turn off' certain tasks once they are completed - for example, once your Connections are set up, you won't need all your Agents checking whether any Connection Tests need to be performed. Turing these task requests off cuts down on unnecessary network traffic.
Agent Message Size
This setting gives you control over the maximum message size (in MB) that is sent from the Agent to QuerySurge. The Agent Message Size can have values of 'No Limit' or numeric values. By default, the Agent Message Size is set to 3 MB. Selecting the 'No Limit' setting tells the Agent to use the maximum size allowed, which is a bit under 50 MB. Depending on the memory resources available on your Agent platform, you may want to experiment with message sizes smaller than the maximum. Using smaller message sizes will cause the Agent to send its data in a larger number of smaller messages, saving Agent memory at the expense of a larger number of messages (= greater network traffic).
Note: This setting plays a significant role in Agent heap memory consumption. This, in turn, affects the maximum size Resultset that your Agent can handle with the memory that is available to it.
Agent Fetch Size
This setting allows you to set the JDBC fetch size, in ResultSet rows. According to the JDBC documentation, the fetch size is "the number of rows that should be fetched from the database when more rows are needed for this ResultSet." Selecting 'No Limit' lets the driver make its own choice about how many rows to fetch. Note that according to the JDBC specification, this is only a hint, and driver vendors are permitted to implement this feature at their own discretion, and need not implement it at all. Consult your JDBC driver documentation to see the specifics of how your drivers implement the JDBC fetch size.
Agent Heap Size
This sets the maximum amount of memory that can be allocated to the Java heap. This is a critical parameter, since it governs the heap that the Agent has access to during query execution and processing.
Note: A significant factor in Agent heap memory consumption is how your JDBC driver manages memory. This, in turn, affects the maximum size Resultset that your Agent can handle with the memory that is available to it. There can be significant variation in JDBC drivers here, so it is wise to perfom trials with your driver to see how the Agents behave on the machines you have deployed them on.
There are a couple of important caveats for setting this value:
- Heap size can only be set at launch, so if you choose a new value, you will receive notification that the Agent must be stopped and re-launched.
-
The heap size setting refers to contiguous memory. If your system does not have the amount of memory requested as contiguous memory, the Agent process will immediately exit.
Note: If, on Agent launch, the Agent quits and the log file contains the following error: "Error occurred during initialization of VM. Could not reserve enough space for object heap", then the Operating System could not give the JVM the heap size it requested. To set the heap size request lower so that your Agent will launch, you must edit (use any text editor) the Agent config file (/../config/agentconfig.xml); set the<heap>tag value to a lower value than it is currently set at (1000 MB is the default; this works on most systems), save the file, and re-launch the Agent.Note: If your system is only able to support heap sizes in the hundreds of MB, then the Resultset sizes that your Agent can handle are likely to be relatively small.Note: The Agent Message Size, Agent Fetch Size and Agent Heap Size all interact to shape the size of the queries that your Agent can manage. The QuerySurge Agent installs with default values that are optimized for a generic set of queries; these optimizations are a starting point for work with your queries. Tuning these values using a set of your standard queries is suggested.
Agent Debug Level
This setting controls the debug information output to the Agent log. See the Run a QuerySurge Agent in Debug Mode article for more information.
Max Analysis Polling Interval
This setting controls the maximum polling interval (in seconds) for checking the analysis status.
Max Connect Retries
This setting controls the maximum number of attempts to reconnect in case of a connection failure.
Max Request Retries
This setting indicates the maximum number of retries for a request if it fails initially.
Request Retry Delay
This setting controls the delay (in seconds) between consecutive request retries.
Outer Polling Loop Wait
This setting defines the number of seconds to wait between checking for new executions.