« 设置代理 ASP.NET Core »
Elastic 文档 › ›设置代理

探查器自动检测

编辑

探查器自动检测编辑

快速入门编辑

代理可以使用 .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 以获得最佳兼容性。

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

它检测以下程序集

集成名称 NuGet 包版本 程序集版本

AdoNet

.NET 的一部分

System.Data 4.0.0 - 4.*.*

.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 - 6.*.*

Npgsql 4.0.0 - 6.*.*

OracleCommand

Oracle.ManagedDataAccess 12.2.1100 - 21.*.*

Oracle.ManagedDataAccess 4.122.0 - 4.122.*

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.*.*

System.Data.SQLite 1.0.0 - 2.*.*

System.Data.SQLite 1.0.0 - 2.*.*

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

使用 .NET CLR 探查 API 的自动检测可以与以下内容结合使用

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

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

常规步骤编辑

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

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

  3. 配置以下环境变量

    .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> 是将 zip 文件解压缩到的目录（步骤 2）。

    要发送跟踪和指标的 APM 服务器接收的 URL。

    APM 代理用于向 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> 是将 zip 文件解压缩到的目录（步骤 2）。

    要发送跟踪和指标的 APM 服务器接收的 URL。

    APM 代理用于向 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> 是将 zip 文件解压缩到的目录（步骤 2）。

    要发送跟踪和指标的 APM 服务器接收的 URL。

    APM 代理用于向 APM 服务器进行身份验证的 密钥令牌。

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

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

检测容器和服务编辑

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

Docker 容器编辑

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

ARG AGENT_VERSION=1.19.0

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}

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

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 代理用于向 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 代理用于向 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 代理用于向 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 代理用于向 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 环境变量指定的主目录中。
ELASTIC_APM_PROFILER_EXCLUDE_INTEGRATIONS (可选)
要从自动检测中排除的集成列表，以分号分隔。有效值为上面集成表中 集成名称 列中定义的值。
ELASTIC_APM_PROFILER_EXCLUDE_PROCESSES (可选)
要从自动检测中排除的进程名称列表，以分号分隔。例如，dotnet.exe;powershell.exe。可以在性能分析器环境变量具有全局范围并最终自动检测不应检测的应用程序的场景中使用。
ELASTIC_APM_PROFILER_EXCLUDE_SERVICE_NAMES (可选)
要从自动检测中排除的 APM 服务名称列表，以分号分隔。定义的值将与 ELASTIC_APM_SERVICE_NAME 环境变量的值进行检查。
ELASTIC_APM_PROFILER_LOG (可选)

性能分析器应记录的日志级别。有效值为

  • 跟踪
  • 调试
  • 信息
  • 警告
  • 错误
  • 无

默认值为 警告。更详细的日志级别，如 跟踪 和 调试 会影响性能分析器自动检测的运行时性能，因此建议仅用于诊断目的。

ELASTIC_APM_PROFILER_LOG_DIR (可选)

写入性能分析器日志文件的目录。如果未设置，则默认为

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

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

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

ELASTIC_APM_PROFILER_LOG_TARGETS (可选)

性能分析器日志的目标列表，以分号分隔。有效值为

  • 文件
  • 标准输出

默认值为 文件，它记录到由 ELASTIC_APM_PROFILER_LOG_DIR 环境变量指定的目录。

« 设置代理 ASP.NET Core »