範例：搭配 OTLP 和獨立 Aspire 儀表板使用 OpenTelemetry

發行項
10/15/2024

這是用來說明 OpenTelemetry 的. NET 可檢視性的系列範例之一。

除了作為 .NET Aspire 的標準部分外，Aspire 儀表板還可以作為一個獨立的 Docker 容器，提供一個 OTLP 端點，可以將遙測資料傳送到該端點，而且它會將記錄、計量和追蹤可視化。以這種方式使用儀表板與 .NET Aspire 沒有任何相依性，它可以可視化來自任何透過 OTLP 傳送遙測資料的應用程式的遙測資訊。它同樣適用於以 Java、GoLang、Python 等撰寫的應用程式 (如果它們可以將其遙測資料傳送至 OTLP 端點)。

使用 Aspire 儀表板的組態和設定步驟比使用 Prometheus、Grafana 和 Jaeger 等開放原始碼解決方案少，但與這些工具不同，Aspire 儀表板是做為開發人員視覺效果工具，而不是用於生產監視。

1. 建立專案

使用 Visual Studio 中的 ASP.NET Core Empty 範本或使用下列 .NET CLI 命令，建立簡單的 Web API 專案：

dotnet new web

2.新增計量和活動定義

下列程式碼會針對呼叫 API 的次數定義新的計量 (greetings.count)，以及定義新的活動來源 (Otel.Example)。

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

3.建立 API 端點

在 builder.Build(); 和 app.Run() 之間插入下列內容

app.MapGet("/", SendGreeting);

在檔案底部插入下列函數：

async Task<String> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

注意

端點定義不使用特定於 OpenTelemetry 的任何內容。其會針對可檢視性使用 .NET API。

4.參考 OpenTelemetry 套件

使用 NuGet 套件管理員或命令列來新增下列 NuGet 套件：

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
  </ItemGroup>

注意

使用最新版本，因為 OTel API 會不斷地發展。

5.使用正確的提供者設定 OpenTelemetry

在 builder.Build(); 前面插入下列程式碼：

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

此程式碼會使用不同的遙測資料來源來設定 OpenTelemetry：

它會將 OTel 提供者新增至 ILogger 以收集記錄檔記錄。
它會設定計量、註冊 ASP.NET 的檢測提供者和計量，以及我們的自訂計量。
它會設定追蹤、註冊檢測提供者和我們的自訂 ActivitySource。

然後，它會使用 env vars 註冊 OTLP 匯出工具進行其設定。

6. 設定 OTLP 環境變數

OTLP 匯出工具可以透過程式碼中的 API 設定，但更常見的是透過環境變數進行設定。將下列內容新增至 AppSettings.Development.json

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

您可以為 .NET OTLP 匯出工具新增其他環境變數或常見的 OTel 變數，例如 OTEL_RESOURCE_ATTRIBUTES 來定義資源屬性。

注意

常見的 gotcha 是混合AppSettings.json和AppSettings.Development.json，如果存在後者，當您從 Visual Studio 中按 F5 時將使用它，而且將會忽略 AppSettings.json 中的任何設定。

7. 啟動 Aspire 儀表板容器

使用 docker 下載並執行儀表板容器。

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

儀表板中顯示的資料可能包含敏感資訊。根據預設，儀表板會受到需要權杖登入的驗證所保護。執行容器時，權杖會顯示在產生的輸出中。

[ Aspire 儀表板 ]

複製顯示的 URL，並將 0.0.0.0 取代為 localhost，例如 http://localhost:18888/login?t=123456780abcdef123456780，並在瀏覽器中開啟該 URL，或者您也可以在顯示登入對話框時在 /login?t= 之後貼上金鑰。每次啟動容器時，權杖都會變更。

8. 執行專案

執行專案，然後使用瀏覽器或 curl 存取 API。

curl -k http://localhost:7275

每次您要求頁面時，都會針對已發出的問候語數目增加計數。

8.1 記錄檔輸出

來自程式碼的記錄陳述式是使用 ILogger 的輸出。根據預設，會啟用主控台提供者，以便將輸出導向至主控台。

對於如何從 .NET 輸出記錄，有幾個選項：

stdout 和 stderr 輸出是由 Kubernetes 等容器系統重新導向至記錄檔。
使用將與 ILogger 整合的記錄程式庫，其中包括 Serilog 或 NLog。
使用 OTel 的記錄提供者，例如 OTLP。步驟 5 程式碼中的記錄區段會新增 OTel 提供者。

記錄會顯示在儀表板中做為結構化記錄 - 您在記錄訊息中設定的任何屬性都會擷取為記錄檔記錄中的欄位。

8.2 檢視計量

Aspire 儀表板會根據每個資源顯示計量 (這是 OTel 談論遙測來源的資源，例如程序)。選取資源時，儀表板會列舉資源已傳送至其 OTLP 端點的每個計量。計量清單是動態的，而且會在收到新的計量時更新。

計量的檢視將取決於所使用的計量類型：

計數器將直接顯示。
追蹤每個要求的數值長條圖 (例如，每個要求傳送的時間範圍或位元組) 會收集到一系列貯體中。儀表板會繪製 P50、P90 和 P99 百分位數的圖表。長條圖結果可以包含範例，這些範例是個別的資料點，以及該要求的 trace/spanId。這些資料會顯示為圖形上的點。選取其中一個會瀏覽至相應的追蹤，以便您查看導致該值的原因。這對於診斷極端值很有用。
計量可以包含維度，這些維度是與個別值相關聯的索引鍵/值組。每個維度會匯總這些值。使用檢視中的下拉式清單，您可以篩選結果來查看特定維度，例如只有 GET 要求，或 ASP.NET 中特定 URL 路由的要求。

8.3 檢視追蹤

追蹤檢視會顯示追蹤清單 - 每個追蹤都是共用相同 traceId 的一組活動。工作會使用代表工作單元的範圍進行追蹤。處理 ASP.NET 要求將會建立範圍。提出 HttpClient 要求將會建立一個範圍。藉由追蹤範圍的父系，即可將範圍的階層可視化。藉由從每個資源 (程序) 收集範圍，我們會追蹤在一系列服務中發生的工作。 Http 要求具有標題，用來將 traceId 和上層 spanId 傳遞至下一個服務。每個資源都需要收集遙測資料，並將其傳送至相同的收集器。然後，它會匯總並呈現範圍的階層。

儀表板會顯示含有摘要資訊的追蹤清單。每當看到具有新 traceId 的範圍時，它們就會在資料表中取得一個資料列。按一下檢視會顯示追蹤中的所有範圍。

選取範圍會顯示其詳細資料，包括範圍上的任何屬性，例如我們在步驟 3 中設定的 greeting 標籤。

共用方式為