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

.NET Core 和 .NET 5+

编辑

.NET Core 和 .NET 5+

编辑

快速入门

编辑

在使用 Microsoft.Extensions.Hosting 的 .NET（Core）应用程序中，可以在 IServiceCollection 上注册代理。这适用于 ASP.NET Core 和依赖于托管 API 的其他 .NET 应用程序，例如使用 工作服务 模板创建的应用程序。

启用代理及其检测的最简单方法是引用 Elastic.Apm.NetCoreAll 包。

<PackageReference Include="Elastic.Apm.NetCoreAll" Version="<LATEST>" />

将 <LATEST> 占位符替换为 NuGet 上可用的最新代理版本。

以下代码示例假设使用 顶级语句 对 .NET 8 工作服务进行检测。

Program.cs

using WorkerServiceSample;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddHttpClient();
builder.Services.AddAllElasticApm(); 
builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();

在注册其他 IHostedServices 之前注册 Elastic APM，以确保其依赖项首先初始化。

使用 AddAllElasticApm() 注册服务时，将启用具有所有检测功能的 APM 代理。在 ASP.NET Core 上，它将自动捕获传入请求、通过受支持技术进行的数据库调用、传出的 HTTP 请求等。

对于其他应用程序模板（例如工作服务），您必须手动检测您的 BackgroundService 以识别应捕获的一个或多个工作单元。

使用 ITracer 进行手动检测

编辑

AddAllElasticApm 将 ITracer 添加到依赖项注入系统，可以在代码中使用它来手动检测应用程序，使用 公共 API

Worker.cs

using Elastic.Apm.Api;

namespace WorkerServiceSample
{
  public class Worker : BackgroundService
  {
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ITracer _tracer;

    public Worker(IHttpClientFactory httpClientFactory, ITracer tracer)
    {
      _httpClientFactory = httpClientFactory;
      _tracer = tracer;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
      while (!stoppingToken.IsCancellationRequested)
      {
        await _tracer.CaptureTransaction("UnitOfWork", ApiConstants.TypeApp, async () => 
        {
          var client = _httpClientFactory.CreateClient();
          await client.GetAsync("https://elastic.ac.cn", stoppingToken);
          await Task.Delay(5000, stoppingToken);
        });
      }
    }
  }
}

CaptureTransaction 方法创建一个名为 UnitOfWork 且类型为 App 的事务。传递给它的 lambda 表示应在事务上下文中捕获的工作单元。

当此应用程序运行时，将为每个 while 循环迭代捕获并发送一个新的事务。将在事务中为对 https://elastic.ac.cn 的 HTTP 请求创建一个名为 HTTP GET 的跨度。HTTP 跨度被捕获，因为 NetCoreAll 包会自动启用此检测功能。

使用 OpenTelemetry 进行手动检测

编辑

作为通过注入 ITracer 使用 Elastic APM API 的替代方法，可以使用 OpenTelemetry API 手动检测应用程序。Elastic APM 代理会自动桥接使用 OpenTelemetry API 创建的检测，因此可以使用它来创建跨度和事务。在 .NET 中，可以使用 Activity API 来检测应用程序。

在此示例工作服务的情况下，可以更新代码以优先使用 OpenTelemetry API。

Worker.cs

using System.Diagnostics;

namespace WorkerServiceSample
{
  public class Worker : BackgroundService
  {
    private readonly IHttpClientFactory _httpClientFactory;
    private static readonly ActivitySource ActivitySource = new("MyActivitySource"); 

    public Worker(IHttpClientFactory httpClientFactory)
    {
      _httpClientFactory = httpClientFactory;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
      while (!stoppingToken.IsCancellationRequested)
      {
        using var activity = ActivitySource.StartActivity("UnitOfWork"); 
        var client = _httpClientFactory.CreateClient();
        await client.GetAsync("https://elastic.ac.cn", stoppingToken);
        await Task.Delay(5000, stoppingToken);
      }
    }
  }
}

为该应用程序定义一个 ActivitySource，从中可以创建活动。

使用名称 UnitOfWork 启动一个 Activity。由于它是 IDisposable，因此在 while 块的每次迭代结束时都会自动结束。

检测模块

编辑

Elastic.Apm.NetCoreAll 包引用了可以自动配置的每个代理组件。这通常不是问题，但如果希望将依赖项保持最少，则可以改为引用 Elastic.Apm.Extensions.Hosting 包并使用 AddElasticApm 方法（而不是 AddAllElasticApm）注册服务。通过此设置，可以明确控制代理将侦听的内容。

以下示例仅打开传出 HTTP 监控（因此，例如，不会自动捕获数据库和 Elasticsearch 调用）

using Elastic.Apm.DiagnosticSource;
using WorkerServiceSample;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddHttpClient();
builder.Services.AddElasticApm(new HttpDiagnosticsSubscriber()); 
builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();

HttpDiagnosticsSubscriber 是一个诊断侦听器，用于捕获传出 HTTP 请求的跨度。

.NET Core 和 .NET 5+ 上的零代码更改设置（ [1.7] 在 1.7 中添加。 )

编辑

如果无法或不想在应用程序中引用 NuGet 包，则可以使用启动挂钩功能在启动期间注入代理，如果应用程序在 .NET Core 3.0、.NET Core 3.1 或 .NET 5 或更高版本上运行。

配置启动挂钩

  1. 从 .NET APM Agent GitHub 存储库的 发行版 页面下载 ElasticApmAgent_<version>.zip 文件。可以在“资产”下找到该文件。
  2. 将 zip 文件解压缩到一个文件夹中。

  3. 设置 DOTNET_STARTUP_HOOKS 环境变量以指向解压缩文件夹中的 ElasticApmAgentStartupHook.dll 文件

    set DOTNET_STARTUP_HOOKS=<path-to-agent>\ElasticApmAgentStartupHook.dll

    <path-to-agent> 是步骤 2 中解压缩的目录。
  4. 在 DOTNET_STARTUP_HOOKS 环境变量可见的环境中启动 .NET Core 应用程序。

通过此设置，代理将在启动期间注入到应用程序中，启用每个检测功能。在 ASP.NET Core 上将自动捕获传入请求（包括 gRPC）。

使用启动挂钩功能时，可以通过环境变量控制代理配置。

« ASP.NET Core ASP.NET »