Troubleshooting Direct Access gateway

This section describes various actions you can perform to troubleshoot Direct Access gateway.

Viewing and downloading log files

The log files provide information about Direct Access gateway operations. Qlik Support might ask you to provide log files for troubleshooting purposes. You can view or download the log files in the Log viewer. Under normal circumstances, there is no reason to examine the log files, but if you experience repeated failures or other issues, the log files will often help pinpoint the cause.

To open the Log viewer:

1. In the Administration activity center, go to Data gateways and locate your Direct Access gateway.

2. Click the at the end of the row, and select View logs.

   The Log viewer window opens.

3. From the drop-down list in the top left, choose the type of log that Qlik Support has asked you to view or download.

   The following logs are available:

   • Direct Access gateway logs (DirectAccessAgent)
   • DCaaS logs (dcaas_logs)
   • ODBC-based connector logs (odbc-connector_logs)
   • SAP BW connector logs (QvSAPBwConnector-<date + timestamp>)
   • SAP ODP connector logs (QvSapConnectorPackage-<process_id>)
   • SAP SQL connector logs (QvSqlBwConnector-<date + timestamp>)
   • Connector agent logs (connector-agent_logs_<date>)

4. From the adjacent drop-down list, select the log you want to view or download. The log files are ordered from the newest (the currently active log file) to the oldest. After you select a log file, you can use the and buttons to jump to the start or end of the log file respectively.

   Tip noteThe view of the log file is not updated automatically with the latest messages. To update the view, click to jump to the end of the log file, which will be updated with the latest messages.

5. To download the log file, click Download.

   The file will either be downloaded to your computer or you will be prompted to save it, depending on your browser settings.

Opening Direct Access gateway logs on the Direct Access gateway machine

In addition to being able to download the Direct Access gateway (DirectAccessAgent) logs from the Administration activity center, you can also open them directly from the Direct Access gateway machine. With a default installation, these logs are located in:

C:\Program Files\Qlik\ConnectorAgent\data\logs

Changing the logging detail level

You can view and change the logging detail level of the Direct Access gateway (DirectAccessAgent) logs as needed. To do so, run the following commands from the ConnectorAgent subfolder (C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent with a default installation).

• To view the current logging level, run:

  connectoragent configuration getloggers

• To set the logging level to Trace, run:

  connectoragent configuration setloggers -l Root -v DEBUG

• To set the logging level to Verbose, run:

  connectoragent configuration setloggers -l Root –v DETAILED_DEBUG

Updating the registration key

Changing the registration key might be necessary in the unlikely event that the key becomes corrupted or if you suspect the data gateway server was accessed by an unauthorized user.

To update the registration key:

1. On the Direct Access gateway server, open a Command Prompt as an administrator and change the working directory to the ConnectorAgent subfolder (C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent with a default installation).

2. Run the following commands:

   • Generate the new key:

     connectoragent qcs generate_keys

   • Show the key:

     connectoragent qcs get_registration

     The key is shown:

     

3. Copy the entire key as shown in the example above.

4. In the Administration activity center, open the data gateway settings by clicking the button at the end of the relevant row and selecting Edit.

5. Paste the key into the Key field (replacing the current key) and save the settings.

6. Return to the Direct Access gateway server and restart the Qlik Data Gateway - Direct Access service, as described in Managing the Qlik Data Gateway - Direct Access service.

Extending reload session life

If the connection between Direct Access gateway and Qlik Cloud is idle for 20 seconds or more, the reload operation might sometimes fail with the following error:

Invalid object name '#<TempTableName>' (indicating that the Direct Access gateway temp tables are unavailable).

The default session life is 20 seconds, but if you frequently experience this error, you can extend the session life as follows:

1. Open C:\ProgramData\Qlik\Gateway\configuration.properties as admin. If you are doing this via Windows Explorer, make sure that Show hidden files, folders, and drives is selected.

2. Locate the ODBC_RELOAD_SESSION_LIFE parameter and increase its value as required.
3. Save the configuration.properties file and restart the Qlik Data Gateway - Direct Access service.

Extending the timeout for load requests

When network interruptions occur, reloads might fail with the following errors:

Connector error: The session does not exist (DirectAccess-1509)

