使用 OpenTelemetry 構建 .NET 應用可觀測性（3）：.NET SDK 概覽

黑洞視界發表於2023-09-25

前言

本文將介紹 OpenTelemetry .NET SDK 核心元件的設計和使用，主要是為後續給大家介紹如何在 ASP.NET Core 應用程式中使用 OpenTelemetry 做鋪墊。

為方便演示，本文使用的 Exporter 都是 Console Exporter，將資料輸出到控制檯。

概覽

我們在 OpenTelemetry 的 GitHub 倉庫中搜尋 dotnet，可以看到有三個倉庫：

https://github.com/open-telemetry?q=dotnet&type=all&language=&sort=

opentelemetry-dotnet

OTel SDK 的核心庫，主要包括以下幾個部分：

Logging, Metrics, Tracing 等核心元件
ASP.NET Core 相關的常用 Instrumentation，如 AspNetCore、HttpClient、GrpcNetClient、SqlClient 等。
Console、Zipkin、Prometheus 等常用 Exporter
依賴注入的擴充套件，用於在應用中快速整合 OTel

opentelemetry-dotnet-contrib

第三方貢獻的 Instrumentation 和 Exporter，比如 InfluxDB、Elasticsearch、AWS 等

opentelemetry-dotnet-instrumentation

無侵入的 Instrumentation，用於在不修改程式碼的情況下，自動收集資料。

SDK 的基本使用

本文只介紹 OTel SDK 的基本使用，下面將建立一個 Console 應用程式，演示如何使用 OTel SDK。

安裝依賴

建立一個 .NET Core Console 應用程式，然後安裝下列依賴：

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.Console

本文測試使用的是 1.6.0 版本，後期 OTel SDK 的版本可能會有所變化。

Resources

Resource 是 OTel 中的一個重要概念，用於標識應用程式的一些後設資料，比如應用程式的名稱、版本、執行環境等。
Resource 的資訊會被新增到 Log、Span、Metric 等資料中，用於後續的查詢和分析。

Resource 由 ResourceBuilder 構建，ResourceBuilder 有兩個方法：

ResourceBuilder.CreateDefault()

ResourceBuilder.CreateDefault()：建立一個預設的 Resource，包含以下Attribute：

ServiceName：應用程式的名稱，可以透過 OTEL_SERVICE_NAME 環境變數設定。
自定義的Attribute：可以透過 OTEL_RESOURCE_ATTRIBUTES 環境變數設定，格式為 key1=value1,key2=value2
OTel SDK 的資訊：包括 OTel SDK 的名稱、版本、語言等。

Environment.SetEnvironmentVariable("OTEL_SERVICE_NAME", "FooService");
// 可以直接在 OTEL_RESOURCE_ATTRIBUTES 中指定 service.name, 這樣就不需要再指定 OTEL_SERVICE_NAME 了
Environment.SetEnvironmentVariable("OTEL_RESOURCE_ATTRIBUTES", "service.version=1.0.0,service.namespace=TestNamespace");

Resource resource = ResourceBuilder
    .CreateDefault()
    .Build();

foreach (var attribute in resource.Attributes)
{
    Console.WriteLine($"{attribute.Key}={attribute.Value}");
}

輸出：

service.name=FooService
service.version=1.0.0
service.namespace=TestNamespace
telemetry.sdk.name=opentelemetry
telemetry.sdk.language=dotnet
telemetry.sdk.version=1.6.0

ResourceBuilder.CreateEmpty()

ResourceBuilder.CreateEmpty()：建立一個空的 Resource，可以按需求新增Attribute。

Environment.SetEnvironmentVariable("OTEL_RESOURCE_ATTRIBUTES", "test.attribute=foo");

Resource resource = ResourceBuilder
    .CreateDefault()
    .AddService("FooService", "TestNamespace", "1.0.0")
    .AddTelemetrySdk()
    .AddEnvironmentVariableDetector() // 可以識別 OTEL_RESOURCE_ATTRIBUTES 環境變數
    .Build();

foreach (var attribute in resource.Attributes)
{
    Console.WriteLine($"{attribute.Key} = {attribute.Value}");
}

