Observability：使用 OpenTelemetry 手动检测 .NET 应用程序

作者：David Hope

在快节奏的软件开发领域，尤其是在云原生领域，DevOps 和 SRE 团队日益成为应用程序稳定性和增长的重要合作伙伴。

DevOps 工程师不断优化软件交付，而 SRE 团队则充当应用程序可靠性、可扩展性和顶级性能的管理者。 挑战？ 这些团队需要一种尖端的可观察性解决方案，该解决方案包含全栈洞察，使他们能够在潜在的干扰最终导致运营挑战之前快速管理、监控和纠正它们。

现代分布式软件生态系统中的可观察性不仅仅是监控 —— 它需要无限的数据收集、处理的精确性以及将这些数据与可操作的见解相关联。 然而，实现这一整体视图的道路充满了障碍，从解决版本不兼容性到与限制性专有代码作斗争。

OpenTelemetry (OTel) 将为采用它的用户带来以下好处：

• 通过 OTel 摆脱供应商限制，将自己从供应商锁定中解放出来，并确保一流的可观察性。
• 查看统一日志、指标和跟踪的和谐统一，以提供完整的系统视图。
• 通过更丰富和增强的工具来改善你的应用程序监督。
• 利用向后兼容性的优势来保护你之前的检测投资。
• 通过简单的学习曲线踏上 OpenTelemetry 之旅，简化入门和可扩展性。
• 依靠经过验证的、面向未来的标准来增强你对每项投资的信心。
• 探索手动仪器，实现定制数据收集以满足你的独特需求。
• 使用标准化的可观测性数据框架确保跨层监控的一致性。
• 将开发与运营脱钩，从而提高两者的最高效率。

在这篇文章中，我们将深入探讨使用 Docker 手动检测 .NET 应用程序的方法。

这篇文章涵盖什么？

• 手动检测 .NET 应用程序
• 使用内置的 OpenTelemetry 工具为 .NET 应用程序创建 Docker 映像
• 安装并运行 OpenTelemetry .NET Profiler 以进行自动检测

先决条件

1. 了解 Docker 和 .NET
2. Elastic Cloud
3. Docker 安装在你的计算机上（我们推荐 docker 桌面版）

查看示例源代码

完整的源代码，包括本博客中使用的 Dockerfile，可以在 GitHub 上找到。 该存储库还包含相同的应用程序，但没有检测。 这使你可以比较每个文件并查看差异。

以下步骤将向你展示如何检测此应用程序并在命令行或 Docker 中运行它。 如果你对更完整的 OTel 示例感兴趣，请查看此处的 docker-compose 文件，它将显示完整的项目。

分步指南

本博客假设你有 Elastic Cloud 帐户 - 如果没有，请按照说明开始使用 Elastic Cloud。

步骤 1. 开始使用

在我们的演示中，我们将手动检测 .NET Core 应用程序 - 登录。 该应用程序模拟一个简单的用户登录服务。 在此示例中，我们仅关注跟踪，因为 OpenTelemetry 日志记录工具目前处于混合成熟度，如此处所述。

该应用程序具有以下文件：

1. 程序.cs
2. 启动.cs
3. 遥测.cs
4. 登录控制器.cs

步骤 2. 检测应用程序

当谈到 OpenTelemetry 时，.NET 生态系统呈现出一些独特的方面。 虽然 OpenTelemetry 提供其 API，但 .NET 利用其原生 System.Diagnostics API 来实现 OpenTelemetry 的跟踪 API。 ActivitySource 和 Activity 等预先存在的构造被适当地重新调整用途以符合 OpenTelemetry。

也就是说，了解 OpenTelemetry API 及其术语对于 .NET 开发人员仍然至关重要。 它对于获得对应用程序检测的完全控制至关重要，并且正如我们所见，它还扩展到理解 System.Diagnostics API 的元素。

对于那些可能倾向于使用原始 OpenTelemetry API 而不是 System.Diagnostics API 的人来说，还有一种方法。 OpenTelemetry 提供了一个可供你使用的用于跟踪的 API 填充程序。 它使开发人员能够切换到 OpenTelemetry API，你可以在 OpenTelemetry API Shim 文档中找到有关它的更多详细信息。

