探查器自动检测

代理可以使用 .NET CLR Profiling API 自动检测 .NET Framework、.NET Core 和 .NET 应用程序。Profiling API 提供了一种无需更改代码即可检测应用程序或依赖代码的方法。

此方法适用于以下情况

** 由于 Microsoft 引入的绑定问题，为获得最佳兼容性，我们建议至少使用 .NET Framework 4.7.2。*

*** GLIBC 最低版本为 2.14。*

它检测以下程序集

配置 profiler 自动检测的一般步骤如下；请参阅检测容器和服务，了解常见部署环境的配置方法。

1. 从 .NET APM Agent GitHub 存储库的Releases 页面下载 elastic_apm_profiler_<version>.zip 文件，其中 <version> 是要下载的版本号。您可以在 Assets 下找到该文件。

2. 将 zip 文件解压到托管要检测的应用程序的主机上的一个文件夹中。

3. 配置以下环境变量

   set COR_ENABLE_PROFILING = "1"
   set COR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}"
   set COR_PROFILER_PATH = "<unzipped directory>\elastic_apm_profiler.dll"
   set ELASTIC_APM_PROFILER_HOME = "<unzipped directory>"
   set ELASTIC_APM_PROFILER_INTEGRATIONS = "<unzipped directory>\integrations.yml"
   set ELASTIC_APM_SERVER_URL = "<apm server url>"
   set ELASTIC_APM_SECRET_TOKEN = "<secret token>"
   

   1. <unzipped directory> 是步骤 2 中解压 zip 文件的目录。
   2. 应将跟踪和指标发送到的 APM 服务器 intake URL。
   3. APM Agent 用于向 APM 服务器进行身份验证的secret token。

   set CORECLR_ENABLE_PROFILING = "1"
   set CORECLR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}"
   set CORECLR_PROFILER_PATH = "<unzipped directory>\elastic_apm_profiler.dll"
   set ELASTIC_APM_PROFILER_HOME = "<unzipped directory>"
   set ELASTIC_APM_PROFILER_INTEGRATIONS = "<unzipped directory>\integrations.yml"
   set ELASTIC_APM_SERVER_URL = "<apm server url>"
   set ELASTIC_APM_SECRET_TOKEN = "<secret token>"
   

   1. <unzipped directory> 是步骤 2 中解压 zip 文件的目录。
   2. 应将跟踪和指标发送到的 APM 服务器 intake URL。
   3. APM Agent 用于向 APM 服务器进行身份验证的secret token。

   export CORECLR_ENABLE_PROFILING=1
   export CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}
   export CORECLR_PROFILER_PATH="<unzipped directory>/libelastic_apm_profiler.so"
   export ELASTIC_APM_PROFILER_HOME="<unzipped directory>"
   export ELASTIC_APM_PROFILER_INTEGRATIONS="<unzipped directory>/integrations.yml"
   export ELASTIC_APM_SERVER_URL = "<apm server url>"
   export ELASTIC_APM_SECRET_TOKEN = "<secret token>"
   

   1. <unzipped directory> 是步骤 2 中解压 zip 文件的目录。
   2. 应将跟踪和指标发送到的 APM 服务器 intake URL。
   3. APM Agent 用于向 APM 服务器进行身份验证的secret token。

确保在设置的环境变量可见的上下文中启动应用程序。

通过此设置，.NET 运行时将 Elastic 的 CLR profiler 加载到 .NET 进程中，该进程在应用程序启动早期加载并实例化 APM agent。profiler 会监控感兴趣的方法并注入代码以检测它们的执行。

使用全局环境变量会导致在主机上启动的任何 .NET 进程加载 profiler 自动检测。通常，环境变量应仅为特定的服务或容器设置。以下各节演示如何配置常见的容器和服务。

包含 profiler 自动检测文件的构建镜像可以作为多阶段构建的一部分使用。

ARG AGENT_VERSION=<VERSION>

FROM alpine:latest AS build
ARG AGENT_VERSION
WORKDIR /source

# install unzip
RUN apk update && apk add zip curl

# pull down the zip file based on ${AGENT_VERSION} ARG and unzip
RUN curl -L -o elastic_apm_profiler_${AGENT_VERSION}.zip https://github.com/elastic/apm-agent-dotnet/releases/download/v${AGENT_VERSION}/elastic_apm_profiler_${AGENT_VERSION}.zip && \
    unzip elastic_apm_profiler_${AGENT_VERSION}.zip -d /elastic_apm_profiler_${AGENT_VERSION}

1. 将 <VERSION> 替换为要下载的 profiler zip 文件的最新发布版本号（例如，ARG AGENT_VERSION=1.26.0）。

然后可以将文件复制到后续阶段

COPY --from=build /elastic_apm_profiler_${AGENT_VERSION} /elastic_apm_profiler

