腾讯云可观测平台通过 OpenTelemetry-dotnet 接入 .NET 应用（推荐）

一、前提条件

OpenTelemetry .NET 支持自动接入和手动接入。

二、自动接入

·支持自动接入的版本：

·.NET SDK ≥ 6

·.NET Framework 暂不支持自动接入

·支持自动接入的框架请参见 OpenTelemetry 产品文档。

三、手动接入

·支持手动接入的版本：

·.NET ≥ 5.0

·.NET Core ≥ 2.0

·.NET Framework ≥ 4.6.1

·支持手动接入的框架请参见 OpenTelemetry 产品文档。

四、Demo 应用

示例代码 Program.cs 是一个 WebApplication 使用 MySQLConnector 连接 MySQL 数据库操作，对应的 MySQL 服务请自行搭建，或直接购买云产品。

1. 初始化应用。

dotnet new web

2. 引入 Demo 中用到的依赖包。

其中 Microsoft.Extensions.Logging.Abstractions 是 MySqlConnector 必需的包。

dotnet add package MySqlConnector;dotnet add package Microsoft.Extensions.Logging.Abstractions;

3. 修改 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" } } }}

4. 编写业务代码 Program.cs。

Program.cs 中使用 WebApplication 接口模拟使用 MySQLConnector 连接 MySQL 数据库操作。

