.NET 中使用 OpenTelemetry Traces 追踪应用程序

上一次我们讲了 OpenTelemetry Logs。今天继续来说说 OpenTelemetry Traces。
在今天的微服务和云原生环境中，理解和监控系统的行为变得越来越重要。在当下我们实现一个功能可能需要调用了 N 个方法，涉及到 N 个服务。方法之间的调用如蜘蛛网一样。分布式追踪这个时候就至关重要。它可以把我们程序的调用链可视化。这对于运维人员监控程序状态，开发人员 trouble shooting 都非常用帮助。

什么是 OpenTelemetry Traces#

OpenTelemetry Traces 是 OpenTelemetry 提供的一种遥测数据类型，用于记录和描述在分布式系统中的单个操作或工作单元的生命周期。
在 OpenTelemetry 中，一个 Trace 可以被视为由一系列相关的事件组成的时间线，这些事件被称为 Spans。每个 Span 可以包含多个属性、注释和事件，用于描述在该 Span 的生命周期中发生的特定操作或事件。
例如，一个 HTTP 请求可以被表示为一个 Span，其中包含了请求的开始时间、结束时间、HTTP 方法、URL、状态码等信息。如果这个请求还调用了其他的服务或数据库，那么这些调用也可以被表示为与原始请求 Span 相关联的子 Span。

注意：Span 是 OpenTelemetry 定义的概念，在 .NET 中使用 Activity 表示一个 Span。

以上的话呢比较官方，是我用 chatGPT 生成的。还是直接用代码来演示一下效果大家好理解。

示例：追踪 Http 与 Database#

在日常的开发活动中，http 与 database 操作基本就是涵盖了 99% 的场景。很多时候我们希望监控应用程序对每个请求的响应速度，以及其中数据库操作的耗时。这是一个非常非常常见的需求。以下使用一个用户登录接口来演示。

安装依赖#

	<PackageReference Include="Npgsql" Version="8.0.3" />
	<PackageReference Include="Npgsql.OpenTelemetry" Version="8.0.3" />
	<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.8.1" />
	<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.8.1" />
	<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.8.1" />

使用 nuget 安装以上包。

注入服务#

var otel = builder.Services.AddOpenTelemetry();

// Configure OpenTelemetry Resources with the application name
otel.ConfigureResource(resource => resource
    .AddService(builder.Environment.ApplicationName));


otel.WithTracing(tracing =>
{
    tracing
    .AddAspNetCoreInstrumentation()
    .AddNpgsql()
    .AddOtlpExporter(otlpOptions =>
    {
        otlpOptions.Protocol = OtlpExportProtocol.HttpProtobuf;
        otlpOptions.Endpoint = new Uri("http://192.168.0.1:5341/ingest/otlp/v1/traces");
    });
});

跟 Logs 类似，我们使用 WithTracing 扩展方法来对 Traces 进行配置。

• 调用 AddAspNetCoreInstrumentation 方法来添加对 AspNetCore 框架的跟踪支持。这将自动跟踪应用程序中的HTTP请求和响应，并生成相应的跟踪数据。
• 调用 AddNpgsql 方法来添加对 Npgsql 库的跟踪支持。这将自动跟踪应用程序中使用 Npgsql 库进行的数据库操作，并生成相应的跟踪数据。
• 我们调用 AddOtlpExporter 方法来添加一个 OTLP（OpenTelemetry Protocol）导出器。这个导出器将把跟踪数据发送到指定的 OTLP 接收端。在这里，我们将跟踪数据发送到"http://192.168.0.201:5341/ingest/otlp/v1/traces"这个地址。

登录代码#

public class UserRepository
{
    private readonly string _connectionString = "Host=127.0.0.1;Username=postgres;Password=123456";

    public async Task GetUserAsync(string username, string password)
    {
        using var conn = new NpgsqlConnection(_connectionString);
        conn.Open();

        using var cmd = new NpgsqlCommand("SELECT * FROM t_users WHERE username = @username AND password = @password", conn);
        cmd.Parameters.AddWithValue("username", username);
        cmd.Parameters.AddWithValue("password", password);

        using var reader = await cmd.ExecuteReaderAsync();
        if (reader.Read())
        {
            return new User
            {
                Id = reader.GetString(0),
                Username = reader.GetString(1),
                Password = reader.GetString(2),
                // 其他字段...
            };
        }

        return null;
    }
}