輸出：

test.attribute = foo
telemetry.sdk.name = opentelemetry
telemetry.sdk.language = dotnet
telemetry.sdk.version = 1.6.0
service.name = FooService
service.namespace = TestNamespace
service.version = 1.0.0
service.instance.id = 15ff37f1-5791-4afe-b130-cb947b895af3

Tracing

ActivitySource & Activity

有別於其他語言的 SDK，.NET SDK 的 Tracing 模組是透過 ActivitySource 實現的。

ActivitySource 的 API 和 OpenTelemetry 的 API 基本是一一對應的。

透過 ActivitySource.StartActivity() 建立的 Activity 對應 OTel 中的 Span，可以被 OTel SDK 的 Tracing 模組收集。

Activity 是 NET 以前就有的類，OTel 標準出來後，.NET 對 Activity 做了一些擴充套件，使其可以和 OTel 中的 Span 一一對應。

System.Diagnostics.ActivitySource 是 .NET Runtime 的一部分，如果編寫的程式碼僅僅是一個收集資料的元件，可以直接使用 System.Diagnostics.ActivitySource，不需要引入 OpenTelemetry 的依賴。

ActivitySource 本質是 System.Diagnostics 名稱空間裡一個釋出/訂閱模式的工具。

ActivitySource.AddActivityListener(new ActivityListener
{
    // 只監聽 TestSource1
    ShouldListenTo = source => source.Name == "TestSource1",
    // 取樣率為 100%
    Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllDataAndRecorded,
    // 監聽 Activity 的開始和結束
    ActivityStarted = activity =>
    {
        Console.WriteLine($"Activity started: {activity.OperationName}");
    },
    ActivityStopped = activity =>
    {
        Console.WriteLine($"Activity stopped: {activity.OperationName}");
    }
});

using var activitySource1 = new ActivitySource("TestSource1");
using var activitySource2 = new ActivitySource("TestSource2");

using var activity1 = activitySource1.StartActivity("Activity1");
Console.WriteLine($"Activity1 created: {activity1 != null}");
// 如果設定 Listener，ActivitySource 將不會建立 Activity，StartActivity 返回 null
activity1?.SetTag("foo", 1);

using var activity2 = activitySource2.StartActivity("Activity2");
Console.WriteLine($"Activity2 created: {activity2 != null}");
activity2?.SetTag("bar", "Hello, World!");

輸出：

Activity started: Activity1
Activity1 created: True
Activity2 created: False
Activity stopped: Activity1

ActivitySource 可以透過 Name 來關聯 ActivityListener，只有 ActivityListener 的 ShouldListenTo 返回 true 的 ActivitySource 才會被監聽。

在上面的例子中，我們透過 ActivitySource.StartActivity() 建立了兩個 Activity，但是隻有一個 Activity 被監聽到，這是因為我們設定了 ShouldListenTo，只監聽 TestSource1。

如果沒有設定 ActivityListener，ActivitySource.StartActivity() 將返回 null。

所以推薦使用 ActivitySource.StartActivity() 建立的 Activity 時，使用?.運算子來避免空指標異常。

Tracing 模組的使用

而 OpenTelemetry SDK 的 Tracing 模組，其實就是一個 ActivityListener 的實現。

在使用 OTel 的 Tracing 模組時，我們需要透過 TracerProvider.AddSource() 告訴 OTel SDK 實現的 ActivityListener 需要監聽哪些 ActivitySource。

var serviceName = "MyCompany.MyProduct.MyService";
var serviceVersion = "1.0.0";

var resourceBuilder = ResourceBuilder.CreateDefault()
    .AddService(serviceName: serviceName, serviceVersion: serviceVersion);

// 建立 Span 是透過 ActivitySource.StartActivity() 實現的，
// 所以這邊的 tracerProvider 不會被使用
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("TestSource1")
    .AddSource("TestSource2")
    .AddConsoleExporter()
    .Build();

using var activitySource1 = new ActivitySource("TestSource1");
using var activitySource2 = new ActivitySource("TestSource2");

