通過OpenTelemetry為應用埋點并上報鏈路數據至可觀測鏈路 OpenTelemetry 版后,可觀測鏈路 OpenTelemetry 版即可開始監控應用,您可以查看應用拓撲、調用鏈路、異常事務、慢事務和SQL分析等一系列監控數據。本文介紹如何使用OpenTelemetry為.NET應用進行自動或手動埋點并上報數據。
前提條件
新版控制臺
登錄可觀測鏈路 OpenTelemetry 版控制臺,在左側導航欄單擊接入中心。
在開源框架區域單擊OpenTelemetry卡片。
在彈出的OpenTelemetry面板中選擇數據需要上報的地域。
說明初次接入的地域將會自動進行資源初始化。
選擇連接方式和上報方式,然后復制接入點信息。
連接方式:若您的服務部署在阿里云上,且所屬地域與選擇的接入地域一致,推薦使用阿里云內網方式,否則選擇公網方式。
上報方式:根據客戶端支持的協議類型選擇HTTP或gRPC協議上報數據。
舊版控制臺
在左側導航欄單擊集群配置,然后在右側頁面單擊接入點信息頁簽。
在頁面頂部選擇需要接入的地域,然后在集群信息區域打開顯示Token開關。
在客戶端采集工具區域單擊OpenTelemetry。
在相關信息列中,獲取接入點信息。
說明如果應用部署于阿里云生產環境,則選擇阿里云VPC網絡接入點,否則選擇公網接入點。
背景信息
OpenTelemetry .NET支持自動埋點和手動埋點。
自動埋點
支持自動埋點的.NET / .NET Framework版本:
.NET SDK 6+
.NET Framework暫不支持自動埋點
支持的框架請參見OpenTelemetry官方文檔。
手動埋點和半自動埋點
支持的版本:
.NET ≥ 5.0
.NET Core ≥ 2.0
.NET Framework ≥ 4.6.1
支持的框架:
框架名稱
是否支持.NET Framework(Windows平臺)
是否支持.NET
(跨平臺,原.NET Core)
支持的框架版本
鏈接
ASPNET
支持
ASP.NET (.NET Framework) MVC / WebApi在.NET上不支持
-
-
ASPNETCORE
/
支持
-
-
AZURE
支持
支持
支持2021年10月01日之后發布的Azure.前綴的包。
ELASTICSEARCH
支持
支持
Elastic.Clients.Elasticsearch支持版本:[8.0.0, 8.10.0) 。
版本≥8.10.0由 Elastic.Transport instrumentation支持。
ELASTICTRANSPORT
支持
支持
≥0.4.16
ENTITYFRAMEWORKCORE
/
支持
≥6.0.12
GRAPHQL
/
支持
≥7.5.0
GRPCNETCLIENT
支持
支持
[2.52.0, 3.0.0)
HTTPCLIENT
支持
支持
*
QUARTZ
.NET Framework 不支持≤ 4.7.1的版本
支持
≥3.4.0
MASSTRANSIT
/
支持
≥8.0.0
MONGODB
支持
支持
[2.13.3, 3.0.0)
MYSQLCONNECTOR
支持
支持
≥2.0.0
MYSQLDATA
/
支持
≥8.1.0
NPGSQL
支持
支持
≥6.0.0
NSERVICEBUS
支持
支持
≥8.0.0
SQLCLIENT
支持
支持
Microsoft.Data.SqlClient v3.*暫不支持
System.Data (shipped with .NET Framework)
STACKEXCHANGEREDIS
/
支持
[2.0.405, 3.0.0)
WCFCLIENT
支持
支持
-
-
WCFSERVICE
支持
/
-
-
示例Demo
示例代碼倉庫地址:dotnet-demo
方法一:自動埋點
版本限制
.NET SDK 6+
.NET Framework暫不支持自動埋點
使用ASP.NET Core編寫Web應用。
創建Demo應用。
mkdir dotnet-simple-demo cd dotnet-simple-demo dotnet new web
將Properties/launchSettings.json文件中的內容替換成以下配置。
{ "$schema": "http://json.schemastore.org/launchsettings.json", "profiles": { "http": { "commandName": "Project", "dotnetRunMessages": true, "launchBrowser": true, "applicationUrl": "http://localhost:8080", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" } } } }
構建應用。
dotnet build
為應用配置自動埋點.
下載并執行OpenTelemetry .NET自動埋點安裝腳本。
curl -L -O https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh ./otel-dotnet-auto-install.sh
設置環境變量并運行OpenTelemetry .NET自動埋點腳本。
請將
<serviceName>
替換為您的服務名,請將<endpoint>
和<token>
替換為前提條件中獲取的接入點和鑒權Token。export OTEL_TRACES_EXPORTER=otlp \ OTEL_METRICS_EXPORTER=none \ OTEL_LOGS_EXPORTER=none \ OTEL_SERVICE_NAME=<serviceName> \ OTEL_EXPORTER_OTLP_PROTOCOL=grpc OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \ OTEL_EXPORTER_OTLP_HEADERS="Authentication=<token>" . $HOME/.otel-dotnet-auto/instrument.sh
說明更多OpenTelemetry .NET自動埋點的環境變量配置,請參見OpenTelemetry .NET自動埋點環境變量。
運行并訪問應用。
運行應用。
dotnet run
使用以下命令訪問應用,生成的調用鏈會自動上報至可觀測鏈路 OpenTelemetry 版。
curl localhost:8080/
方法二:手動埋點
進入示例代碼倉庫的dotnet-demo/opentelemetry-demo/manual-demo路徑,然后安裝手動埋點所需的OpenTelemetry相關依賴。
dotnet add package OpenTelemetry dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol dotnet add package OpenTelemetry.Exporter.Console # 可選,在控制臺導出數據 dotnet add package OpenTelemetry.Extensions.Hosting
在OpentelemetryExporterDemo.cs文件中創建OpenTelemetry TracerProvider,并添加基于HTTP協議的OtlpExporter,修改上報應用名和上報數據的Endpoint。
using System.Diagnostics; using OpenTelemetry; using OpenTelemetry.Trace; using OpenTelemetry.Resources; using OpenTelemetry.Exporter; namespace Demo { internal static class OpentelemetryExporterDemo { internal static void Run() { Console.WriteLine("otlp running"); // OpenTelemetry上報應用名 var serviceName = "otlp-test"; using var tracerProvider = Sdk.CreateTracerProviderBuilder() .AddSource(serviceName) .SetResourceBuilder( ResourceBuilder.CreateDefault().AddService(serviceName)) .AddOtlpExporter(opt => { // 根據前提條件中獲取的接入點信息進行修改 opt.Endpoint = new Uri("<endpoint>"); // 使用HTTP協議上報數據 opt.Protocol = OtlpExportProtocol.HttpProtobuf; }) .AddConsoleExporter() // 可選,在控制臺導出數據 .Build(); for(int i = 0; i<10; i++) { var MyActivitySource = new ActivitySource(serviceName); using var activity = MyActivitySource.StartActivity("SayHello"); activity?.SetTag("bar", "Hello World"); } } } }
修改Program.cs文件內容,在Main方法中調用OpentelemetryExporterDemo。
using System.Diagnostics; using System.Net.Http; using OpenTelemetry; using OpenTelemetry.Resources; using OpenTelemetry.Trace; namespace Demo { public class Otlp { public static void Main(string[] args) { OpentelemetryExporterDemo.Run(); } } }
在當前路徑下運行以下命令。
dotnet run
方法三:半自動埋點
OpenTelemetry支持自動上傳數十種.NET框架Trace的數據,詳細的.NET框架列表請參見Supported Libraries。
進入示例代碼倉庫的dotnet-demo/opentelemetry-demo/auto-demo路徑,創建ASP.NET Core應用(Web應用)。
請將代碼中的
<your-project-name>
替換為實際的應用名。mkdir <your-project-name> cd <your-project-name> dotnet new mvc
下載觀測.NET應用必備的OpenTelemetry依賴。
dotnet add package OpenTelemetry.Exporter.Console # 在控制臺導出采集的數據 dotnet add package OpenTelemetry.Extensions.Hosting dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol # 以OTLP協議導出
下載自動埋點依賴。
下載為ASP.NET Core框架自動埋點的依賴,當應用收到HTTP請求時,會自動生成Span并上報。如需為其他框架自動埋點,請參考Supported Libraries下載對應依賴。
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
修改<your-project-name>/Program.cs文件中的代碼。
在源文件開頭導入所需包。
using System.Diagnostics; using OpenTelemetry.Exporter; using OpenTelemetry.Resources; using OpenTelemetry.Trace;
在源文件末尾添加DiagnosticsConfig類。
請將代碼中的
<your-service-name>
和<your-host-name>
替換為實際的服務名和主機名。public static class DiagnosticsConfig { public const string ServiceName = "<your-service-name>"; public const string HostName = "<your-host-name>"; public static ActivitySource ActivitySource = new ActivitySource(ServiceName); }
添加OpenTelemetry初始化代碼。
HTTP協議上報
請將以下代碼中的
<http_endpoint>
替換成前提條件中獲取的接入點信息。// ... builder.Services.AddOpenTelemetry() .WithTracing(tracerProviderBuilder => tracerProviderBuilder .AddSource(DiagnosticsConfig.ActivitySource.Name) .SetResourceBuilder(OpenTelemetry.Resources.ResourceBuilder.CreateDefault() .AddAttributes(new Dictionary<string, object> { {"service.name", DiagnosticsConfig.ServiceName}, {"host.name",DiagnosticsConfig.HostName} })) .AddAspNetCoreInstrumentation() .AddConsoleExporter() // 在控制臺導出Trace數據,可選 .AddOtlpExporter(opt => { // 使用HTTP協議上報 opt.Endpoint = new Uri("<http_endpoint>"); opt.Protocol = OtlpExportProtocol.HttpProtobuf; }) ); // ...
使用gRPC協議上報
請將以下代碼中的
<grpc_endpoint>
和<token>
替換成前提條件中獲取的接入點信息和Token。// ... builder.Services.AddOpenTelemetry() .WithTracing(tracerProviderBuilder => tracerProviderBuilder .AddSource(DiagnosticsConfig.ActivitySource.Name) .SetResourceBuilder(OpenTelemetry.Resources.ResourceBuilder.CreateDefault() .AddAttributes(new Dictionary<string, object> { {"service.name", DiagnosticsConfig.ServiceName}, {"host.name",DiagnosticsConfig.HostName} })) .AddAspNetCoreInstrumentation() .AddConsoleExporter() // 在控制臺導出Trace數據,可選 .AddOtlpExporter(opt => { // 使用gRPC協議上報 opt.Endpoint = new Uri("<grpc_endpoint>"); opt.Headers = "Authentication=<token>"; opt.Protocol = OtlpExportProtocol.Grpc; }) ); // ...
// 引入所需包 using System.Diagnostics; using OpenTelemetry.Exporter; using OpenTelemetry.Resources; using OpenTelemetry.Trace; var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllersWithViews(); // OpenTelemetry 初始化 builder.Services.AddOpenTelemetry() .WithTracing(tracerProviderBuilder => tracerProviderBuilder .AddSource(DiagnosticsConfig.ActivitySource.Name) .SetResourceBuilder(OpenTelemetry.Resources.ResourceBuilder.CreateDefault() .AddAttributes(new Dictionary<string, object> { {"service.name", DiagnosticsConfig.ServiceName}, {"host.name",DiagnosticsConfig.HostName} })) .AddAspNetCoreInstrumentation() .AddConsoleExporter() // 在控制臺輸出Trace數據,可選 .AddOtlpExporter(opt => { // 使用HTTP協議上報 opt.Endpoint = new Uri("<http_endpoint>"); opt.Protocol = OtlpExportProtocol.HttpProtobuf; // 使用gRPC協議上報 // opt.Endpoint = new Uri("<grpc_endpoint>"); // opt.Headers = "Authentication=<token>"; // opt.Protocol = OtlpExportProtocol.Grpc; }) ); var app = builder.Build(); if (!app.Environment.IsDevelopment()) { app.UseExceptionHandler("/Home/Error"); app.UseHsts(); } app.UseHttpsRedirection(); app.UseStaticFiles(); app.UseRouting(); app.UseAuthorization(); app.MapControllerRoute( name: "default", pattern: "{controller=Home}/{action=Index}/{id?}"); app.Run(); // 創建DiagnosticsConfig類 public static class DiagnosticsConfig { public const string ServiceName = "<your-service-name>"; // 服務名 public const string HostName = "<your-host-name>"; // 主機名 public static ActivitySource ActivitySource = new ActivitySource(ServiceName); }
在終端執行以下命令運行項目。
dotnet run
返回示例:
在返回信息中獲取URL,例如
http://localhost:5107
。Building... info: Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:5107 info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. info: Microsoft.Hosting.Lifetime[0] Hosting environment: Development info: Microsoft.Hosting.Lifetime[0] Content root path: /path/to/<your-project-name>
在瀏覽器中訪問
http://localhost:5107
,返回以下頁面則說明數據已上報至可觀測鏈路 OpenTelemetry 版控制臺。
查看監控數據
在可觀測鏈路 OpenTelemetry 版控制臺的應用列表頁面選擇目標應用,查看鏈路數據。