入门 Traces - 控制台
本指南将在几分钟内向您展示如何在控制台应用程序中开始使用 OpenTelemetry .NET Traces。
先决条件
- 在您的计算机上安装了 .NET SDK
创建控制台应用程序
创建新的控制台应用程序并运行它
dotnet new console --output getting-started
cd getting-started
dotnet run
您应该会看到以下输出
Hello World!
添加 OpenTelemetry Traces
安装 OpenTelemetry Console Exporter 包
dotnet add package OpenTelemetry.Exporter.Console
使用以下代码更新 Program.cs 文件
using System;
using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
namespace GettingStarted
{
class Program
{
// Define an ActivitySource to create activities from
private static readonly ActivitySource MyActivitySource = new ActivitySource(
"MyCompany.MyProduct.MyLibrary");
static void Main(string[] args)
{
// Configure the OpenTelemetry TracerProvider
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("getting-started"))
.AddSource("MyCompany.MyProduct.MyLibrary")
.AddConsoleExporter()
.Build();
// Start an activity (span) with some tags (attributes)
using (var activity = MyActivitySource.StartActivity("SayHello"))
{
// Set some attributes on the activity
activity?.SetTag("foo", 1);
activity?.SetTag("bar", "Hello, World!");
activity?.SetTag("baz", new int[] { 1, 2, 3 });
// Set the status of the activity
activity?.SetStatus(ActivityStatusCode.Ok);
// Do some work...
Console.WriteLine("Hello World!");
}
Console.WriteLine("Trace has been exported. Press any key to exit.");
Console.ReadKey();
}
}
}
再次运行应用程序（使用 dotnet run），您应该会看到来自控制台的 trace 输出
Activity.TraceId: d4a7d499698d62f0e2317a67abc559b6
Activity.SpanId: a091d18fbe45bdf6
Activity.TraceFlags: Recorded
Activity.ActivitySourceName: MyCompany.MyProduct.MyLibrary
Activity.DisplayName: SayHello
Activity.Kind: Internal
Activity.StartTime: 2022-03-30T19:42:33.5178011Z
Activity.Duration: 00:00:00.0097620
StatusCode : Ok
Activity.Tags:
foo: 1
bar: Hello, World!
baz: [1, 2, 3]
Resource associated with Activity:
service.name: getting-started
您现在正在使用 OpenTelemetry 收集 traces。
工作原理
ActivitySource (Tracer)
程序创建一个 ActivitySource，它代表一个 OpenTelemetry Tracer
private static readonly ActivitySource MyActivitySource = new ActivitySource(
"MyCompany.MyProduct.MyLibrary");
ActivitySource 用于创建和启动新的活动。
Activity (Span)
ActivitySource 实例用于启动一个 Activity，它代表一个 OpenTelemetry Span。您可以在其上设置几个标签（属性）并设置其状态
using (var activity = MyActivitySource.StartActivity("SayHello"))
{
activity?.SetTag("foo", 1);
activity?.SetTag("bar", "Hello, World!");
activity?.SetTag("baz", new int[] { 1, 2, 3 });
activity?.SetStatus(ActivityStatusCode.Ok);
}
TracerProvider
TracerProvider 配置为订阅指定源的活动并导出它们
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("MyCompany.MyProduct.MyLibrary")
.AddConsoleExporter()
.Build();
TracerProvider 是 OpenTelemetry SDK 的核心组件。它包含所有用于 tracing 的配置，如采样器、处理器、导出器等，并且高度可定制。
Tracing pipeline
OpenTelemetry .NET 中的 tracing pipeline 遵循以下流程
- ActivitySource 创建 Activities
- TracerProvider 接收 Activities
- Processor 处理 Activities
- Exporter 将 Activities 导出到后端
OpenTelemetry .NET 和 .NET Activity API
在 OpenTelemetry .NET 中，使用 ActivitySource 和 Activity 这两个术语来代替 OpenTelemetry 规范中的 Tracer 和 Span。这是因为 OpenTelemetry .NET 中的 tracing 是在 .NET 运行时内置的诊断系统之上实现的。
您可以通过依赖 System.Diagnostics.DiagnosticSource 包来 instrument 您的应用程序，该包提供了 Activity 和 ActivitySource 类，分别代表 OpenTelemetry 规范中的 Span 和 Tracer 概念。