可以在 Dockerfile 中添加环境变量来配置 profiler 自动检测

ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}
ENV CORECLR_PROFILER_PATH=/elastic_apm_profiler/libelastic_apm_profiler.so
ENV ELASTIC_APM_PROFILER_HOME=/elastic_apm_profiler
ENV ELASTIC_APM_PROFILER_INTEGRATIONS=/elastic_apm_profiler/integrations.yml

ENTRYPOINT ["dotnet", "your-application.dll"]

可以通过向 Windows 注册表添加条目来向特定的 Windows 服务添加环境变量。使用 PowerShell：

$environment = [string[]]@(
  "COR_ENABLE_PROFILING=1",
  "COR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}",
  "COR_PROFILER_PATH=<unzipped directory>\elastic_apm_profiler.dll",
  "ELASTIC_APM_PROFILER_HOME=<unzipped directory>",
  "ELASTIC_APM_PROFILER_INTEGRATIONS=<unzipped directory>\integrations.yml"
  "ELASTIC_APM_SERVER_URL=<apm server url>"
  "ELASTIC_APM_SECRET_TOKEN=<secret token>")

Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<service-name> -Name Environment -Value $environment

$environment = [string[]]@(
  "CORECLR_ENABLE_PROFILING=1",
  "CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}",
  "CORECLR_PROFILER_PATH=<unzipped directory>\elastic_apm_profiler.dll",
  "ELASTIC_APM_PROFILER_HOME=<unzipped directory>",
  "ELASTIC_APM_PROFILER_INTEGRATIONS=<unzipped directory>\integrations.yml"
  "ELASTIC_APM_SERVER_URL=<apm server url>"
  "ELASTIC_APM_SECRET_TOKEN=<secret token>")

Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<service-name> -Name Environment -Value $environment

1. <unzipped directory> 是 zip 文件解压到的目录。
2. 应将跟踪和指标发送到的 APM 服务器 intake URL。
3. APM Agent 用于向 APM 服务器进行身份验证的secret token。
4. <service-name> 是 Windows 服务的名称。

然后必须重新启动服务才能使更改生效。使用 PowerShell：

Restart-Service <service-name>

对于 IIS 10 之前的版本，无法将环境变量的作用域限定在特定的应用程序池中，因此环境变量需要全局设置。

对于 IIS 10 及更高版本，可以使用 AppCmd.exe 为应用程序池设置环境变量。使用 PowerShell：

$appcmd = "$($env:systemroot)\system32\inetsrv\AppCmd.exe"
$appPool = "<application-pool>"
$profilerHomeDir = "<unzipped directory>"
$environment = @{
  COR_ENABLE_PROFILING = "1"
  COR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}"
  COR_PROFILER_PATH = "$profilerHomeDir\elastic_apm_profiler.dll"
  ELASTIC_APM_PROFILER_HOME = "$profilerHomeDir"
  ELASTIC_APM_PROFILER_INTEGRATIONS = "$profilerHomeDir\integrations.yml"
  COMPlus_LoaderOptimization = "1"
  ELASTIC_APM_SERVER_URL = "<apm server url>"
  ELASTIC_APM_SECRET_TOKEN = "<secret token>"
}

$environment.Keys | ForEach-Object {
  & $appcmd set config -section:system.applicationHost/applicationPools /+"[name='$appPool'].environmentVariables.[name='$_',value='$($environment[$_])']"
}

1. <application-pool> 是您的应用程序使用的应用程序池的名称。例如，IIS APPPOOL\DefaultAppPool
2. <unzipped directory> 是 zip 文件解压到的目录的完整路径
3. 强制程序集不以域中立方式加载。当前存在一个限制：当程序集以域中立方式加载时，Profiler 自动检测无法检测它们。此限制预计将在未来版本中移除，但目前可以通过设置此环境变量来解决。有关详细信息，请参阅 Microsoft 文档。
4. 应将跟踪和指标发送到的 APM 服务器 intake URL。
5. APM Agent 用于向 APM 服务器进行身份验证的secret token。

$appcmd = "$($env:systemroot)\system32\inetsrv\AppCmd.exe"
$appPool = "<application-pool>"
$profilerHomeDir = "<unzipped directory>"
$environment = @{
  CORECLR_ENABLE_PROFILING = "1"
  CORECLR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}"
  CORECLR_PROFILER_PATH = "$profilerHomeDir\elastic_apm_profiler.dll"
  ELASTIC_APM_PROFILER_HOME = "$profilerHomeDir"
  ELASTIC_APM_PROFILER_INTEGRATIONS = "$profilerHomeDir\integrations.yml"
  ELASTIC_APM_SERVER_URL = "<apm server url>"
  ELASTIC_APM_SECRET_TOKEN = "<secret token>"
}

$environment.Keys | ForEach-Object {
  & $appcmd set config -section:system.applicationHost/applicationPools /+"[name='$appPool'].environmentVariables.[name='$_',value='$($environment[$_])']"
}

1. <application-pool> 是您的应用程序使用的应用程序池的名称。例如，IIS APPPOOL\DefaultAppPool。
2. <unzipped directory> 是 zip 文件解压到的目录的完整路径。
3. 应将跟踪和指标发送到的 APM 服务器 intake URL。
4. APM Agent 用于向 APM 服务器进行身份验证的secret token。

