管理主机代理

如果满足前提条件，就可以初始化配置管理。

如果没有激活配置管理，请单击 " 配置管理 "部分中的 Initialize ，初始化基于 Git 的配置管理。

然后，在 "配置管理 "对话框中输入以下信息：

• 远程名称 ： Git 远程名称。
• 远程分支 ：用于更新的分支名称。
• 远程 URI ： Git 资源库的 URI。

单击 Initialize & Restart（初始化和重启 ），根据设置配置代理并重启以获取最新配置。

如果配置管理已激活，则可在 " 配置管理 "部分查看详细信息。 详细信息包括已配置的远程信息（如分支名称和 URI），以及当前使用的提交信息（如哈希值和提交信息）。

要更新配置，请单击更新并在配置管理对话框中输入所需的详细信息。

单击更新和重启 ，根据设置配置代理，并重启以获取最新配置。

要在 Linux 系统上为宿主代理生成堆转储，请在 Linux shell中运行以下命令：

TS=`date +%s` && /opt/instana/agent/jvm/bin/jmap -dump:file=/tmp/agent-dump-$TS.hprof `cat /opt/instana/agent/agent.pid` && gzip /tmp/agent-dump-$TS.hprof

该命令创建堆转储文件，并将压缩文件保存至 /tmp/agent-dump-<timestamp>.hprof.zip。

要在Windows系统上为宿主代理生成堆转储，请在 PowerShell: 中运行以下命令：

$TS = [int][double]::Parse((Get-Date -UFormat %s)); C:\"Program Files"\Instana\instana-agent\jvm\bin\jmap -dump:file="$env:TEMP\agent-dump-$TS.hprof" (Get-Content "C:\Program Files\Instana\instana-agent\agent.pid"); Compress-Archive -Path "$env:TEMP\agent-dump-$TS.hprof" -DestinationPath "$env:TEMP\agent-dump-$TS.hprof.zip" -Force; Remove-Item "$env:TEMP\agent-dump-$TS.hprof"

该命令创建堆转储文件，并将压缩文件保存至 $TEMP\agent-dump-<timestamp>.hprof.zip。

要在 Linux 系统上为宿主代理创建堆转储，请执行以下步骤：

仅当代理程序以 -Dcom.ibm.tools.attach.enable=yes 设置运行时，才能创建临时堆转储。 要验证此设置，请在 Instana 用户界面中打开代理管理仪表板，导航至流程仪表板左侧的 Instana 代理进程实体，并在流程参数列表中 com.ibm.tools.attach.enable 定位。

以下步骤假设 Instana 代理已安装在默认位置， /opt/instana/agent 且该代理作为 Systemd 服务运行。 若您将Instana代理安装在其他位置，则需采用相应路径。

1. 请以 root 用户身份登录 Linux 主机，或将您的 shell 会话切换至 用户 root 。
2. 打开文件 /opt/instana/agent/bin/setenv 进行编辑。
3. 定位以 开头的 EXTRA_JAVA_OPTS= 行，并将属性 -Dcom.ibm.tools.attach.enable=no 更改为 -Dcom.ibm.tools.attach.enable=yes。
4. 使用 systemctl restart instana-agent. 重启代理。
5. 让代理程序运行，直到需要提取堆转储的情况发生。
6. 要在 Linux 系统上为宿主代理生成堆转储，请运行以下命令：

   TS=`date +%s` && /opt/instana/agent/jvm/bin/jcmd `cat /opt/instana/agent/agent.pid` Heap.dump /tmp/agent-dump-$TS.phd  && gzip /tmp/agent-dump-$TS.phd

   该命令创建堆转储文件，并将压缩文件保存至 /tmp/agent-dump-<timestamp>.phd.zip。

要在 Windows 系统上创建主机代理的堆转储，请完成以下步骤：

仅当代理程序以 -Dcom.ibm.tools.attach.enable=yes 设置运行时，才能创建临时堆转储。 要验证此设置，请在 Instana 用户界面中打开代理管理仪表板，导航至流程仪表板左侧的 Instana 代理进程实体，并在流程参数列表中 com.ibm.tools.attach.enable 定位。

以下步骤假设 Instana 代理已安装在默认位置， C:\Program Files\Instana\instana-agent 且该代理作为 Systemd 服务运行。 若您将Instana代理安装在其他位置，则需采用相应路径。

1. 以 Administrator. 身份登录到 Windows 主机。
2. 打开 C:\Program Files\Instana\instana-agent\bin\setenv.bat 文件进行编辑。
3. 定位以 开头的 SET EXTRA_JAVA_OPTS= 行，并将属性 -Dcom.ibm.tools.attach.enable=no 更改为 -Dcom.ibm.tools.attach.enable=yes。
4. 在“服务”Microsoft 管理控制台中，找到“Instana Agent Service”并重新启动该服务。
5. 让代理程序运行，直到需要提取堆转储的情况发生。
6. 创建文件 C:\Users\Administrator\agent-dump.ps1 ，内容如下：

   $TS = [int][double]::Parse((Get-Date -UFormat %s))
   $AGENT_PID = (Get-Content "C:\Program Files\Instana\instana-agent\agent.pid")
   C:\"Program Files"\Instana\instana-agent\jvm\bin\jcmd $AGENT_PID Dump.heap C:\Windows\Temp\agent-dump-$TS.phd
   Compress-Archive -Path C:\Windows\Temp\agent-dump-$TS.phd -DestinationPath C:\Windows\Temp\agent-dump-$TS.phd.zip -Force
   Remove-Item C:\Windows\Temp\agent-dump-$TS.phd

