前言
[使用 elastic 构建可观测性平台](#使用 elastic 构建可观测性平台)
[在 ASP.NET Core 应用中集成 OTel SDK](#在 ASP.NET Core 应用中集成 OTel SDK)
- 安装依赖
- 基础配置
- [Instrumentation 配置](#Instrumentation 配置)
- [创建自定义 Span 和 Metric](#创建自定义 Span 和 Metric)
- 完整的代码演示
- [kibana 中查看数据](#kibana 中查看数据)
  - Tracing
  - Metrics
  - [Tracing 和 Logs 的关联](#Tracing 和 Logs 的关联)

前言

本文将介绍如何在 ASP.NET Core 应用中集成 OTel SDK，并使用 elastic 构建可观测性平台展示 OTel 的数据。

本文只是使用 elastic 做基本的数据展示，详细的使用方式同学可以参考 elastic 的官方文档，后面也会介绍其他的对 OTel 支持较好的可观测性后端。

示例代码已经上传到了 github，地址为：
https://github.com/eventhorizon-cli/otel-demo

使用 elastic 构建可观测性平台

elastic 提供了一套完整的可观测性平台，并支持 OpenTelemetry protocol (OTLP) 协议。

elastic apm 部署相对比较复杂，如果有同学想在生产环境中使用，可以参考 elastic 的官方文档进行部署或直接购买 elastic cloud。

https://www.elastic.co/cn/blog/adding-free-and-open-elastic-apm-as-part-of-your-elastic-observability-deployment

为方便同学们学习，我准备好了一个 elastic 的 docker-compose 文件，包含了以下组件：

elasticsearch：用于存储数据
kibana：用于展示数据
apm-server：处理 OTel 的数据
fleet-server：用于管理 apm-agent，apm-agent 可以接收 OTLP 的数据，并将数据发送给 apm-server

docker-compose 文件已经上传到了 github，地址为：

https://github.com/eventhorizon-cli/otel-demo/blob/main/ElasticAPM/docker-compose.yml

docker-compose 启动的过程中可能会遇到部分容器启动失败的情况，可以手动重启这部分容器。

启动完成后，我们还需要一点配置，才能启用 apm-server。

打开 http://localhost:5601 ，进入 kibana 的管理界面，用户名 admin，密码是 changeme。

进入后会提示你添加集成。

点击 Add integrations，选择 APM。

然后一路确定，就可以了。

在 ASP.NET Core 应用中集成 OTel SDK

安装依赖

创建一个 ASP.NET Core 项目，然后安装以下依赖：

OpenTelemetry：OpenTelemetry 的核心库，包含了 OTel 的数据模型和 API。
OpenTelemetry.Extensions.Hosting：ASP.NET Core 的扩展，用于在 ASP.NET Core 应用中集成 OTel。
OpenTelemetry.Exporter.OpenTelemetryProtocol：OTel 的 OTLP exporter，用于将 OTel 的数据发送给可观测性后端。
OpenTelemetry.Exporter.OpenTelemetryProtocol.Logs：OTel Logs 的 OTLP exporter，用于将 OTel 的 Logs 数据发送给可观测性后端。

基础配置

在 Program.cs 中，我们需要添加以下代码：

csharp 复制代码

builder.Services.AddOpenTelemetry()
    // 这边配置的 Resource 是全局的，Log、Metric、Trace 都会使用这个 Resource
    .ConfigureResource(resourceBuilder =>
    {
        resourceBuilder
            .AddService("FooService", "TestNamespace", "1.0.0")
            .AddTelemetrySdk();
    })
    .WithTracing(tracerBuilder =>
    {
        tracerBuilder
            .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:8200"));
    }).WithMetrics(meterBuilder =>
    {
        meterBuilder
            .AddOtlpExporter(otlpOptions => otlpOptions.Endpoint = new Uri("http://localhost:8200"));
    });

builder.Services.AddLogging(loggingBuilder =>
{
    loggingBuilder.AddOpenTelemetry(options =>
    {
        options.IncludeFormattedMessage = true;
        options.AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:8200"));
    });
});

Instrumentation 配置

ASP.NET Core 以及 Entity Framework Core 等框架中有很多预置的埋点（通过 DiagnosticSource 实现），通过这些预置的埋点，我们可以收集到大量的数据，并借此创建出 Trace、Metric。

比如，通过 ASP.NET Core 中 HTTP 请求的埋点，可以创建出代表此次 HTTP 请求的 Span，并记录下各个 API 的耗时、请求频率等 Metrics。

下面我们在应用中添加两个 Instrumentation

OpenTelemetry.Instrumentation.AspNetCore：ASP.NET Core 的 Instrumentation
OpenTelemetry.Instrumentation.Http：HTTP 请求的 Instrumentation，如果想要跨进程传输 Baggage，也需要添加此 Instrumentation

csharp 复制代码

tracerBuilder
    // ASP.NET Core 的 Instrumentation
    .AddAspNetCoreInstrumentation(options =>
    {
        // 配置 Filter，忽略 swagger 的请求
        options.Filter =
            httpContent => httpContent.Request.Path.StartsWithSegments("/swagger") == false;
    })
    // HTTP 请求的 Instrumentation，如果想要跨进程传输 Baggage，也需要添加此 Instrumentation
    .AddHttpClientInstrumentation()
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:8200"));

csharp 复制代码

meterBuilder
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .AddOtlpExporter(otlpOptions => otlpOptions.Endpoint = new Uri("http://localhost:8200"));

除了上面介绍的两个两个 Instrumentation，OTel SDK 还提供了很多 Instrumentation，可以在下面的链接中查看：

https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src

https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src

创建自定义 Span 和 Metric

前一篇文章中，我们介绍了利用 ActivitySource 创建自定义Span 和利用 Meter 创建自定义Metric 的方法。

在 ASP.NET Core 中集成了 OTel SDK 后，我们可以将这些自定义的 Span 和 Metric 通过 OTel SDK 的 Exporter 发送给可观测性后端。

csharp 复制代码

tracerBuilder
    // 这边注册了 ActivitySource，OTel SDK 会去监听这个 ActivitySource 创建的 Activity
    .AddSource("FooActivitySource")
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:8200"));

csharp 复制代码

meterBuilder
    // 这边注册了 Meter，OTel SDK 会去监听这个 Meter 创建的 Metric
    .AddMeter("FooMeter")
    .AddOtlpExporter(otlpOptions => otlpOptions.Endpoint = new Uri("http://localhost:8200"));

完整的代码演示

下面我们创建两个 API 项目，一个叫做 FooService，一个叫做 BarService。两个服务都配置了 OTel SDK，其中 FooService 会调用 BarService。

FooService 的关键代码如下：

csharp 复制代码

builder.Services.AddHttpClient();
builder.Services.AddOpenTelemetry()
    // 这边配置的 Resource 是全局的，Log、Metric、Trace 都会使用这个 Resource
    .ConfigureResource(resourceBuilder =>
    {
        resourceBuilder
            .AddService("FooService", "TestNamespace", "1.0.0")
            .AddTelemetrySdk();
    })
    .WithTracing(tracerBuilder =>
    {
        tracerBuilder
            .AddAspNetCoreInstrumentation(options =>
            {
                // 配置 Filter，忽略 swagger 的请求
                options.Filter =
                    httpContent => httpContent.Request.Path.StartsWithSegments("/swagger") == false;
            })
            .AddHttpClientInstrumentation()
            .AddSource("FooActivitySource")
            .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:8200"));
    }).WithMetrics(meterBuilder =>
    {
        meterBuilder
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddMeter("FooMeter")
            .AddOtlpExporter(otlpOptions => otlpOptions.Endpoint = new Uri("http://localhost:8200"));
    });

builder.Services.AddLogging(loggingBuilder =>
{
    loggingBuilder.AddOpenTelemetry(options =>
    {
        options.IncludeFormattedMessage = true;
        options.AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:8200"));
    });
});

csharp 复制代码

[Route("/api/[controller]")]
public class FooController : ControllerBase
{
    private static readonly ActivitySource FooActivitySource
        = new ActivitySource("FooActivitySource");
    private static readonly Counter<int> FooCounter
        = new Meter("FooMeter").CreateCounter<int>("FooCounter");

    private readonly IHttpClientFactory _clientFactory;
    private readonly ILogger<FooController> _logger;

    public FooController(
        IHttpClientFactory clientFactory,
        ILogger<FooController> logger)
    {
        _clientFactory = clientFactory;
        _logger = logger;
    }
    [HttpGet]
    public async Task<IActionResult> Get()
    {
        _logger.LogInformation("/api/foo called");

        Baggage.SetBaggage("FooBaggage1", "FooValue1");
        Baggage.SetBaggage("FooBaggage2", "FooValue2");

        var client = _clientFactory.CreateClient();
        var result = await client.GetStringAsync("http://localhost:5002/api/bar");

        using var activity = FooActivitySource.StartActivity("FooActivity");
        activity?.AddTag("FooTag", "FooValue");
        activity?.AddEvent(new ActivityEvent("FooEvent"));
        await Task.Delay(100);

        FooCounter.Add(1);

        return Ok(result);
    }
}

BarService 的关键代码如下：

csharp 复制代码

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resourceBuilder =>
    {
        resourceBuilder
            .AddService("BarService", "TestNamespace", "1.0.0")
            .AddTelemetrySdk();
    })
    .WithTracing(options =>
    {
        options
            .AddAspNetCoreInstrumentation(options =>
            {
                // 配置 Filter，忽略 swagger 的请求
                options.Filter =
                    httpContent => httpContent.Request.Path.StartsWithSegments("/swagger") == false;
            })
            .AddHttpClientInstrumentation()
            .AddOtlpExporter(otlpOptions => otlpOptions.Endpoint = new Uri("http://localhost:8200"));
    }).WithMetrics(options =>
    {
        options
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddOtlpExporter(otlpOptions => otlpOptions.Endpoint = new Uri("http://localhost:8200"));
    });

builder.Services.AddLogging(loggingBuilder =>   
{
    loggingBuilder.AddOpenTelemetry(options =>
    {
        options.IncludeFormattedMessage = true;
        options.AddOtlpExporter(otlpOptions => otlpOptions.Endpoint = new Uri("http://localhost:8200"));
    });
});

csharp 复制代码

[Route("/api/[controller]")]
public class BarController : ControllerBase
{
    private readonly ILogger<BarController> _logger;

    public BarController(ILogger<BarController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public async Task<string> Get()
    {
        _logger.LogInformation("/api/bar called");

        var baggage1 = Baggage.GetBaggage("FooBaggage1");
        var baggage2 = Baggage.GetBaggage("FooBaggage2");
        
        _logger.LogInformation($"FooBaggage1: {baggage1}, FooBaggage2: {baggage2}");

        return "Hello from Bar";
    }
}