using (var activity1 = activitySource1.StartActivity("Activity1"))
{
    activity1?.SetTag("foo", 1);
    activity1?.SetTag("bar", "Hello, World!");

    using (var activity2 = activitySource2.StartActivity("Activity2"))
    {
        activity2?.SetTag("foo", 2);
        activity2?.SetTag("bar", "Hello, OpenTelemetry!");

        Debug.Assert(activity2?.ParentId == activity1?.Id);
    }
}

輸出：

Activity.TraceId:            7497970c0c05341cadbbbd2b87b4246b
Activity.SpanId:             ce96499cd0c115fd
Activity.TraceFlags:         Recorded
Activity.ParentSpanId:       1cfead09b114a264
Activity.ActivitySourceName: TestSource2
Activity.DisplayName:        Activity2
Activity.Kind:               Internal
Activity.StartTime:          2023-09-25T13:05:36.0415480Z
Activity.Duration:           00:00:00.0000240
Activity.Tags:
    foo: 2
    bar: Hello, OpenTelemetry!
Resource associated with Activity:
    service.name: MyCompany.MyProduct.MyService
    service.version: 1.0.0
    service.instance.id: 012ed685-54a3-4ec0-879b-aff9afcbd59c
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.6.0

Activity.TraceId:            7497970c0c05341cadbbbd2b87b4246b
Activity.SpanId:             1cfead09b114a264
Activity.TraceFlags:         Recorded
Activity.ActivitySourceName: TestSource1
Activity.DisplayName:        Activity1
Activity.Kind:               Internal
Activity.StartTime:          2023-09-25T13:05:36.0413000Z
Activity.Duration:           00:00:00.0110830
Activity.Tags:
    foo: 1
    bar: Hello, World!
Resource associated with Activity:
    service.name: MyCompany.MyProduct.MyService
    service.version: 1.0.0
    service.instance.id: 012ed685-54a3-4ec0-879b-aff9afcbd59c
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.6.0

兩個 Activity 都有相同的 TraceId，表示它們屬於同一個 Trace。

Activity1 在 Activity2 的外層作用域中建立，所以 Activity1 是 Activity2 的 Parent，Activity2 的 ParentId 等於 Activity1 的 Id。

Metrics

MeterProvider & Meter

Metrics 模組的使用和 Tracing 模組類似，透過 MeterProvider 來建立 Meter，然後透過 Meter 建立 Counter、Gauge、Measure 等。

var serviceName = "MyCompany.MyProduct.MyService";
var serviceVersion = "1.0.0";

var resourceBuilder = ResourceBuilder.CreateDefault()
    .AddService(serviceName: serviceName, serviceVersion: serviceVersion);

using MeterProvider meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddMeter("Meter1")
    .SetResourceBuilder(resourceBuilder)
    .AddConsoleExporter()
    .Build();

var meter = new Meter(name: "Meter1", version: "1.0.0");

var counter = meter.CreateCounter<long>("counter");

counter.Add(100);

輸出：

Resource associated with Metric:
    service.name: MyCompany.MyProduct.MyService
    service.version: 1.0.0
    service.instance.id: 8b4fd315-6a8f-4198-ab1a-a4d11a14a431
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.6.0

Export counter, Meter: Meter1/1.0.0
(2023-09-24T13:18:45.2247000Z, 2023-09-24T13:18:45.2277870Z] LongSum
Value: 100

Metrics 的型別

OTel 定義了以下幾種 Metric 型別：

Counter：計數器，用於記錄某個事件發生的次數，比如 HTTP 請求的次數、異常的次數等。
Asynchronous Counter: Counter 的非同步版本。
UpDownCounter：和 Counter 一樣用於記錄某個事件發生的次數，但和 Counter 不同的是，UpDownCounter 可以增加和減少。
Asynchronous UpDownCounter：UpDownCounter 的非同步版本。
Histogram ：直方圖，用於記錄某個事件的分佈情況，比如 HTTP 請求的耗時分佈。
Asynchronous Gauge：非同步計量器，用於記錄某個事件的瞬時值，比如 CPU 使用率、記憶體使用率等。

下面是各個型別在 Meter 中對應的建立方法：