通过将此类实践集成到 .NET 应用程序中，你可以充分利用 OpenTelemetry 提供的强大功能，无论你使用的是 OpenTelemetry 的 API 还是 System.Diagnostics API。

在本博客中，我们坚持使用默认方法并使用 System.Diagnostics API 规定的 activity 约定。

要手动检测 .NET 应用程序，你需要对每个文件进行更改。 我们来一一看看这些变化。

Program.cs

这是我们应用程序的入口点。 在这里，我们使用默认配置创建 IHostBuilder 的实例。 请注意我们如何使用 Serilog 设置控制台记录器。

public static void Main(string[] args)
{
    Log.Logger = new LoggerConfiguration().WriteTo.Console().CreateLogger();
    CreateHostBuilder(args).Build().Run();
}

Startup.cs

在 Startup.cs 文件中，我们使用 ConfigureServices 方法添加 OpenTelemetry Tracing。

public void ConfigureServices(IServiceCollection services)
{
    services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter()
        .AddSource("Login")
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter()  
        .ConfigureResource(resource =>
            resource.AddService(
                serviceName: "Login"))
    );
    services.AddControllers();
}

WithTracing 方法支持在 OpenTelemetry 中进行跟踪。 我们添加了 OTLP（OpenTelemetry Protocol）导出器，它是一种通用遥测数据传输协议。 我们还添加了 AspNetCoreInstrumentation，它将自动从我们的应用程序收集跟踪。 这是 OpenTelemetry 文档中未提及的极其重要的步骤。 如果不添加此方法，则仪器无法为我的登录应用程序工作。

Telemetry.cs

该文件包含我们的 ActivitySource 的定义。 ActivitySource 表示遥测活动的来源。 它以你的应用程序的服务名称命名，该名称可以来自配置文件、常量文件等。我们可以使用此 ActivitySource 来启动活动。

using System.Diagnostics;

public static class Telemetry
{
    //...

    // Name it after the service name for your app.
    // It can come from a config file, constants file, etc.
    public static readonly ActivitySource LoginActivitySource = new("Login");

    //...
}

在我们的例子中，我们创建了一个名为 Login 的 ActivitySource。 在我们的 LoginController.cs 中，当我们开始操作时，我们使用此 LoginActivitySource 来启动一个新 activity。

using (Activity activity = Telemetry.LoginActivitySource.StartActivity("SomeWork"))
{
    // Perform operations here
}

这段代码启动一个名为 SomeWork 的新 activity，执行一些操作（在本例中，生成随机用户并登录），然后结束该活动。 这些活动可以被跟踪并在以后进行分析以了解操作的性能。

此 ActivitySource 是 OpenTelemetry 手动检测的基础。 它代表活动的来源并提供启动和停止 activity 的方法。

LoginController.cs

在 LoginController.cs 文件中，我们跟踪 GET 和 POST 方法执行的操作。 我们在开始操作之前启动一项新活动 SomeWork，并在完成后将其处理掉。

using (Activity activity = Telemetry.LoginActivitySource.StartActivity("SomeWork"))
{
    var user = GenerateRandomUserResponse();
    Log.Information("User logged in: {UserName}", user);
    return user;
}

这将跟踪这些操作所花费的时间，并通过 OTLP 导出器将此数据发送到任何配置的遥测后端。

步骤 3. 基础镜像设置

现在我们已经创建并检测了应用程序源代码，是时候创建一个 Dockerfile 来构建和运行我们的 .NET 登录服务了。

从 Dockerfile 基础层的 .NET 运行时映像开始：

FROM ${ARCH}mcr.microsoft.com/dotnet/aspnet:7.0. AS base
WORKDIR /app
EXPOSE 8000

在这里，我们正在设置应用程序的运行时环境。

步骤 4. 构建 .NET 应用程序

Docker 的这个特性是最好的。 在这里，我们编译 .NET 应用程序。 我们将使用 SDK 映像。 在过去的糟糕日子里，我们曾经在不同的平台上构建，然后将编译后的代码放入 Docker 容器中。 这样，我们更有信心通过使用 Docker 来将我们的构建从开发人员桌面复制到生产中。

FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:8.0-preview AS build
ARG TARGETPLATFORM

WORKDIR /src
COPY ["login.csproj", "./"]
RUN dotnet restore "./login.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "login.csproj" -c Release -o /app/build