using MySqlConnector;var builder = WebApplication.CreateBuilder(args);var app = builder.Build();app.MapGet("/", () => "Hello World!");app.MapGet("/todo", () =>{ string connectionString = "server=localhost;port=3306;User Id=root;password=;Database=MyDB"; using (MySqlConnection myConnnect = new MySqlConnection(connectionString)) { try { myConnnect.Open(); using (MySqlCommand myCmd = new MySqlCommand("select * from MyTable", myConnnect)) { using (MySqlDataReader reader = myCmd.ExecuteReader()) { List<Int32> results = new List<Int32>(); while (reader.Read()) { // 假设我们只处理第一列的数据ID results.Add(reader.GetInt32(0)); } return "ids:" + string.Join(", ", results); } } } catch (Exception ex) { Console.WriteLine($"数据库操作出错: {ex.Message}"); return "数据库操作出错"; } }});app.Run();

五、获取接入点和 Token

1. 登录腾讯云可观测平台控制台。

2. 在左侧菜单栏中选择应用性能监控 > 应用列表，单击接入应用。

3. 在右侧弹出的接入应用抽屉框中，单击 .NET 语言。

4. 在接入 .NET 应用页面，选择你所要接入的地域以及业务系统。

5. 选择接入协议类型为 OpenTelemetry。

6. 上报方式选择你所想要的上报方式，获取你的接入点和 Token。

注意：说明：

七、步骤1：确定探针版本

请参考探针版本选择，找到和 .NET 版本所匹配的探针版本。

八、步骤2：安装 opentelemetry-dotnet-instrumentation

·如果使用最新版探针，请运行如下命令安装脚本：

curl -L -O https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.shsh ./otel-dotnet-auto-install.sh

·如果使用非最新版探针，请运行如下命令安装脚本（以1.9.0为例）：

curl -L -O https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/download/v1.9.0/otel-dotnet-auto-install.shsh ./otel-dotnet-auto-install.sh

九、步骤3：设置环境变量

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_RESOURCE_ATTRIBUTES="token=<token>" . $HOME/.otel-dotnet-auto/instrument.sh

对应的字段说明如下：

·<serviceName> ：应用名，多个使用相同 serviceName 接入的应用进程，在 APM 中会表现为相同应用下的多个实例。应用名最长63个字符，只能包含小写字母、数字及分隔符“ – ”，且必须以小写字母开头，数字或小写字母结尾。

·<token> ：获取接入点和 Token 中拿到业务系统 Token。

·<endpoint> ：获取接入点和 Token 中拿到的接入点。

注意：说明：

注意：brew install coreutils

十、步骤4：运行应用

1. 构建并运行应用。

dotnet builddotnet run

2. 在浏览器中访问以下链接：

http://localhost:8080http://localhost:8080/todo

每次进入该页面，OpenTelemetry 都会自动创建 Trace，并将链路数据上报至 APM。

十一、接入验证

启动 .NET 应用后，通过8080端口访问对应的接口，例如 http://localhost:8080/todo。在有正常流量的情况下，应用性能监控 > 应用列表中将展示接入的应用，单击应用名称/ID 进入应用详情页。

再选择实例分析，即可看到接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待30秒左右。

十二、自定义埋点（可选）

当自动埋点不满足你的场景或者需要增加业务层埋点时，你可参照下述内容，使用 opentelemetry-dotnet-instrumentation 添加自定义埋点。这篇仅展示最基本的自定义埋点方式，OpenTelemetry 社区提供了更多灵活的自定义埋点方式，具体使用方法可参考 OpenTelemetry 社区提供的 .NET 自定义埋点文档。

十三、引入 System.Diagnostics.DiagnosticSource 依赖包

dotnet add package System.Diagnostics.DiagnosticSource

十四、创建 ActivitySource 实例

private static readonly ActivitySource RegisteredActivity = new ActivitySource("Examples.ManualInstrumentations.Registered");

十五、创建 Activity

using (var activity = RegisteredActivity.StartActivity("Main")){ // 添加 Activity Tag activity?.SetTag("key", "3.1415"); // 为 Activity 添加一个 Event activity?.AddEvent(new("something happened")); // 一些业务代码 Thread.Sleep(1000);}

十六、在 OpenTelemetry.AutoInstrumentation 中注册 ActivitySource

在环境变量中设置 OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES，没有通过该配置注册的 ActivitySource 将不会接入上报。

export OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES=Examples.ManualInstrumentations.Registered

十七、手动接入方案

若 .NET SDK 版本不大于6或使用 .NET Framework ，但能满足手动接入条件，可以选择手动接入上报。这篇仅展示最基本的手动埋点方式，OpenTelemetry 社区提供了更多灵活的手动埋点方式，具体使用方法可参考 OpenTelemetry 社区提供的 .NET 手动接入文档。

十八、步骤1：安装手动接入所需的 OpenTelemetry 相关依赖

1. 安装手动接入所需的 OpenTelemetry 相关依赖。

dotnet add package OpenTelemetrydotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocoldotnet add package OpenTelemetry.Extensions.Hosting

2. 如果是基于 ASP.NET Core 的应用，还需要引入 OpenTelemetry.Instrumentation.AspNetCore 依赖。

dotnet add package OpenTelemetry.Instrumentation.AspNetCore

十九、步骤2：初始化 OpenTelemetry SDK

1. 创建一个 tracerProvider，并确保添加以下代码到你的程序开始处。

var serviceName = "<service-name>"; // <service-name>替换成自定义服务名using var tracerProvider = Sdk.CreateTracerProviderBuilder() .AddSource(serviceName) .SetResourceBuilder( ResourceBuilder.CreateDefault().AddService(serviceName) .AddAttributes(new Dictionary<string, object> { ["token"] = "<token>", // <token>替换成前置步骤中获得的 Token ["host.name"] = "<host>" // <host>替换成自定义主机名 })) .AddOtlpExporter(opt => { opt.Endpoint = new Uri("<endpoint>"); // <endpoint>替换成前置步骤中获得的接入点信息 opt.Protocol = OtlpExportProtocol.Grpc; }) .Build();

20、步骤3：修改应用代码，使用 ActivitySource 创建 Activity

1. 在应用任意需要手动接入的地方，创建一个 ActivitySource 用于创建 Activity。其用途相当于可观测领域的 Tracer。

var MyActivitySource = new ActivitySource(serviceName);

2. 当 ActivitySource 创建好后，创建一个 Activity。其用途相当于可观测领域的 Span 。

using var activity = MyActivitySource.StartActivity("SayHello");// 添加 Activity Tagactivity?.SetTag("key", "3.1415");// 为 Activity 添加一个 Eventactivity?.AddEvent(new("something happened"));

21、步骤4：运行程序

构建并运行应用。