故障排除 Direct Access gateway
本节介绍了可以执行的各种操作以进行 Direct Access gateway 故障排除。
查看和下载日志文件
日志文件提供有关 Direct Access gateway 操作的信息。Qlik 支持人员可能会要求您提供日志文件以进行故障排除。您可以在日志查看器中查看或下载日志文件。在正常情况下,没有理由检查日志文件,但如果您遇到重复故障或其他问题,日志文件通常有助于查明原因。
要打开日志查看器,请执行以下操作:
-
在 Administration 活动中心中,转到数据网关并找到您的 Direct Access gateway。
-
单击行末尾的
,然后选择查看日志。
日志查看器窗口打开。
-
从左上角的下拉列表中,选择 Qlik 支持部门要求您查看或下载的日志类型。
有以下日志可用:
- Direct Access gateway 日志 (DirectAccessAgent)
- DCaaS logs (dcaas_logs)
- 基于 ODBC 的连接器日志 (odbc-connector_logs)
- SAP BW 连接器日志(QvSAPBwConnector-<日期 + 时间戳>)
- SAP ODP 连接器日志 (QvSapConnectorPackage-<process_id>)
- SAP SQL 连接器日志(QvSqlBwConnector-<日期 + 时间戳>)
- 连接器代理日志 (connector-agent_logs_<日期>)
-
从相邻的下拉列表中,选择要查看或下载的日志。日志文件按从最新(当前活动的日志文件)到最旧的顺序排列。选择日志文件后,可以使用
和
按钮分别跳到日志文件的开头或末尾。
提示注释日志文件的视图不会自动更新为最新消息。要更新视图,请单击跳到日志文件的末尾,日志文件将用最新消息更新。
-
要下载日志文件,请单击下载。
该文件将被下载到您的计算机上,或者系统会提示您保存该文件,具体取决于您的浏览器设置。
正在打开 Direct Access gateway 计算机上的 Direct Access gateway 日志
除了可以从 Administration 活动中心下载 Direct Access gateway (DirectAccessAgent) 日志外,还可以直接从 Direct Access gateway 计算机打开这些日志。对于默认安装,这些日志位于:
C:\Program Files\Qlik\ConnectorAgent\data\logs
更改日志级别
您可以更改 Direct Access gateway 日志的记录级别,如下所述。
更改连接器组件的日志记录级别
为排除故障,您可能需要更改连接器组件日志的记录级别。
要做到这一点,请按以下步骤操作:
- 以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties 如果是通过 Windows 资源管理器执行此操作,请确保已选中显示 > 隐藏项目。
-
找到 <COMPONENT>_LOG_LEVEL 属性的位置,其中 COMPONENT 可以是以下之一:
- AGENT
- DCAAS
- ODBC
- SAPBW
- SAPSQL
- SAPPACKAGE
- FILE
- 将其设置为以下选项之一:ERROR、WARN、INFO 或 DEBUG
-
保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
信息注释从 Direct Access gateway 1.7.1 开始,如果只更改了 AGENT 组件,则无需重新启动 Qlik Data Gateway - Direct Access 服务。
更改 DirectAccessAgent 日志级别
为排除故障,您可能需要更改 DirectAccessAgent 日志的记录级别。DirectAccessAgent 负责连接 Qlik Cloud 服务。要查看和更改 DirectAccessAgent 日志的日志详细级别,请从 ConnectorAgent 子文件夹运行以下命令(默认安装位置为 C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent)。
-
要查看当前日志记录级别,请运行:
connectoragent configuration getloggers -
要将日志记录级别设置为“跟踪”,请运行:
connectoragent configuration setloggers -l Root -v DEBUG -
要将日志记录级别设置为“详细”,请运行:
connectoragent configuration setloggers -l Root –v DETAILED_DEBUG
更新注册密钥
如果密钥损坏或怀疑数据网关服务器被未经授权的用户访问,则可能需要更改注册密钥。
更新注册密钥:
- 在 Direct Access gateway 服务器上,以管理员身份打开命令提示符并将工作目录更改为 ConnectorAgent 子文件夹(对于默认安装为 C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent)。
-
然后运行以下命令:
-
生成新的密钥:
connectoragent qcs generate_keys
-
显示密钥:
connectoragent qcs get_registration
显示密钥:
-
-
复制整个密钥,如上面的示例所示。
-
在 Administration 活动中心中,通过单击相关行末尾的
按钮并选择编辑来打开数据网关设置。
-
将密钥粘贴到密钥字段(替换当前密钥)并保存设置。
-
返回到 Direct Access gateway 服务器并重新启动 Qlik Data Gateway - Direct Access 服务,如管理 Qlik Data Gateway - Direct Access 服务中所述。
延长重新加载会话寿命
如果 Direct Access gateway 和 Qlik Cloud 之间的连接空闲 20 秒或更长时间,则重新加载操作有时可能会失败,并出现以下错误:
Invalid object name '#<TempTableName>' (indicating that the Direct Access gateway temp tables are unavailable).
默认会话寿命为 20 秒,但如果您经常遇到此错误,可以按如下方式延长会话寿命:
-
以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示隐藏的文件、文件夹和驱动器。
- 找到 ODBC_RELOAD_SESSION_LIFE 参数并根据需要增大其值。
- 保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
延长加载请求的超时时间
当网络中断发生时,重新加载可能会失败,并出现以下错误:
Connector error: The session does not exist (DirectAccess-1509)
Connector error: The stream session expired for the load data request (DirectAccess-1012)
如果您经常遇到上述错误,请尝试将 EXTEND_FIRST_REQUEST_TIMEOUT 参数设置为 5-10 分钟。
为此:
-
以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示隐藏的文件、文件夹和驱动器。
- 找到 EXTEND_FIRST_REQUEST_TIMEOUT 参数并根据需要增大其值至 5-10 分钟。默认值为 0。
- 保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
减轻重新加载过程中的连接器崩溃
进程隔离 允许直接访问网关服务器操作系统的管理员控制每个连接器类型可用于重新加载的进程数。通过减少每个连接器进程上同时运行的重新加载次数,在多个连接器进程之间分散重新加载可以提高隔离级别。这反过来又可以在发生连接器崩溃的情况下提高整体 Direct Access gateway 稳定性。
需要 Direct Access gateway 1.6.1 或更高版本。
关闭进程隔离
Qlik 支持团队可能会要求您关闭进程隔离以进行故障排除。
要关闭进程隔离:
- 打开 C:\ProgramData\Qlik\Gateway\configuration.properties 文件。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示隐藏的文件、文件夹和驱动器。
-
将 [ODBC|SAPBW|SAPSQL|SAPPACKAGE]_PROCESS_ISOLATION_MODE(按条件将所有行着色)设置为 None(指定行)。
- 保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
打开进程隔离或更改数量或并发重新加载
要打开进程隔离或更改数量或并发重新加载,请执行以下操作:
-
以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示隐藏的文件、文件夹和驱动器。
该文件包含三个前缀,对应于不同的连接器类型:ODBC_<property-name>、SAPBW_<property-name>、SAPSQL_<property-name> 和 SAPPACKAGE_<property-name>。
-
将 [ODBC|SAPBW|SAPSQL|SAPPACKAGE]_PROCESS_ISOLATION_MODE 设置为 Load 并将 [ODBC|SAPBW|SAPSQL|SAPPACKAGE]_MAX_PROCESS_COUNT 设置为 N。
其中:
N = 一个命令进程 + 要分配的并发重新加载进程的数量。因此,例如,值为 10 意味着最多 9 次并发重新加载。
- 保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
ODBC 连接器进程隔离示例
以下 configuration.properties 文件摘录显示了如何为最多 12 次重新加载启用 ODBC 连接器进程隔离:
ODBC_PROCESS_ISOLATION_MODE=Load
ODBC_MAX_PROCESS_COUNT=13
缓存数据,以便在出现问题时重新加载
对于每次重新加载操作,Direct Access gateway 可将数据块缓存在内存中,并将其卸载到磁盘(当超出分配给缓存的大小时)。如果您不使用自动恢复,并且经常遇到 4025、4020 和 4021 错误,这尤其有用。您可以通过设置缓存大小阈值来启用此功能,该阈值用于将数据块卸载到磁盘(每次重新加载)。当达到指定的阈值时,网关将把下一个加密块卸载到 Direct Access gateway 机器的磁盘上。
要设置缓存大小,请执行以下操作:
-
以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示隐藏的文件、文件夹和驱动器。
-
将 RELOAD_CACHE_MEMORY_MB 设置为 N(默认值为 0,表示该功能未启用)。
其中:
N = 为缓存数据块分配的内存量(每次重载)
信息注释启用此功能将增加 Direct Access gateway 计算机上的内存消耗,因此我们建议在启用此功能时监视对内存的影响。对于大多数情况,将 RELOAD_CACHE_MEMORY_MB 值设置为 100 应该已足够。 - 保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
覆盖默认的块缓存目录
对于每次重新加载操作,Direct Access gateway 可将数据块缓存在内存中,并将其卸载到磁盘(当超出分配给缓存的大小时)。如果系统驱动器上没有足够的磁盘空间,则可以覆盖默认块缓存目录 (C:\ProgramData\Qlik\Gateway\tmp) 。
为此:
- 使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示 > 隐藏项目。
-
定位 OVERRIDE_CHUNKS_CACHE_DIR 属性,并将其设置为所选目录。
示例:
OVERRIDE_CHUNKS_CACHE_DIR=C:\tmp
信息注释不要将路径括在引号中。 - 保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
使用 ODBC(经由 Direct Access gateway)连接器时覆盖默认 Qlik Cloud 数据类型
有时,由于供应商 ODBC 驱动程序处理源数据类型的问题,在重新加载过程中会出现错误,或者会向 Qlik Cloud 加载不正确的数据。在这种情况下,您可以覆盖 Qlik Cloud 数据类型或其规范(例如比例或精度)。
为此:
- 使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\custom_type_mapping.json。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示 > 隐藏项目。该文件包含 Qlik Cloud 数据类型的一个示例源。
-
添加一个部分,将有问题的数据类型映射到所需的 Qlik Cloud 数据类型。
在以下示例中(包含在 custom_type_mapping.json 文件中),客户需要将 Qlik Cloud DateTime 数据类型的大小更改为 27。
{
"Identifier": "Amazon Athena ODBC (x64)",
"NativeDataType": "timestamp with time zone",
"QlikDataType": "DateTime",
"Size": 27,
"IsBit": false
}
- 保存 custom_type_mapping.json 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
- 重新加载数据。
强制 Direct Access gateway 重新连接到 Qlik Cloud
默认情况下,如果Direct Access gateway 与 Qlik Cloud 断开连接,则应在 45 秒后重新连接。如果您发现需要更长的时间,可以强制网关更快地重新连接。
为此:
- 使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作,请确保已选中显示 > 隐藏项目。该文件包含 Qlik Cloud 数据类型的一个示例源。
-
将 AGENT_PONG_TIMEOUT_SECONDS=<time-in-seconds> 添加到文件开头的 # Connector Agent 部分。
示例:
AGENT_PONG_TIMEOUT_SECONDS=30
信息注释最短时间为 30 秒。 - 保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
增加连接到 ODBC 数据源时的错误消息详细信息
出于安全考虑,ODBC 驱动程序返回的默认错误消息包含的信息很少。但是,在某些情况下,您可能需要更多信息来解决特定问题。要获取更详细的错误消息,请将 ShowErrorDetailMessage 属性添加到连接器对话框的高级部分,并将其设置为 True。解决问题后,为了获得最佳安全性,强烈建议删除该属性或将其设置为 False。