OpenTelemetry API を使用した .NET カスタムインスツルメンテーション

Docs > APM > アプリケーションインスツルメンテーション > カスタムインスツルメンテーション > .NET > OpenTelemetry API を使用した .NET カスタムインスツルメンテーション

Unsure when to use OpenTelemetry with Datadog? Start with Custom Instrumentation with the OpenTelemetry API to learn more.

Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

You are not using Datadog supported library instrumentation.
You want to extend the ddtrace library’s functionality.
You need finer control over instrumenting your applications.

The ddtrace library provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with Datadog.

セットアップ

OpenTelemetry を Datadog トレースプロバイダーを使用するように構成するには

OpenTelemetry .NET 手動インスツルメンテーションドキュメントに従って、必要な手動 OpenTelemetry インスツルメンテーションを .NET コードに追加してください。注: OpenTelemetry SDK を呼び出すように指示されている箇所では、代わりに Datadog トレーシングライブラリを呼び出してください。
Datadog .NET トレーシングライブラリをインストールし、.NET Framework サービスまたは .NET Core (および .NET 5+) サービスのトレーサーを有効にします。プレビュー: 必要に応じて、Single Step APM Instrumentation を使用してこれを実行できます。
DD_TRACE_OTEL_ENABLED 環境変数を true に設定します。
アプリケーションを実行します。

Datadog は、これらの OpenTelemetry スパンと他の Datadog APM スパンを組み合わせて、アプリケーションの単一のトレースにします。また、OpenTelemetry インスツルメンテーションライブラリもサポートしています。

カスタムスパンの作成

新しい独立したトレースを開始するスパンを手動で作成するには:

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

// 新しいスパンを開始
using (Activity? activity = Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>"))
            {
  activity?.SetTag("operation.name", "custom-operation");
               // 何かを実行
            }

スパンの作成

既存のトレースコンテキスト内にカスタムスパンを作成するには

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

using (Activity? parentScope = Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>"))
{
   parentScope?.SetTag("operation.name", "manual.sortorders");
   using (Activity? childScope = Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>"))
   {
       // トレース対象のコードの周囲に using ステートメントをネストする
       childScope?.SetTag("operation.name", "manual.sortorders.child");
       SortOrders();
   }
}

スパンタグの追加

カスタムタグをスパンに追加して、追加のコンテキストを提供します。

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

public class ShoppingCartController : Controller
{
    private IShoppingCartRepository _shoppingCartRepository;

    [HttpGet]
    public IActionResult Index(int customerId)
    {
      Activity? activity =
      Telemetry.ActivitySource.StartActivity("<RESOURCE NAME>")

        // Datadog の Web UI で使用できるよう、スパンにタグを追加
        activity?.SetTag("customer.id", customerId.ToString());

        var cart = _shoppingCartRepository.Get(customerId);

        return View(cart);
    }
}

スパンにエラーを設定する

実行中にエラーが発生した場合は、スパンにエラー情報を設定します。

try
{
    // 例外をスローする可能性のある処理を実行します。
}
catch(Exception e)
{
    activity?.SetTag("error", 1);
    activity?.SetTag("error.message", exception.Message);
    activity?.SetTag("error.stack", exception.ToString());
    activity?.SetTag("error.type", exception.GetType().ToString());
}

スパンイベントの追加

スパンイベントを追加するには SDK バージョン 2.53.0 以上が必要です。

AddEvent API を使用してスパンイベントを追加できます。このメソッドには name パラメーターで構築した ActivityEvent が必須で、オプションで attributes と timestamp を受け取ります。メソッドは指定されたプロパティを持つ新しいスパンイベントを作成し、対象のスパンに関連付けます。

Name [required]: イベント名を表す文字列。
Timestamp [optional]: イベント発生時刻を表す UNIX タイムスタンプ。DateTimeOffset オブジェクトを想定します。
Attributes [optional]: 以下のプロパティを持つ 0 個以上のキーと値のペア。
- キーは空でない文字列である必要があります。
- 値として指定できるのは次のいずれかです。
  - プリミティブ型: string、Boolean、number。
  - 同一プリミティブ型の要素のみを含む配列 (例: string の配列)。
- 入れ子の配列や異なるデータ型を混在させた配列は使用できません。

以下の例は、スパンにイベントを追加するさまざまな方法を示しています。

var eventTags = new ActivityTagsCollection
{
    { "int_val", 1 },
    { "string_val", "two" },
    { "int_array", new int[] { 3, 4 } },
    { "string_array", new string[] { "5", "6" } },
    { "bool_array", new bool[] { true, false } }
};

activity.AddEvent(new ActivityEvent("Event With No Attributes"));
activity.AddEvent(new ActivityEvent("Event With Some Attributes", DateTimeOffset.Now, eventTags));