配置型 Java 追蹤 SDK

配置型「Java 追蹤 SDK」會啟用文字段的宣告規格，以及文字段應該包含的標籤，並透過執行應用程式的特定方法來建立文字段。
表現性與程式化 Java 追蹤 SDK的 @Span 註釋及 SpanSupport.annotate() 機能的表現性相當。

在實作自訂追蹤之前，請先閱讀追蹤最佳作法。

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

簡介

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

配置

若要使用配置型 Java 追蹤 SDK ，您需要啟用 Java 追蹤 SDK ，如啟用及停用 Java 追蹤中所述。

附註：

Instana 代理程式會自動挑選對配置型 Java 追蹤 SDK 的配置所做的變更。已檢測的應用程式需要重新啟動，才能使用變更的配置。
「Java 追蹤感應器」 1.2.351 版或更新版本中提供配置型 Java 追蹤 SDK。

格式

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

# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: 'interface'|'class'|'baseclass'
            name: '<type-name>'
            method: '<method-name>'
            [argumentTypes:
      	      - '<argument-type-index0>'
    	      - '<argument-type-indexn>']
            [returnType: '<return-type-name>']
          span:
            name: '<span-name>'
            [type: '<span-type>']
            [stackDepth: <depth>]
            [tags:
              - kind: 'argument'
                name: 'name'
                index: 0
              - kind: 'return'
                name: 'name'
              - kind: 'constant'
                name: 'name'
                value: 'constant-value']

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

要檢測的比對方法

附註: 監測介面或基礎類別可能非常耗用資源，特別是在使用大量類別的應用程式中，應該盡可能避免使用。

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

type: 要檢測的程式碼類型; 支援的值:
- class，比對具體類別
- interface，比對所有實作介面的類別
- baseclass，比對延伸基礎類別的所有類別
name: 要符合的類別、介面或基礎類別的完整名稱
對於巢狀類別，表示法 a.b.c.OutsideClass$NestedClass 是預期的
method: 應記錄呼叫之給定類別、介面或基礎類別的方法名稱
argumentTypes: 要符合之方法的完整引數類型清單 (選用)
- 如果遺漏，則引數不相符，且在超載時，會將檢測套用至所有方法
- 如果存在，則所有引數必須依序符合給定的類型，否則方法將不符合
returnType: 要符合之方法的完整傳回類型 (選用)
- 如果遺漏，則不考量傳回類型
- 如果存在，則傳回類型必須符合給定的類型，否則方法將不符合

指定文字段的外觀

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

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

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

錯誤跨距

如果 Throwable 在已檢測方法外部傳播，則會自動將文字段標示為錯誤，並將 Throwable#getMessage() 的值設為錯誤訊息，您可以透過 call.error.message 標籤在無界限分析中搜尋此錯誤訊息。

範例

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

com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: processBatch
          span:
            name: Job
            type: ENTRY
            stackDepth: 2
            tags:
              - kind: constant
                name: endpoint
                value: BatchJob
              - kind: argument
                name: batch.job
                index: 0
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: updateDatabase
          span:
            name: DatabaseCall
            type: EXIT
            stackDepth: 2
            tags:
              - kind: constant
                name: db.connection_string
                value: jdbc:mysql://127.0.0.1:3306/jobs
              - kind: argument
                name: db.statement
                index: 0

首先，會檢測類別 com.instana.java.sdk.BatchApplication 中的方法 processBatch ，以建立名稱為 Job的項目文字段、註釋 endpoint (含常數值 BatchJob) ，以及註釋 batch.job (含第一個引數作為其值)。

此外，在批次處理期間送出的 DB 呼叫 (即相同類別中 updateDatabase 方法的呼叫) ，將會建立名稱為 DatabaseCall 的結束文字段，以及具有常數值 jdbc:mysql://127.0.0.1:3306/jobs 的註釋 db.connection_string 和具有方法呼叫第一個引數的註釋 db.statement 。

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

限制

下列限制適用於配置型 Java 追蹤 SDK:

不支援檢測建構子。
不支援在一種方法中啟動文字段，並在另一種方法中關閉文字段; 也就是說，配置型 SDK 沒有 @Span.Start 和 @Span.End 註釋的對等項目。
不支援在未明確建立 tag 的情況下擷取所有引數或回覆值。
不支援在引數清單中指定不重要引數或 "all the rest" 的位置保留元; 以引數為基礎的比對會嚴格執行。
不支援指定類別或方法的名稱型樣。
不支援在建立跨距之前還原追蹤環境定義; 也就是說，配置型 SDK 沒有等同於 SpanSupport.inheritNext()的功能。