.NET Custom Instrumentation using the OpenTelemetry API

このページは日本語には対応しておりません。随時翻訳に取り組んでいます。
翻訳に関してご質問やご意見ございましたら、お気軽にご連絡ください。
Datadog で OpenTelemetry を使用するタイミングがわからない場合は、OpenTelemetry API を使用したカスタムインスツルメンテーションから始めて、詳細を学びましょう。

概要

OpenTelemetry API を使用してアプリケーションを手動でインスツルメントする理由はいくつかあります。

ddtrace ライブラリは、これらの目標を達成するためのさまざまなテクニックを提供しています。次のセクションでは、Datadog で使用するために OpenTelemetry API を使用してカスタムインスツルメンテーションを行う方法を説明します。

セットアップ

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

  1. OpenTelemetry .NET 手動インスツルメンテーションドキュメントに従って、必要な手動 OpenTelemetry インスツルメンテーションを .NET コードに追加してください。注: OpenTelemetry SDK を呼び出すように指示されている箇所では、代わりに Datadog トレーシングライブラリを呼び出してください。

  2. Datadog .NET トレーシング ライブラリをインストールし、.NET Framework サービスまたは .NET Core (および .NET 5+) サービスのトレーサーを有効にします。プレビュー: 必要に応じて、Single Step APM Instrumentation を使用してこれを実行できます。

  3. DD_TRACE_OTEL_ENABLED 環境変数を true に設定します。

  4. アプリケーションを実行します。

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());
}

Adding span events

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

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

  • Name [required]: A string representing the event’s name.
  • Timestamp [optional]: イベント発生時刻を表す UNIX タイムスタンプ。DateTimeOffset オブジェクトを想定します。
  • Attributes [optional]: Zero or more key-value pairs with the following properties:
    • The key must be a non-empty string.
    • The value can be either:
      • A primitive type: string, Boolean, or number.
      • A homogeneous array of primitive type values (for example, an array of strings).
    • Nested arrays and arrays containing elements of different data types are not allowed.

The following examples demonstrate different ways to add events to a span:

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));

詳細は OpenTelemetry 仕様 を参照してください。

ヘッダー抽出と挿入によるコンテキストの伝搬

分散型トレーシングのコンテキストの伝搬は、ヘッダーの挿入と抽出で構成できます。詳しくはトレースコンテキストの伝播をお読みください。

その他の参考資料

お役に立つドキュメント、リンクや記事:

サービス、リソース、トレースの詳細ドキュメント more more OpenTelemetry API と Datadog でインスツルメントされたトレースの相互運用性ドキュメント more more