›

探查器自动检测

编辑

探查器自动检测

编辑

快速入门

编辑

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

此方法适用于以下情况

操作系统

架构

Windows

Linux **

x64

.NET Framework 4.6.2+*

.NET Core 2.1+

.NET 5+

.NET Core 2.1+

.NET 5+

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

** 最低 GLIBC 版本 2.14。

基于探查器的 Agent 仅支持 64 位应用程序。不支持 32 位应用程序。

基于探查器的 Agent 目前不支持 ARM。

它检测以下程序集

集成名称	NuGet 包版本	程序集版本
AdoNet	.NET 的一部分	System.Data 4.0.0 - 4..
AdoNet	.NET 的一部分	System.Data.Common 4.0.0 - 5..
AspNet	.NET Framework 的一部分	System.Web 4.0.0 - 4..
Kafka	Confluent.Kafka 1.4.0 - 1..	Confluent.Kafka 1.4.0 - 1..
MySqlCommand	MySql.Data 6.7.0 - 8..	MySql.Data 6.7.0 - 8..
NpgsqlCommand	Npgsql 4.0.0 - 7..	Npgsql 4.0.0 - 7..
OracleCommand	Oracle.ManagedDataAccess 12.2.1100 - 21..	Oracle.ManagedDataAccess 4.122.0 - 4.122.*
OracleCommand	Oracle.ManagedDataAccess.Core 2.0.0 - 3..	Oracle.ManagedDataAccess 2.0.0 - 3..
RabbitMQ	RabbitMQ.Client 3.6.9 - 6..	RabbitMQ.Client 3.6.9 - 6..
SqlCommand	.NET 的一部分	System.Data 4.0.0 - 4..
	System.Data.SqlClient 4.0.0 - 4..	System.Data.SqlClient 4.0.0 - 4..
	Microsoft.Data.SqlClient 1.0.0 - 5..	Microsoft.Data.SqlClient 1.0.0 - 5..
SqliteCommand	Microsoft.Data.Sqlite 2.0.0 - 7..	Microsoft.Data.Sqlite 2.0.0 - 7..
SqliteCommand	System.Data.SQLite 1.0.0 - 2..	System.Data.SQLite 1.0.0 - 2..

.NET CLR 探查 API 仅允许一个探查器附加到 .NET 进程。鉴于此限制，应用程序应仅使用一个使用 .NET CLR 探查 API 的解决方案。

使用 .NET CLR 探查 API 进行自动检测可以与

公共 API 结合使用以执行手动检测。
使用 IDiagnosticsSubscriber 订阅诊断事件来执行检测的 NuGet 包。

使用探查器检测的项目的 NuGet 包版本号必须与使用的探查器 zip 文件的版本号相同。

常规步骤

编辑

配置探查器自动检测的常规步骤如下；有关常见部署环境的配置，请参阅检测容器和服务。

从 .NET APM Agent GitHub 存储库的发布页面下载 elastic_apm_profiler_<version>.zip 文件，其中 <version> 是要下载的版本号。您可以在“资产”下找到该文件。
将 zip 文件解压缩到托管要检测应用程序的主机上的文件夹中。

配置以下环境变量

.NET Framework。

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>"

	`<unzipped directory>` 是步骤 2 中解压缩 zip 文件的目录。
	要发送跟踪和指标的 APM 服务器接收 URL。
	APM Agent 用于向 APM 服务器进行身份验证的密钥令牌。

.NET Core / .NET 5+（Windows）。

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>"

	`<unzipped directory>` 是步骤 2 中解压缩 zip 文件的目录。
	要发送跟踪和指标的 APM 服务器接收 URL。
	APM Agent 用于向 APM 服务器进行身份验证的密钥令牌。

.NET Core / .NET 5+（Linux）。

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>"

	`<unzipped directory>` 是步骤 2 中解压缩 zip 文件的目录。
	要发送跟踪和指标的 APM 服务器接收 URL。
	APM Agent 用于向 APM 服务器进行身份验证的密钥令牌。

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

通过此设置，.NET 运行时将 Elastic 的 CLR 探查器加载到 .NET 进程中，该进程在应用程序启动初期加载并实例化 APM Agent。探查器监视感兴趣的方法，并注入代码以检测其执行情况。

检测容器和服务

编辑

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

Docker 容器

编辑

包含探查器自动检测文件的构建映像可用作多阶段构建的一部分

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}

将 <VERSION> 替换为要下载的探查器 zip 文件的最新发行版版本号（例如 ARG AGENT_VERSION=1.26.0）。

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

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

可以将环境变量添加到 Dockerfile 以配置探查器自动检测

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"]

您还应考虑如何在运行容器时以安全的方式将 APM 服务器 URL 和密钥令牌作为环境变量提供。不建议将密钥令牌包含在映像中，因为它可能会意外泄露。

Windows 服务

编辑

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

.NET Framework 服务。

$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

.NET Core 服务。

$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

	`<unzipped directory>` 是解压缩 zip 文件的目录。
	要发送跟踪和指标的 APM 服务器接收 URL。
	APM Agent 用于向 APM 服务器进行身份验证的密钥令牌。
	`<service-name>` 是 Windows 服务的名称。

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

Restart-Service <service-name>

Internet Information Services (IIS)

编辑

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

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

.NET Framework。