设置环境变量后，停止并启动 IIS，以便托管在 IIS 中的应用程序能够看到新的环境变量。

net stop /y was
net start w3svc

可以通过创建包含以下内容的 environment.env 文件，将环境变量添加到使用 systemd 运行的特定服务：

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}
CORECLR_PROFILER_PATH=/<unzipped directory>/libelastic_apm_profiler.so
ELASTIC_APM_PROFILER_HOME=/<unzipped directory>
ELASTIC_APM_PROFILER_INTEGRATIONS=/<unzipped directory>/integrations.yml
ELASTIC_APM_SERVER_URL=<apm server url>
ELASTIC_APM_SECRET_TOKEN=<secret token>

1. <unzipped directory> 是 zip 文件解压到的目录。
2. 应将跟踪和指标发送到的 APM 服务器 intake URL。
3. APM Agent 用于向 APM 服务器进行身份验证的secret token。

然后，在服务的配置文件中添加一个 EnvironmentFile 条目，引用 environment.env 文件的路径：

[Service]
EnvironmentFile=/path/to/environment.env
ExecStart=<command>

1. 启动您的服务的命令

添加 EnvironmentFile 条目后，重新启动服务。

systemctl reload-or-restart <service>

profiler 自动检测有自己的一组环境变量来管理检测。这些变量除通过环境变量进行的agent 配置之外使用。

ELASTIC_APM_PROFILER_HOME

profiler 自动检测的主目录。主目录通常包含：

• 特定于平台的 profiler 程序集
• 每个兼容目标框架的目录，每个目录包含用于自动检测的支持托管程序集。
• 一个 integrations.yml 文件，用于确定要自动检测哪些方法

ELASTIC_APM_PROFILER_INTEGRATIONS (可选)

指向 integrations.yml 文件的路径，该文件确定要自动检测哪些方法。如果未指定，则 profiler 将假定 ELASTIC_APM_PROFILER_HOME 环境变量指定的主目录中存在 integrations.yml。

ELASTIC_APM_PROFILER_EXCLUDE_INTEGRATIONS (可选)

要从自动检测中排除的集成列表，以分号分隔。有效值是上面集成表中 Integration name 列中定义的值。

ELASTIC_APM_PROFILER_EXCLUDE_PROCESSES (可选)

要从自动检测中排除的进程名称列表，以分号分隔。例如，dotnet.exe;powershell.exe。可在 profiler 环境变量作用域为全局范围，从而导致不应自动检测的应用程序也被检测的场景中使用。

默认情况下，以下进程始终从 profiling 中排除。

• powershell.exe

• ServerManager.exe

• ReportingServicesService.exe

• RSHostingService.exe

• RSMananagement.exe

• RSPortal.exe

• RSConfigTool.exe

  ELASTIC_APM_PROFILER_EXCLUDE_SERVICE_NAMES (可选)

  要从自动检测中排除的 APM 服务名称列表，以分号分隔。定义的值将与 ELASTIC_APM_SERVICE_NAME 环境变量的值进行比对。

默认情况下，以下服务名称始终从 profiling 中排除。

• SQLServerReportingServices

  ELASTIC_OTEL_LOG_LEVEL (可选)

  profiler 应记录的日志级别。有效值有：

• trace

• debug

• info

• warn

• error

• 无

默认值为 warn。更详细的日志级别（如 trace 和 debug）可能会影响 profiler 自动检测的运行时性能，因此建议仅用于诊断目的。

此项优先于现已弃用的 ELASTIC_APM_PROFILER_LOG

ELASTIC_OTEL_LOG_DIRECTORY (可选)

用于写入 profiler 日志文件的目录。如果未设置，则默认为：

• Windows 上为 %PROGRAMDATA%\elastic\apm-agent-dotnet\logs
• Linux 上为 /var/log/elastic/apm-agent-dotnet

如果由于某种原因无法写入默认目录，profiler 将尝试将日志文件写入 ELASTIC_APM_PROFILER_HOME 环境变量指定的主目录中的 logs 目录。

此项优先于现已弃用的 ELASTIC_APM_PROFILER_LOG_DIR

ELASTIC_OTEL_LOG_TARGETS (可选)

profiler 日志的目标列表，以分号分隔。有效值有：

• file
• stdout

默认值为 file，它会将日志记录到 ELASTIC_APM_PROFILER_LOG_DIR 环境变量指定的目录。

此项优先于现已弃用的 ELASTIC_APM_PROFILER_LOG_TARGETS

如果 Windows 认为下载的 DLL 文件可疑，可能会自动阻止它们。

要在 Windows 上解除阻止 DLL 文件，您可以执行以下操作：

• 在文件资源管理器中右键单击 DLL 文件
• 选择“属性”
• 在“常规”选项卡中，查找底部的“安全”部分
• 勾选“解除阻止”复选框，然后单击“确定”