Counter：CreateCounter
Asynchronous Counter: CreateObservableCounter
UpDownCounter：CreateUpDownCounter
Asynchronous UpDownCounter：CreateObservableUpDownCounter
Histogram ：CreateHistogram
Asynchronous Gauge：CreateObservableGauge

詳細的介紹可以參考這幾篇文章：

Logging

我們知道，.NET Core 有自己的 Logging 模組，可以透過 LoggerFactory 建立 ILogger，然後透過 ILogger 記錄日誌。

OTel SDK 的 Logging 模組，是 ILoggerProvider 的一個實現，將其註冊到 LoggerFactory 中，就可以透過 ILogger 收集日誌。

var serviceName = "MyCompany.MyProduct.MyService";
var serviceVersion = "1.0.0";

var resourceBuilder = ResourceBuilder.CreateDefault()
    .AddService(serviceName: serviceName, serviceVersion: serviceVersion);

using var loggerFactory = LoggerFactory.Create(
    builder => builder.AddOpenTelemetry(
        options =>
        {
            options.AddConsoleExporter();
            options.SetResourceBuilder(resourceBuilder);
        }));

var logger = loggerFactory.CreateLogger("MyLogger");

logger.LogInformation("Hello World!");

輸出：

LogRecord.Timestamp:               2023-09-25T13:09:19.2702090Z
LogRecord.CategoryName:            MyLogger
LogRecord.Severity:                Info
LogRecord.SeverityText:            Information
LogRecord.Body:                    Hello World!
LogRecord.Attributes (Key:Value):
    OriginalFormat (a.k.a Body): Hello World!

Resource associated with LogRecord:
service.name: MyCompany.MyProduct.MyService
service.version: 1.0.0
service.instance.id: 7f14c6d0-7d8b-490a-b4dc-bfb2275da108
telemetry.sdk.name: opentelemetry
telemetry.sdk.language: dotnet
telemetry.sdk.version: 1.6.0

Tracing、Metrics、Logging 三者的資料關聯

在上面的例子中，我們單獨使用了 Tracing、Metrics、Logging 模組，這三者的資料是相互獨立的，沒有關聯。

我們把上面的例子放在一起看下

var serviceName = "MyCompany.MyProduct.MyService";
var serviceVersion = "1.0.0";

var resourceBuilder = ResourceBuilder.CreateDefault()
    .AddService(serviceName: serviceName, serviceVersion: serviceVersion);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("TestSource1")
    .AddSource("TestSource2")
    .AddConsoleExporter()
    .Build();

using MeterProvider meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddMeter("Meter1")
    .AddConsoleExporter()
    .Build();

using var loggerFactory = LoggerFactory.Create(
    builder => builder.AddOpenTelemetry(
        options =>
        {
            options.AddConsoleExporter();
            options.SetResourceBuilder(resourceBuilder);
        }));

using var activitySource1 = new ActivitySource("TestSource1");
using var activitySource2 = new ActivitySource("TestSource2");

var logger = loggerFactory.CreateLogger("MyLogger");

var meter = new Meter("Meter1", "1.0.0");
var counter = meter.CreateCounter<long>("MyCounter");

using (var activity1 = activitySource1.StartActivity("Activity1"))
{
    logger.LogInformation("Hello, Activity1!");
    using (var activity2 = activitySource2.StartActivity("Activity2"))
    {
        logger.LogInformation("Hello, Activity2!");
        counter.Add(100);
    }
}

下面是輸出內容的整理：

兩個 Activity 的 TraceId 相同，表示它們屬於同一個 Trace，Activity1 是 Activity2 的 Parent。
兩次日誌輸出的 TraceId 是一樣的，表示這兩條日誌屬於同一個 Trace，但是它們的 SpanId 不同，表示這兩條日誌屬於不同的 Span。
Metrics 並沒有記錄 TraceId 和 SpanId，但和 Tracing、Logging 的 Resource 是一樣的，表示它們屬於同一個應用程式。透過 Resource 和記錄 Metrics 的時間，可以和 Tracing、Logging 的資料關聯起來。