$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[$_])']"
}

	`<application-pool>` 是应用程序使用的应用程序池的名称。例如，`IIS APPPOOL\DefaultAppPool`
	`<unzipped directory>` 是解压缩 zip 文件的目录的完整路径
	强制程序集不以域中立方式加载。目前存在一个限制，即当程序集以域中立方式加载时，探查器自动检测无法检测这些程序集。预计将在将来删除此限制，但目前可以通过设置此环境变量来解决此问题。请参阅 Microsoft 文档以了解更多详细信息。
	要发送跟踪和指标的 APM 服务器接收 URL。
	APM Agent 用于向 APM 服务器进行身份验证的密钥令牌。

.NET Core。

$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[$_])']"
}

	`<application-pool>` 是应用程序使用的应用程序池的名称。例如，`IIS APPPOOL\DefaultAppPool`。
	`<unzipped directory>` 是解压缩 zip 文件的目录的完整路径。
	要发送跟踪和指标的 APM 服务器接收 URL。
	APM Agent 用于向 APM 服务器进行身份验证的密钥令牌。

确保 <unzipped directory> 的位置对应用程序池运行的标识帐户可访问且可执行。

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

net stop /y was
net start w3svc

systemd / systemctl

编辑

可以通过创建一个包含以下内容的 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>

	`<unzipped directory>` 是解压缩 zip 文件的目录。
	要发送跟踪和指标的 APM 服务器接收 URL。
	APM Agent 用于向 APM 服务器进行身份验证的密钥令牌。

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

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

启动服务的命令

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

systemctl reload-or-restart <service>

探查器环境变量

编辑

探查器自动检测有一套自己的环境变量来管理检测。这些变量与通过环境变量进行的代理配置结合使用。

ELASTIC_APM_PROFILER_HOME

特定于平台的探查器程序集
每个兼容的目标框架的目录，其中每个目录都包含用于自动检测的支持托管程序集。
一个 integrations.yml 文件，用于确定要针对其进行自动检测的方法

ELASTIC_APM_PROFILER_INTEGRATIONS (可选)

集成文件 integrations.yml 的路径，用于确定要自动检测哪些方法。如果未指定，则探查器将假设 integrations.yml 存在于由 ELASTIC_APM_PROFILER_HOME 环境变量指定的 home 目录中。

ELASTIC_APM_PROFILER_EXCLUDE_INTEGRATIONS (可选)

要从自动检测中排除的集成的分号分隔列表。有效值为上表“集成名称”列中定义的值。

ELASTIC_APM_PROFILER_EXCLUDE_PROCESSES (可选)

要从自动检测中排除的进程名称的分号分隔列表。例如，dotnet.exe;powershell.exe。可用于探查器环境变量具有全局作用域，最终会自动检测不应检测的应用程序的场景。

默认情况下，以下进程始终被排除在探查之外。

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 环境变量的值进行检查。

默认情况下，以下服务名称始终被排除在探查之外。

SQLServerReportingServices

ELASTIC_OTEL_LOG_LEVEL (可选)

探查器应记录的日志级别。有效值为
trace
debug
info
warn
error
none

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

此选项优先于现已弃用的 ELASTIC_APM_PROFILER_LOG

ELASTIC_OTEL_LOG_DIRECTORY (可选)

写入探查器日志文件的目录。如果未设置，则默认为

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

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

此选项优先于现已弃用的 ELASTIC_APM_PROFILER_LOG_DIR

运行探查器进程的用户帐户必须具有写入目标日志目录的权限。具体来说，请确保在 IIS 上运行时，应用程序池标识在目标目录中具有写入权限。

ELASTIC_OTEL_LOG_TARGETS (可选)

探查器日志的目标的分号分隔列表。有效值为

file
stdout

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

此选项优先于现已弃用的 ELASTIC_APM_PROFILER_LOG_TARGETS

故障排除

编辑

Windows 上的 DLL 被阻止

编辑

如果 Windows 认为下载的 DLL 文件可疑，则会自动阻止这些文件。

要在 Windows 上取消阻止 DLL 文件，您可以执行以下操作

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

« 设置 Agent ASP.NET Core »

集成名称	NuGet 包版本	程序集版本
AdoNet	.NET 的一部分	System.Data 4.0.0 - 4..
AdoNet	.NET 的一部分	System.Data.Common 4.0.0 - 5..
AspNet	.NET Framework 的一部分	System.Web 4.0.0 - 4..
Kafka	Confluent.Kafka 1.4.0 - 1..	Confluent.Kafka 1.4.0 - 1..
MySqlCommand	MySql.Data 6.7.0 - 8..	MySql.Data 6.7.0 - 8..
NpgsqlCommand	Npgsql 4.0.0 - 7..	Npgsql 4.0.0 - 7..
OracleCommand	Oracle.ManagedDataAccess 12.2.1100 - 21..	Oracle.ManagedDataAccess 4.122.0 - 4.122.*
OracleCommand	Oracle.ManagedDataAccess.Core 2.0.0 - 3..	Oracle.ManagedDataAccess 2.0.0 - 3..
RabbitMQ	RabbitMQ.Client 3.6.9 - 6..	RabbitMQ.Client 3.6.9 - 6..
SqlCommand	.NET 的一部分	System.Data 4.0.0 - 4..
	System.Data.SqlClient 4.0.0 - 4..	System.Data.SqlClient 4.0.0 - 4..
	Microsoft.Data.SqlClient 1.0.0 - 5..	Microsoft.Data.SqlClient 1.0.0 - 5..
SqliteCommand	Microsoft.Data.Sqlite 2.0.0 - 7..	Microsoft.Data.Sqlite 2.0.0 - 7..
SqliteCommand	System.Data.SQLite 1.0.0 - 2..	System.Data.SQLite 1.0.0 - 2..