通过OpenTelemetry为应用埋点并上报链路数据至可观测链路 OpenTelemetry 版后,可观测链路 OpenTelemetry 版即可开始监控应用,您可以查看应用拓扑、调用链路、异常事务、慢事务和SQL分析等一系列监控数据。本文介绍如何使用OpenTelemetry为.NET应用进行自动或手动埋点并上报数据。
前提条件
背景信息
OpenTelemetry .NET支持自动埋点和手动埋点。
自动埋点
支持自动埋点的.NET / .NET Framework版本:
.NET SDK 6+
.NET Framework暂不支持自动埋点
支持的框架请参见OpenTelemetry官方文档。
手动埋点和半自动埋点
支持的版本:
.NET ≥ 5.0
.NET Core ≥ 2.0
.NET Framework ≥ 4.6.1
支持的框架:
示例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; }) ); // ...
在终端执行以下命令运行项目。
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 版控制台的应用列表页面选择目标应用,查看链路数据。