Learn how to troubleshoot QuerySurge Agent issues.
Issue 1: A QueryPair Starts Running, but Never Seems to Complete
Periodically, the Agent will appear to start a run (either a Scenario or a Design-Time Run), but will not be fully connected. In these instances, the Agent will hang and the run will never complete. This is usually resolved by restarting your Agent. If restarting your Agent does not rectify the problem, you may need to consider upgrading to our most recent release. Otherwise, please contact Technical Support.
To restart a QuerySurge Agent, you’ll need the following:
- Access to each Agent box with administrative rights.
Restarting an Agent
- Log into the Agent box with administrative rights.
- In the Start menu, launch the Agent Service Console (All Programs > QuerySurge > Open Agent Console).
- Stop the Agent Service using the Stop Agent Service
- Start the Agent Service using the Start Agent Service
Then, exit from the console (File > Exit).
Note: You should repeat this procedure for all your Agents.
Issue 2: A QueryPair isn’t Running, or is Stuck on ‘Loading’
If a QueryPair, Design-Time Run, or Scenario is not running, it is most likely unable to find an Agent. A QuerySurge Agent is responsible for establishing contact with your Connections and executing the queries. If all of your Agents are busy or unavailable, your QueryPairs will not run. QuerySurge will wait for an Agent to become available.
Checking if an Agent is Available
- To check if an Agent is available, you can do any one of the following:
a. Hover over the Agent Status icon in the QuerySurge bottom dock to see a quick view of the Agents’ statuses (for more information on the Agent Status icon, see the icon glossary below):
b. Click on the Agent Status icon in the QuerySurge bottom dock to bring up the Agent Activity window, or click on the Administration menu, and choose View Agents to open the Agents grid.
Note: If all Agents are showing as Offline, you may need to restart the Agent service for each Agent as described in Issue 1.
|
Description |
Icon |
|
No Agents online. Agent icon appears black on bottom when all Agents are offline.
|
|
|
Idle Agent(s). Agent icon appears yellow on bottom when at least one Agent is idle.
|
|
|
Agent(s) executing Scenario or Design-Time Run. Agent icon appears red on bottom when all Agents are busy. |
|
Issue 3: Agent will not Connect
If your Agent will not connect, it may simply require a restart. However, it also might signal that your Agent is using an incorrect URL to communicate with QuerySurge, or that your Agent is disabled.
To restart a QuerySurge Agent, you’ll need the following:
- Access to each Agent box with administrative rights.
Restarting an Agent and Verifying its Connection Details
- Log into the Agent box with administrative rights.
- In the Start menu, launch the Agent Service Console (All Programs > QuerySurge > Open Agent Console).
- Stop the Agent Service using the Stop Agent Service
- Verify the QuerySurge URL is specified correctly, and includes the appropriate port number. If the URL is incorrect, please edit the value in the textbox.
- Start the Agent Service using the Start Agent Service The Agent Service Status should display Started, and the message below it should read CONNECTED.
- Exit from the console (File > Exit).Note: Repeat this procedure for all your Agents.
Issue 4: Agent is not Enabled
This issue often occurs after adding an Agent to your QuerySurge instance. Newly installed Agents will self-register, but will not self-enable. You will need to enable them manually.
Enabling an Agent
- Log into QuerySurge, click on the Administration menu, and select View Agents.
- Select the checkbox in the Enabled column next to the Agent you wish to enable.
Issue 5: Agent Cannot Self-Register or Login
Under normal conditions, the first time an Agent connects to QuerySurge after installation, it performs a self-registration process. If an Agent successfully self-registers, all that is needed is for a QuerySurge Admin user to 'Enable' the Agent (see above 'Agent is not Enabled'). However, if an Agent was previously registered, and subsequently was deleted, and then attempts to self-register, QuerySurge will return an error with the message:
AGENT: <agent.name.com> CANNOT SELF-REGISTER OR LOGIN
If an Agent receives this message, then usually it just means that a QuerySurge Admin needs to log in and manually register the Agent. The manual registration process is as follows:
- Login to an Agent box
- Run the Agent Service Console (this may require elevated or Admin rights on the box)
- Right-click on the Agent Name and use the Copy pop-up to copy the Agent name to the clipboard.
- Open a browser and log into QuerySurge as a QuerySurge Admin user.
- Navigate to the Admin view, and click on Agents in the tree under Users and Agents (upper left).
- Single-click on the Agent listing that is not working. Use the Remove button (main panel, lower right) to remove this Agent.
- Click on the Add button (main panel, lower left)
- In the pop-up, paste the Agent name that you copied from the Agent Service Console. Leave the other choices unchanged from their default values.
- Save the Agent using the Save button at the bottom of the pop-up.
- In the Agent Service Console, cycle the Agent service by clicking on the Stop Agent Service button, and waiting for the service to stop, and then by clicking on the Start Agent Service button.
- Your Agent should now be manually registered.
If your Agent does not connect normally, then you'll need to contact QuerySurge support.
Issue 6: Agent Cannot Run as a Windows Service
When you install a QuerySurge Agent on Windows, by default it will install as a Windows service. However, in some situations, the Agent will install without the correct permissions to run as a Windows service. In this case, you can run the Agent as a standalone application (instead of running as a service). When the Agent is run as a standalone application, a user must be logged in to run the Agent, and the Agent will not automatically restart if the OS is rebooted. Running the Agent in standalone mode can be a helpful approach during a Trial or while the permissions issues are resolved. The following instructions show how to run your Agent as a standalone application:
- Stop any Agent that you want to switch over to standalone mode.
- In Windows Explorer, navigate to the Agent configuration file, at: \\<QuerySurge Install Dir>\QuerySurge\agent\config\agentconfig.xml
- Make a copy of the agentconfig.xml file.
- Edit the file in a text editor. Editing and saving this file may require admin rights. Find the <headless> tag in the file, and change it's value from:
<headless>Y</headless>
to:
<headless>N</headless> - Save the file and close the editor.
- Launch the Agent as a standalone application by double-clicking on the qsagent.bat file. Note: you may need to execute this with 'Run as administrator' privileges. You can find this file at \\<QuerySurge Install Dir>\QuerySurge\agent\qsagent.bat.
You should see the Agent GUI, which looks like:
Issue 7: Agent Hangs on JDBC Driver Loading
QuerySurge Agents are threaded and, by default, start with a "query" thread pool of 3 threads. This means that each Agent can run 3 queries simultaneously. (This is an adjustable parameter; you can change it in the QuerySurge Admin view under QuerySurge Administration > Users and Agents > Agents, by selecting a specific Agent and modifying the Query Thread Pool Size.)
We have observed that Agents can hang during execution unpredictably at the step when multiple threads are loading JDBC drivers in preparation for connecting and querying a database or datastore. Evidence for this issue appears in the Agent logs; at the point where a query thread attempts to load a driver, the log reads:
Mar 22, 2017 6:29:02 PM com.rttsweb.querysurge.h.x k
INFO: Driver Load Started (com.mysql.jdbc.Driver)
If the process proceeds normally with the driver loading, the following log entries indicate that the driver loading has finished:
Mar 22, 2017 6:29:02 PM com.rttsweb.querysurge.h.x k
INFO: Driver Load Completed (com.mysql.jdbc.Driver)
However, if the log lacks an entry indicating that the driver load has completed, this is indicative that the loading process has hung. You should abort your execution in QuerySurge, and stop the Agent.
To further diagnose this issue, log into QuerySurge as an Admin user, and navigate to the Admin view. Select QuerySurge Administration > Users and Agents > Agents, and edit the Agent you are working with. Set the Query Thread Pool Size to 1, and save the change. On the Agent box, re-start the Agent, and in QuerySurge, execute a QueryPair that has previously hung during driver loading on the Agent you have modified. If the QueryPair runs when the Agent is limited to 1 query thread, then this is diagnostic for the problem. After your trial execution with the Agent set with a query thread pool size of 1, set the value back to the default (3 threads).
To resolve this condition, a delay can be inserted between the driver loading steps for the threads. The following instructions describe how to configure the Agent delay between query threads on driver loading:
- Stop your Agent
- Locate the Agent config directory, <QuerySurge Install Dir>\QuerySurge\agent\config\.
On Windows, the default directory is: C:\Program Files\QuerySurge\agent\config\
On Linux, the default directory is: /opt/QuerySurge/agent/config/ - In the Agent config directory, you'll find the config file: agentconfig.xml. Make a copy of this file (agentconfig.xml.bak).
- Carefully edit agentconfig.xml in a text editor. You may need elevated rights (i.e. admin rights) in order to edit and save this file.
- In agentconfig.xml, immediately under the root <config> tag, locate the <loaderId> tag (if the tag doesn't exist, you can add it under the <config> tag level), which looks like:
<config>
....
<loaderId>0:200</loaderId>
....
</config>
The "0:200" notation indicates a 200 millisecond delay between threads for driver loading. Change this to "0:2000" (a 2000 millisecond delay) so that the tag looks like:<config>
....
<loaderId>0:2000</loaderId>
....
</config> - Save the changes to agentconfig.xml.
- Start your Agent, and run a "hanging" QueryPair. If the situation is resolved, replicate the changes on any other Agents that are hanging on driver loading. If the situation is not resolved, raise the delay (continue with a jumps of 500 milliseconds) and try the QueryPair again. You may continue to lengthen the delay, but if you find that the problem is not resolved at 5000 milliseconds, contact support.