構成ベースの .NET Core トレース SDK

構成ベースの SDK は、アプリケーションの変更に対して不安定です。 クラスまたはメソッドを名前変更すると、構成が突然一致しなくなり、トレース・データが失われます。 可能な限り、.NET Core SDK のご利用をお勧めします。このSDKはコードの変更に対する耐性がはるかに高く、目的を達成するための機能も豊富に備えています。

設定は ファイル configuration.yaml に記述されています。

以下のリストは、構成の一般的なフォーマットを示しています。

# .NET Full Framework Tracing
com.instana.plugin.netcore:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            class: '<type-name>'
            method: '<method-name>'
            arguments: <number of arguments>
          span:
            name: '<span-name>'
            type: 'ENTRY' | 'EXIT' | 'INTERMEDIATE'
            tags:
              - name: '<name of tag>'
                kind: argument
                index: <0-based index of the method's argument>
              - name: '<name of tag>'
                kind: constant
                index: '<constant value>'
              - name: '<name of tag>'
                kind: return

targets キー内に複数のターゲットを定義できます。各ターゲットでは、作成するスパンを 1 つ指定します。 1 つの target の match オブジェクトは、インスツルメンテーションの適用先のメソッドを指定します。 span オブジェクトは、スパンの作成方法を指定します。これには、スパンの名前 (call.name フィルターの無制限分析などで使用される) および設定するタグが含まれます。

Exception がインスツルメンテーションされたメソッドの外部に伝搬されると、スパンには自動的にエラーのマークが付けられ、 Exception::Message の値がエラー・メッセージとして設定されます。このエラー・メッセージは、 call.error.message タグを使用して 無制限分析 で検索できます。

以下のスニペットは、バッチ・ジョブを処理するアプリケーションをトレースする方法の構成例を示しています。

com.instana.plugin.clr:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            class: Example.BatchJobStarter
            method: ExecuteJob
            arguments: 1
          span:
            name: BatchJob
            type: ENTRY
            tags:
              - name: endpoint
                kind: constant
                value: BatchJob
              - name: batch.job
                kind: argument
                index: 0
        - match:
            type: class
            class: Example.ProprietaryDatabaseClient
            method: ExecuteQuery
            arguments: 1
          span:
            name: DatabaseCall
            type: EXIT
            tags:
              - name: db.connection_string
                kind: constant
                value: 'Data Source=SomeServer;Initial Catalog=SomeDB'
              - name: db.statement
                kind: argument
                index: 0

最初に、クラス Example.BatchJobStarter 内のメソッド ExecuteJob がインスツルメントされて、BatchJob という名前のエントリー・スパン、定数値 BatchJob を持つ注釈 endpoint、および値として最初の引数を持つ注釈 batch.job が作成されます。

さらに、バッチ処理中の発信 DB 呼び出し (つまり、Example.ProprietaryDatabaseClient 内のメソッド ExecuteQuery の呼び出し) で、DatabaseCall という名前のエグジット・スパン、定数値 Data Source=SomeServer;Initial Catalog=SomeDB を持つ注釈 db.connection_string、およびメソッド呼び出しの最初の引数を持つ注釈 db.statement が作成されます。

ExecuteJob を使用して新規バッチを処理すると、新しいトレースが開始され、ExecuteQuery による後続の DB 更新がその中に子スパンとしてリストされます。 無制限分析と同様、すべての Instana 機能は、Instana AutoTrace で作成されたトレースに同じように使用できます。

構成ベースの .NET Core トレース SDK には、以下の制約事項が適用されます。

• コンストラクターのインスツルメントはサポートされていません。
• 静的メソッドへのインストルメンテーションはサポートされていません。
• あるメソッドでスパンを開始して別のメソッドでそれを閉じることはサポートされていません。このため、構成ベースの SDK には、自動トレースで使用される MethodPairInstrumentation に相当するものはありません。
• tag を明示的に作成せずにすべての引数または戻り値をキャプチャーする処理はサポートされていません。
• クラスやメソッドの名前パターンの指定はサポートされていません。
• スパンを作成する前にトレース・コンテキストを復元することはサポートされていません。