Resource associated with Metric:
    service.name: MyCompany.MyProduct.MyService
    service.version: 1.0.0
    service.instance.id: 9f8306cb-c4a6-42f9-8d5b-897ba7f5df72
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.6.0

Export MyCounter, Meter: Meter1/1.0.0
(2023-09-25T13:38:33.6109280Z, 2023-09-25T13:38:33.6342240Z] LongSum
Value: 100

下期預告

下期將介紹如何在 ASP.NET Core 應用程式中使用 OpenTelemetry，並使用 Elastic APM 來收集資料。

歡迎關注個人技術公眾號

使用 OpenTelemetry 構建 .NET 應用可觀測性（4）：ASP.NET Core 應用中整合 OTel
2023-10-12
ASP.NET
使用 OpenTelemetry 的 .NET 可觀測性
2024-03-09
.Net微服務實戰之可觀測性
2021-09-29
微服務
.NET企業應用安全開發動向-概覽
2023-12-10
使用 Moq 測試.NET Core 應用 -- Mock 屬性
2018-07-13
Mock
OpenTelemetry - 雲原生下可觀測性的新標準
2021-01-12
雲原生ASP.NET Core程式的可監測性和可觀察性
2021-05-27
ASP.NET
使用.NET5、Blazor和Electron.NET構建跨平臺桌面應用
2021-11-21
Blazor
構建可讀性更高的 ASP.NET Core 路由
2019-05-31
ASP.NET路由
使用 .NET Core 3.x 構建 RESTFUL Api
2020-08-09
RESTAPI
ASP.NET Core之OpenTelemetry、SEQ構建視覺化日誌
2024-06-15
ASP.NET視覺化
ASP.NET Core 入門教程 2、使用ASP.NET Core MVC框架構建Web應用
2018-09-21
ASP.NETMVC框架架構Web
使用 .NET Core 3.x 構建 RESTFUL Api （續）
2020-08-11
RESTAPI
使用 Moq 測試.NET Core 應用 -- 其它
2018-07-15
可觀測性建設路線圖
2024-07-30
可觀測實踐｜如何使用阿里雲 Prometheus 觀測 ECS 應用
2022-10-28
阿里Prometheus
使用 Moq 測試.NET Core 應用 -- Mock 方法
2018-07-13
Mock
使用 Moq 測試.NET Core 應用 - Why Moq?
2018-07-12
使用InfluxDB時間序列資料功能構建可觀察性
2022-03-20
UX
使用 Moq 測試.NET Core 應用 -- Mock 行為
2018-07-14
Mock
使用 .NET 升級助手將.NET Framework應用遷移到.NET 5
2021-05-29
Framework
技術解密Java Chassis 3超實用的可觀測性
2024-06-14
解密Java
使用 Cloudflare 構建 Web3 應用
2021-10-30
CloudWeb
Istio可觀測性
2020-09-03
Topshelf一個用於使用.NET構建Windows服務框架
2021-04-03
Windows框架
使用 .NET 7、Blazor 和 .NET MAUI 構建你自己的 Podcast App
2023-01-23
BlazorUIASTAPP
通過silky框架在.net平臺構建微服務應用
2021-11-03
框架微服務
雲原生可觀測套件：構建無處不在的可觀測基礎設施
2022-11-11
套件
手把手教會將 Windows 窗體桌面應用從.NET Framework遷移到 .NET SDK/.NET 6 格式
2022-04-18
WindowsFramework
阿里雲日誌服務SLS攜手觀測雲釋出可觀測性解決方案，共建可觀測應用創新
2022-11-07
阿里
Dapr-可觀測性
2021-11-28
Yii2 應用概覽
2019-07-19
快速入門：構建您的第一個 .NET Aspire 應用程式
2023-11-16
使用 .NET CLI 構建專案腳手架
2021-03-09
.NET Core API閘道器Ocelot(一)【概覽，開始】
2019-03-02
API
Ooui：在瀏覽器中執行.NET應用
2018-04-23
UI瀏覽器
使用Try.NET建立可互動.NET文件
2019-05-20
第5章：可複用性的軟體構建方法 5.1可複用性的度量，形態和外部觀察
2019-01-19