Ruby 故障排除

验证您的环境是否受支持，以及您运行的 Ruby 版本是否受支持。

在花太多时间诊断问题之前，首先要确保相关组件和环境是受支持的。 所有支持组件的列表可在 Ruby 支持版本中找到。

检查安装步骤。

验证是否正确遵循了安装步骤。

验证应用程序捆绑包中是否安装了 Instana Ruby gem。

您可以通过查看应用程序 Gemfile 中的 gem "instana" 和 Gemfile.lock 文件中提及的 instana 进行验证。 或者， 在 Ruby 应用程序目录下运行 bundle exec gem list。 此命令会列出应用程序捆绑包中的所有 Ruby gem。 验证 Instana Ruby gem 是否在该列表中。

确保 Instana gem 是最新版本。

发布的最新版本可在 RubyGems. 在 Gemfile.lock 中，您必须看到 Instana Ruby gem 的最新版本，并在名称旁边注明，如 instana (x.x.x)。

验证应用程序日志输出中是否提到 Instana。

应用程序或容器日志必须始终包含类似于 Stan is on the scene. Starting Instana instrumentation version x.x.x

启用调试输出并重新检查应用程序或容器日志。

为 Ruby 流程设置环境变量 INSTANA_DEBUG=true，然后重新验证应用程序或容器日志（与 #3相同）。 特别注意是否存在任何与 Instana 相关的错误信息。

检查 Instana 主机代理日志，查看是否有与 Ruby 进程相关的信息。

尝试从控制台以 "verbose（详细）"模式启动 Ruby 应用程序。

如需启动，请参阅应用程序中的测试部分。 特别注意查看 Ruby 应用程序输出中是否出现任何与 Instana 相关的错误信息。

提交支持单。

如果您验证了前面的所有步骤，但 Ruby 进程仍未显示在 Instana 面板上，请打开支持案例进行进一步调查。

支持票据必须包括

1. 环境详情：平台、Ruby 版本和使用的框架
2. 前面所有验证的总结。

检查是否支持您的应用程序框架。

检查 Ruby 应用程序中正在使用的组件是否受支持。

检查 ::Instana::Rack 中间件是否处于活动状态。

如果使用的是基于 Rack 的框架（如 Ruby on Rails），请确保 ::Instana::Rack 中间件已作为中间件正确安装。 在正常情况下，会针对各种框架自动安装此中间件。

要在 Ruby on Rails 中进行验证，可以运行以下命令：

bundle exec rake middleware

您必须查看 ::Instana::Rack 的条目。 如果需要安装，可以手动安装。

在 Gemfile 中使用 require => false 检查是否延迟加载 Instana gem。

不鼓励延迟加载 Instana Ruby gem，因为各种堆栈中的引导过程通常严格且依赖于顺序。 延迟加载的一个常见症状是缺少 ::Instana::Rack Rack 中间件，而该中间件可启动对传入请求的跟踪。

如果出于某种原因，你仍然喜欢后期加载 Instana Ruby gem，那么请务必按照安装 Instana Rack 中间件的手册说明 （如有需要）进行安装。

启用调试输出并重新检查应用程序或容器日志。

为 Ruby 流程设置环境变量 INSTANA_DEBUG=true，然后重新验证应用程序或容器日志（与 #3相同）。 特别注意是否出现任何与 Instana 相关的错误信息。

从应用程序控制台生成自定义跟踪。

如果其他方法都不奏效，可以打开应用程序控制台，运行以下命令生成自定义跟踪：

require "instana"

Instana.tracer.in_span(:my_custom_trace) do
  sleep 1
end

成功并启用调试输出（如上一步所述）后，必须在应用程序日志中看到以下一行：

Instana:: Reporting 1 spans

然后，查看 Instana 仪表板（查询分析下的 call.span_type SDK ）。 您必须看到一个名为 "my_custom_trace "的跟踪。

检查 Instana 主机代理日志，查看是否有与 Ruby 进程相关的信息。

提交支持单。

如果您验证了所有步骤，但 Instana 仪表板上仍看不到 Ruby 跟踪，请提交支持票据以进一步调查。

支持票据必须包括

1. 环境详情：平台、Ruby 版本和使用的框架
2. 前面所有验证的总结。

确保代理有足够的资源来处理请求

如果采取了限制代理所需 CPU 和内存的措施，请确保所设置的限制为代理提供了足够的资源，使其能够完成所有必要的任务。

禁用流程查找

通过将下列内容添加到代理程序配置，您还可以禁用代理程序的“快速路径”。 这种配置可以减少代理消耗的资源，但如果进程在向代理发送任何数据之前退出，则可能导致跟踪被丢弃。 对于使用 fork 作为并发基元并带有短暂子进程的应用程序，通常会出现这个问题。

com.instana.processlookup:
  enabled: false