public class User
{
    public string Id { get; set; }
    public string Username { get; set; }
    public string Password { get; set; }
    // 其他字段...
}

    [HttpPost]
    public async Task<string> Login([FromBody] LoginModel model)
    {
        var user = await new UserRepository().GetUserAsync(model.Username, model.Password);
        if (user != null)
        {
            return "ok";
        }

        return "error";
    }

平平无奇的代码，简单演示一下用用户名密码进行登录。在这里我想指出的一个点是：

其中并没有任何 Trace 的代码会侵入到我们的业务中。

在 Seq 中查看 Trace#

以上就是所有的关键代码。让我们运行程序使用 postman 调用登录接口。打开 Seq 界面进行查看。

Trace 的信息已经到了 Seq 里。可以看到整个 POST Account 接口耗时 326ms，其中 postgres 耗时 42 ms。点击每一行都有更详细的属性。比如 postgres 里包含了 connection string，sql statement 等非常有用的信息。

示例：自定义 Trace 内容#

以上示例能是使用现成的库进行 Trace。虽然绝大多数情况下已经够用了。但是有的时候我们想更加详细的对我们的程序进行追踪，那么就需要自己来定义 Span（Activity）来实现了。以下就让我们通过一个获取天气的接口来演示如何自定义 Activity。

添加 Trace 的 source#

otel.WithTracing(tracing =>
{
    tracing
    .AddSource("MyTraceSample")
    ....
});

编写接口#

    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private readonly ILogger _logger;
        private readonly  ActivitySource _source;
        public WeatherForecastController(ILogger logger)
        {
            _logger = logger;
            _source = new ActivitySource("MyTraceSample", "1.0.0");
        }

        [HttpGet]
        public async Task<string> Get([FromQuery]string city)
        {
            _logger.LogInformation("Hello WeatherForecast");

            using (var activity = _source.StartActivity("CallWeatherForecast")) {

                activity?.AddTag("city", city);

                await Task.Delay(100);

                await GetWeatherInfoFromWebservice();

                await FormatWeatherInfo();
            }

            return "24°c";
        }

        async Task GetWeatherInfoFromWebservice()
        {
            using (var activity = _source.StartActivity("GetWeatherInfoFromWebservice"))
            {
                await Task.Delay(200);
            }
        }

        async Task FormatWeatherInfo()
        {
            using (var activity = _source.StartActivity("FormatWeatherInfo"))
            {
                await Task.Delay(300);
            }
        }
    }

在 Controller 的 Get 方法可以接受一个 city 的参数，然后调用 GetWeatherInfoFromWebservice 模拟从其他服务获取数据，再调用 FormatWeatherInfo 方法来模拟对获取的天气数据进行格式化。每个方法中都加入了 Task.Delay 来模拟耗时。
首先我们会实例化一个 ActivitySource。然后在每个需要追踪的方法最顶上调用 _source.StartActivity 得到一个 Activity 实例。这时候 Activity 就开始计时了。但是为啥没有 Stop 呢？
显然是 using 帮我们调用了。 以上代码可能对业务代码侵入的比较严重，那么可以使用 AOP 技术进行解耦。这里就不展开了。

在 Seq 中查看自定义的 Trace#

运行程序，使用 postman 进行调用。然后打开 Seq 界面查看 Trace。

通过以上图片可以清晰看到：GET WeatherForecast 接口调用了 CallWeatherForecast ， CallWeatherForecast 又调用了 GetWeatherInfoFromWebservice 与 FormatWeatherInfo。以及这些方法与整个 http 请求的耗时。可以说是非常非常直观。

点击 CallWeatherForecast 这一行，还可以看到我们设置的 tag 的内容。

总结#

以上我们可以看到如果你想对 http 接口以及 database 操作进行追踪，只需要简单的几行代码就可以完成而且全程无侵入。如果你想对程序进行更细致的追踪还可以使用自定义的 Activity 进行扩展，整个过程也毫无难度。希望这篇内容对想要学习 .NET 程序可观测的同学有所帮助。

关注我的公众号一起玩转技术#