配置型 .NET Core 追蹤 SDK

配置型 .NET Core Trace SDK 會啟用文字段的宣告式規格，以及它們應該攜帶的標籤，並透過執行應用程式的某些方法來建立它們。
雖然並非提供所有功能，但宣告式方法比使用程式碼型 Tracing SDK 更有表達能力。在實作自訂追蹤之前，請先閱讀追蹤最佳作法。

免責聲明
配置
格式
- 用來檢測的比對方法
- 指定文字段的外觀
錯誤跨距
範例
限制

免責聲明

配置型 SDK 對應用程式中的變更很脆弱。您可以重新命名類別或方法，突然配置不再相符，您會失去追蹤資料。如果可能，我們建議您使用。NET Core SDK，對於程式碼變更更具復原力，且具有更多特性可協助您達成目標。

配置

配置指定在 configuration.yaml 檔案中。

附註: Instana 代理程式會自動挑選對配置型 .NET Core Trace SDK 的配置所做的變更。已檢測的應用程式需要重新啟動，才能使用變更的配置。

附註:Nuget 套件版本 1.191.20 及 .NET Core 感應器 1.0.28 或以上版本中提供配置型 .NET Core Trace SDK。使用 1.193.4 之前的 nuget-package 版本，它是接受功能。若要啟用它，請將環境變數 INSTANA_NETCORE_SDKCONFIG 設為 1 以啟用它。 > = 1.193.4 版不再需要此交換器。

格式

下列清單說明配置的一般格式:

# .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 索引鍵內定義多個目標，每個目標都指定要建立一個跨距。
一的 match 物件 target 指定要套用檢測的方法。
span 物件指定如何建置跨距，包括其名稱 (例如，在 call.name 過濾器的「無界限分析」中使用) 以及應該設定哪些標籤。

要檢測的比對方法

附註: 配置型 SDK 目前僅支援類別上方法的比對。尚不支援以介面或基礎類別 (遍訪繼承路徑) 為基礎的檢測。

此物件說明應該發生檢測的字碼點:

type: 要檢測的程式碼類型; 支援的值:
class，比對具體類別
name: 要符合的類別、介面或基礎類別的完整名稱
對於巢狀類別，表示法 a.b.c.OutsideClass$NestedClass 是預期的
method: 應記錄呼叫之給定類別、介面或基礎類別的方法名稱
arguments: 方法採用的引數數目 (只會比對具有此引數數目的超載)。如果未傳入任何引數，則為 0。

指定文字段的外觀

此物件說明在呼叫 match 中說明的方法時將建立之跨距的內容:

name: 跨距名稱
type: 跨距類型 (選用); 支援的值:
- ENTRY，用來指出來自外部系統的「送入」呼叫
- INTERMEDIATE，用來擷取對「感興趣」方法的內部呼叫 (預設值)
- EXIT，用來表示對外部系統的「送出」呼叫
tags: 要擷取的標籤/註釋清單，以及如何取得其值 (選用); 支援的值:
- constant，擷取常數值
  - kind: constant
  - name: 要建立的標籤名稱
  - value: 要建立之標籤的常數值
- return，擷取方法呼叫的回覆值
  - kind: return
  - name: 要建立的標籤名稱; 值將是所傳回物件的值
- argument，擷取方法呼叫的特定引數值
  - kind: argument
  - name: 要建立的標籤名稱
  - index: 要擷取為標籤值之引數的 0 型索引

附註: 如果擷取的值是沒有值的 null 或 Nullable<T> ，則不會新增已定義的標籤。可以使用 is not present 運算子與 call.tag 過濾器一起使用，在無界限分析中查閱具有遺漏標籤的文字段。

錯誤跨距

如果 Exception 在已檢測的方法外部傳播，則跨距會自動標示為錯誤，且 Exception::Message 的值會設為錯誤訊息，您可以透過 call.error.message 標籤在無界限分析中搜尋此錯誤訊息。

範例

下列 Snippet 顯示如何追蹤應用程式處理批次工作的配置範例:

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的項目文字段、註釋 endpoint (含常數值 BatchJob) ，以及註釋 batch.job (含第一個引數作為其值)。

此外，在批次處理期間 (即 Example.ProprietaryDatabaseClient中 ExecuteQuery 方法的呼叫) 送出的 DB 呼叫會建立名稱為 DatabaseCall 的結束文字段，以及具有常數值 Data Source=SomeServer;Initial Catalog=SomeDB 及註釋 db.statement 且具有方法呼叫第一個引數的註釋 db.connection_string 。

使用 ExecuteJob 處理新批次會啟動新的追蹤，且使用 ExecuteQuery 的後續資料庫更新會列為其中的子項跨距。所有 Instana 特性 (例如 Unbounded Analytics) 都可以與使用 Instana AutoTrace所建立的追蹤資料相同。

限制

下列限制適用於配置型 .NET Core Trace SDK:

不支援檢測建構子。
不支援在一種方法中啟動跨距，並在另一種方法中關閉該跨距; 亦即，配置型 SDK 對於自動追蹤中使用的 MethodPairInstrumentation 沒有對等項目
不支援在未明確建立 tag 的情況下擷取所有引數或回覆值。
不支援指定類別或方法的名稱型樣。
不支援在建立跨距之前還原追蹤環境定義