Connector error: The stream session expired for the load data request (DirectAccess-1012)

If you frequently encounter the above errors, try setting the EXTEND_FIRST_REQUEST_TIMEOUT parameter to 5-10 minutes.

To do this:

1. Open C:\ProgramData\Qlik\Gateway\configuration.properties as admin. If you are doing this via Windows Explorer, make sure that Show hidden files, folders, and drives is selected.

2. Locate the EXTEND_FIRST_REQUEST_TIMEOUT parameter and increase its value to 5-10 minutes. The default is 0.
3. Save the configuration.properties file and restart the Qlik Data Gateway - Direct Access service.

Mitigating connector crashes during reload

Process isolation allows administrators with direct access to the gateway server operating system to control how many processes are available for reloads per connector type. Spreading reloads across multiple connector processes increases the level of isolation by reducing the number of reloads running concurrently on each connector process. This in turn can improve overall Direct Access gateway stability in cases where connector crashes have occurred.

Turning off process isolation

Qlik Support might ask you to turn off process isolation for troubleshooting purposes.

To turn off process isolation:

1. Open the the C:\ProgramData\Qlik\Gateway\configuration.properties file. If you are doing this via Windows Explorer, make sure that Show hidden files, folders, and drives is selected.

2. Set [ODBC|SAPBW|SAPSQL|SAPPACKAGE]_PROCESS_ISOLATION_MODE to None.

3. Save the configuration.properties file and restart the Qlik Data Gateway - Direct Access service.

Turning on process isolation or changing the number or concurrent reloads

To turn on process isolation or change the number or concurrent reloads:

1. Open C:\ProgramData\Qlik\Gateway\configuration.properties as admin. If you are doing this via Windows Explorer, make sure that Show hidden files, folders, and drives is selected.

   The file contains three prefixes corresponding to the different connector types: ODBC_<property-name>, SAPBW_<property-name>, SAPSQL_<property-name>, and SAPPACKAGE_<property-name>.

2. Set [ODBC|SAPBW|SAPSQL|SAPPACKAGE]_PROCESS_ISOLATION_MODE to Load and [ODBC|SAPBW|SAPSQL|SAPPACKAGE]_MAX_PROCESS_COUNT to N.

   Where:

   N = One command process + The number of concurrent reload processes to allocate. So, for example, a value of 10 would mean a maximum of 9 concurrent reloads.

3. Save the configuration.properties file and restart the Qlik Data Gateway - Direct Access service.

ODBC connector process isolation examples

The following configuration.properties file excerpt shows how to enable ODBC connector process isolation for up to 12 reloads:

ODBC_PROCESS_ISOLATION_MODE=Load

ODBC_MAX_PROCESS_COUNT=13

 

Starting from Direct Access gateway version 1.6.7, the MAX_PROCESS_COUNT value can exceed 10 without needing to change other settings. To fully isolate reloads with a particular connector type (that is, no more than one reload per connector process), this value should be set to a minimum of 30, but you might need to be set it as high as 60 depending on the workload.

Storing corrupted or missing data chunks for future reload

For each reload operation, Direct Access gateway can store corrupted or missing data chunks in memory and offload them to disk. This is especially useful if you do not use automatic recovery and frequently encounter 4025, 4020, and 4021 errors. You turn on this capability by setting the cache size threshold for offloading corrupted or missing data chunks to disk (per reload). When the specified threshold is reached, the gateway will offload the next encrypted chunks to the disk of the Direct Access gateway machine.

To set the cache size:

1. Open C:\ProgramData\Qlik\Gateway\configuration.properties as admin. If you are doing this via Windows Explorer, make sure that Show hidden files, folders, and drives is selected.

2. Set RELOAD_CACHE_MEMORY_MB to N (The default is 0 meaning the capability is not enabled).

   Where:

   N = The size a data chunk can reach before it is reloaded.

   Information noteEnabling this capability will increase memory consumption on the Direct Access gateway machine, so we recommend monitoring the impact on memory while it is enabled. Setting the RELOAD_CACHE_MEMORY_MB value to 100 should be sufficient for most situations.
3. Save the configuration.properties file and restart the Qlik Data Gateway - Direct Access service.