本节确保我们的 .NET 代码得到正确恢复和编译。

步骤 5. 发布应用程序

构建完成后，我们将发布该应用程序：

FROM build AS publish
RUN dotnet publish "login.csproj" -c Release -o /app/publish

步骤 6. 准备最终镜像

现在，让我们设置最终的运行时映像：

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .

步骤 7. 入口点设置

最后，将 Docker 映像的入口点设置为 OpenTelemetry 工具的源，这会设置引导 .NET Profiler 所需的环境变量，然后启动 .NET 应用程序：

ENTRYPOINT ["/bin/bash", "-c", "dotnet login.dll"]

步骤 8. 使用环境变量运行 Docker 镜像

要构建并运行 Docker 映像，你通常需要执行以下步骤：

构建 Docker 镜像

首先，你需要从 Dockerfile 构建 Docker 映像。 假设 Dockerfile 位于当前目录中，并且你想要命名/标记你的映像 dotnet-login-otel-image。

docker build -t dotnet-login-otel-image .

运行 Docker 镜像

构建镜像后，你可以使用指定的环境变量运行它。 为此，将 docker run 命令与每个环境变量的 -e 标志一起使用。

  docker run \
       -e OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ELASTIC_APM_SECRET_TOKEN}" \
       -e OTEL_EXPORTER_OTLP_ENDPOINT="${ELASTIC_APM_SERVER_URL}" \
       -e OTEL_METRICS_EXPORTER="otlp" \
       -e OTEL_RESOURCE_ATTRIBUTES="service.version=1.0,deployment.environment=production" \
       -e OTEL_SERVICE_NAME="dotnet-login-otel-manual" \
       -e OTEL_TRACES_EXPORTER="otlp" \
       dotnet-login-otel-image

确保在 shell 环境中设置 ${ELASTIC_APM_SECRET_TOKEN} 和 ${ELASTIC_APM_SERVER_URL}，将它们替换为来自云的实际值，如下所示。

获取 Elastic Cloud 变量

你可以从 Kibana 的路径 “/app/home#/tutorial/apm” 下复制端点和令牌。

如果你有多个环境变量，你还可以将环境文件与 docker run --env-file 一起使用，以使命令更加简洁。

启动并运行此程序后，你可以 ping 检测服务的端点（在我们的示例中为 /login），你应该会看到该应用程序出现在 Elastic APM 中，如下所示：

它将首先跟踪 SRE 需要关注的吞吐量和延迟关键指标。

深入研究，我们可以看到所有交易的概述。

看看具体的 transactions，包括我们在上面的代码中创建的 “SomeWork” activity/span：

这里显然有一个异常值，一笔交易花费了 20 毫秒以上。 这可能是由于 CLR 预热所致。

总结一下

通过此处的代码检测和 Dockerfile 引导应用程序，你已将简单的 .NET 应用程序转换为使用 OpenTelemetry 检测的应用程序。 这将极大地有助于了解应用程序性能、跟踪错误以及深入了解用户如何与软件交互。

请记住，可观察性是现代应用程序开发的一个重要方面，尤其是在分布式系统中。 借助 OpenTelemetry 等工具，理解复杂系统变得更加容易。

在这篇博客中，我们讨论了以下内容：

• 如何使用 OpenTelemetry 手动检测 .NET。
• 使用 Docker 文件中的标准命令，构建并启动了我们的检测应用程序。
• 使用 OpenTelemetry 及其对多种语言的支持，DevOps 和 SRE 团队可以轻松地检测其应用程序，立即了解整个应用程序堆栈的运行状况并缩短平均解决时间 (MTTR)。

由于 Elastic 可以支持多种提取数据的方法，无论是使用开源 OpenTelemetry 的自动检测还是使用其本机 APM 代理进行手动检测，因此你可以先关注一些应用程序，然后使用 OpenTelemety 来规划向 OTel 的迁移 稍后以最适合你的业务需求的方式跨你的应用程序。

还没有 Elastic Cloud 帐户？ 注册 Elastic Cloud 并尝试我上面讨论的检测功能。 我很想了解你对使用 Elastic 了解应用程序堆栈的体验的反馈。

本文中描述的任何特性或功能的发布和时间安排均由 Elastic 自行决定。 当前不可用的任何特性或功能可能无法按时交付或根本无法交付。