7. 打开以管理员权限运行的 PowerShell。
8. 运行以下命令以创建并运行一个 ScheduledTask 进程，该进程将以 root SYSTEM 账户身份执行堆转储：

   $SchedScript = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument '-ExecutionPolicy Bypass -file C:\Users\Administrator\agent-dump.ps1'
   Register-ScheduledTask -User SYSTEM -taskname !_AgentDump -Action $SchedScript | Out-Null
   Start-ScheduledTask -TaskName "!_AgentDump" 
   Unregister-ScheduledTask -TaskName "!_AgentDump" -Confirm:$false

   该命令创建堆转储文件，并将压缩文件保存至 C:\Windows\Temp\agent-dump-<timestamp>.phd.zip。

您可以使用代理自探测器功能分析 Instana 主机代理的性能指标。

自剖析器仅支持 Linux 系统的 x86_64-bit 架构。 {: note} 要对主机代理进行自我配置，请完成以下步骤：

1. 在代理控制面板的支持部分，单击配置文件代理。 剖析器运行 10 分钟。 您可以检查代理日志，查看剖析器是否已启动。 请参阅以下示例：

   2025-03-19T14:21:48.077+00:00 | INFO  | instana-executor-thread-2-1      | ndRequestHandler | com.instana.agent-self-profiling - 1.0.0 | Starting Agent profiler for 10 minutes
   2025-03-19T14:21:52.998+00:00 | INFO  | instana-scheduler-thread-3-4     | Profiler         | com.instana.agent-self-profiling - 1.0.0 | Profiler installed
    

2. 启动剖析器后，等待 2 分钟，然后刷新仪表板。 在代理仪表板上会出现一个新按钮 " 分析配置文件 "。

3. 单击 " 分析配置文件 "按钮打开 " 分析配置文件 "页面。

4. 在 "分析配置文件 "页面，单击 " 查看全部 "。 您可以共享 " 火焰 "图以及 IBM 支持部门要求的任何其他信息，以便进行代理性能分析。

监测问题类型： agent_tmp_directory_missing

Instana 主机代理会在 $TMP/.instana 目录中创建临时 JAR 文件。 JVM 监控需要这些 JAR 文件。 该警告表示缺少必要的 JAR 文件或 Instana tmp 目录不可用，这可能导致 Java 附件问题。 Instana 代理会定期监控 Instana tmp 目录及其相关 JAR 文件的状态，以防止 Java 附件失效。

为避免这一问题，请确保 tmp 位置具有读写权限，并避免对 /tmp 位置进行不必要的清理。

监测问题类型： insufficient-disk-space-for-tmp-directory

运行时，Instana 代理容器会在 $TMP/.instana 目录中创建临时 JAR 文件。 JVM 监控需要这些 JAR 文件。 此警告表明 tmp 位置没有足够的空间容纳临时文件，这可能导致 Java 附件失败。 要解决这个问题，可在容器部署中增加为 tmp 分配的空间。

监测问题类型： pax_url_mvn_leak

OPS4J Pax URL 2.6.16 版本存在内存泄漏，每 24 小时重置一次，作为代理更新的一部分。 根据在此期间停止和启动的传感器数量，代理可能会遇到 OutOfMemoryError 错误。 为解决这一问题，在 2025 年 6 月 18 日之后发布的代理程序集中添加了一个修复程序。 如果发现此监控问题，请将 Instana 代理程序集更新到 2025 年 6 月 18 日或之后发布的版本。

有关此问题的更多信息，请参阅 pax-url GitHub 仓库中的问题和相应的拉取请求。

监测问题类型： agent_jvm_tls_1_3_missing

Instana 代理需要安装主机支持 TLSv1.3 。 如果不支持 TLSv1.3 ，则会降低监控能力。

要解决这个问题，请将 Instana 代理的 TLS 版本升级到 TLSv1.3。 已启用以下 TLS 版本： TLSv1, TLSv1.1, TLSv1.2, TLSv1.3。更多信息，请参阅 为代理端点设置 TLS 加密。

监测问题类型： solaris_jspawnhelper_executable_issue

此监控问题表明，Solaris 主机上的 jspawnhelper JVM 文件没有可执行权限。

要解决 Solaris JVM 文件权限问题，请使用以下命令为 JVM 路径中的 jspawnhelper JVM 文件提供可执行权限：

chmod +x <jvm-path>/jspawnhelper
 

对于 Java 9 或更高版本，请将 JVM 路径指定为 *instanaAgentDir*/jvm/jre/lib/jspawnhelper。 对于早期版本的 Java，请将 JVM 路径指定为 *instanaAgentDir*/jvm/jre/lib/sparcv9/jspawnhelper。

如果此故障排除部分未能解决您的问题，请联系 IBM Instana 支持团队 ，并提供您的使用情况信息。