Java 配置

配置應用程式名稱

如果存在，則會自動從啟動的 .jar 檔案中挑選應用程式名稱，否則會以 Java 工具顯示 JVM 的相同方式使用指令行。

在 .jar 檔案內， META-INF/Manifest.MF 中的兩個標準屬性如下:

Implementation-Title=Demo App
Implementation-Version=1.0.0

使用建置工具，可以在建置應用程式時設定這兩個屬性。 如需相關資訊，請參閱 Oracle 文件。

如果未使用上述程序取得任何名稱，則會透過檢查各種系統內容 (例如 -Dcatalina.home for Tomcat 儲存器) 來決定該名稱。

若要明確設定應用程式名稱，請在啟動 JVM 時指定 -Dcom.instana.agent.jvm.name="My Custom Name" 屬性。

若要讓代理程式使用已存在的自訂系統內容，請在代理程式 configuration.yaml中指定內容清單。 第一個現有的內容會命名 JVM:

com.instana.plugin.java:
  name-properties:
    - 'acme.app'
    - 'DEPLOYMENT'

自訂 JMX 度量

若要配置要監視的 JMX 度量，請編輯代理程式 configuration.yaml 檔案。

com.instana.plugin.java:
  jmx:
    # JMX is NOT hot-reloaded and needs to be set before a JVM is discovered.
    # Supported attribute types are Number and Boolean
    # delta calculation is only supported for Number
    - object_name: 'java.lang:type=Compilation'
      metrics:
        - attributes: 'TotalCompilationTime'
          type: 'delta' # delta will report the change to the previous second
    - object_name: 'java.lang:type=ClassLoading'
      metrics:
        - attributes: 'LoadedClassCount'
          type: 'absolute' # absolute will report the value as-is

上述範例中指定兩種類型的度量值:

• delta 用於隨著時間而增加的值，例如計數器，其中會將相對變更視為感興趣。
• absolute 用來顯示每次存取度量時的實際值。

指定的屬性必須是 Number (或它的其中一個子類別，例如 Integer 或 Double) 或代表數字的 String 。

在 JVM 儀表板上， JMX 度量會顯示在 自訂 JMX 度量之下。

object_name 可能包含萬用字元型樣，如 Java 的 ObjectName API 文件中所指定。 以下是具有萬用字元型樣的配置範例:

com.instana.plugin.java:
  jmx:
    - object_name: 'kafka.*:type=*-metrics,client-id=*,*'
      metrics:
        - attributes: 'incoming-byte-rate'
          type: 'absolute'
        - attributes: 'incoming-byte-total'
          type: 'absolute'
        - attributes: 'outgoing-byte-rate'
          type: 'absolute'
        - attributes: 'outgoing-byte-total'
          type: 'absolute'

啟用及停用 Java 追蹤

安裝 Instana 主機代理程式之後，依預設會啟用預設 (非 SDK) Java 追蹤設備測試，但不會啟用 OpenTracing 設備測試及 Java 追蹤 SDK 。

• 若要停用預設 Java 追蹤設備測試，請在 設備測試 區段中，將 enabled: true 變更為 enabled: false ，以配置代理程式 configuration.yaml 檔。 若要重新啟用預設「Java 追蹤」檢測，請將 enabled: false 變更為 enabled: true。

• 若要啟用 Java 追蹤的 OpenTracing 檢測，請將 opentracing: false 變更為 enabled: true。 若要再次啟用 OpenTracing 檢測，請將 opentracing: true 變更為 enabled: false。

• 若要啟用 Java 追蹤 SDK ，請提供需要掃描以取得 SDK 註釋的套件清單，以配置代理程式 configuration.yaml 檔案。 依預設，不會掃描任何套件以取得 SDK 註釋。 若要再次停用「Java 追蹤 SDK」，請註解整個 packages 區段。

在下列範例中，已停用預設 Java 追蹤設備測試，並已啟用 OpenTracing 設備測試及 Java 追蹤 SDK。

# Java Tracing
#com.instana.plugin.javatrace:
   instrumentation:
#    # Lightweight Bytecode Instrumentation, enabled by default
#    # Disabling currently requires an agent restart
     enabled: false
#    # OpenTracing instrumentation, disabled by default
#    # Enabling requires an agent restart
     opentracing: true
#    # To enable using the SDK, provide a list of packages that should be
#    # scanned for SDK annotations. All subpackages are scanned, as it is a
#    # starts-with prefix matching.
#    # Scanning a large amount of classes slows down agent attach and requires
#    # more CPU for parsing, therefore it is recommended to limit to packages
#    # actually using SDK annotations.
#    # By default no packages are scanned for SDK annotations.
     sdk:
       packages:
         - 'com.instana.backend'
         - 'com.instana.frontend'

停用自動檢測

這個 Instana 套件包含在套件載入時起始設定的自動檢測。 此檢測提供 Instana 儀表板的分散式追蹤資訊。

若要停用自動檢測 (追蹤) ，請編輯代理程式 configuration.yaml 檔案。

com.instana.plugin.javatrace:
  instrumentation:
    # Lightweight Bytecode Instrumentation, enabled by default
    # Disabling currently requires an agent restart
    enabled: true

啟用 IBM MQ 的追蹤相關性

在部分 IBM MQ 消費者用戶端中， IBM MQ 訊息中存在其他標頭資料可能會導致訊息處理錯誤及訊息拒絕。 這是依預設未針對 IBM MQ Java 應用程式啟用 Instana 追蹤標頭相關性的原因。

強烈建議 在 非正式作業環境 中測試 IBM MQ 追蹤相關性，然後在正式作業環境中啟用它。 如果啟用追蹤相關性支援在 IBM MQ 用戶端應用程式中導致錯誤，請執行下列其中一個動作:

• 如果它是可以變更的應用程式，請更新應用程式，以忽略 Instana 所新增的其他 IBM MQ 標頭資料。 如果需要協助進行 IBM MQ 用戶端變更，您可以聯絡 IBM MQ 支援中心。
• 如果它是無法變更的應用程式，請不要啟用 IBM MQ 追蹤相關性支援。

如果已啟用 IBM MQ 追蹤相關性，您也可以設定 ibmmq-optin-queues-regexp 正規表示式值來過濾您要啟用追蹤相關性的佇列名稱。 它是選用值。 如果遺漏，則表示追蹤相關性會套用至所有佇列。

若要啟用 IBM MQ的追蹤相關性，請編輯代理程式 configuration.yaml 檔案。

# General Tracing Settings
com.instana.tracing:
  ibm-mq:
    trace-correlation: true
    ibmmq-optin-queues-regexp: '^QueueName.*'

當更新「Java 追蹤感應器」時，或在 Instana 代理程式關閉大約 15 分鐘之後，將會針對新的 JVM 挑選此配置。 在執行時期期間不會熱重新載入它，而且快速代理程式重新啟動也不會採用此配置 (這是最佳化，因為配置變更需要完整重新檢測)。

作為替代方案，可以在包含 IBM MQ 用戶端的應用程式 JVM 上指定系統內容:

-Dinstana.ibm.mq.trace.correlation.enable=true -Dcom.instana.ibm.mq.trace.optin.queues="^QueueName.*"

IBM MQ 感應器也會利用使用者結束程式來提供追蹤功能。 如需 IBM MQ 感應器的相關資訊，請參閱 監視 IBM MQ。

Kafka 追蹤相關性標頭

您可以使用環境變數 INSTANA_KAFKA_HEADER_FORMAT來配置 Java 追蹤程式所使用的 Kafka 追蹤相關性標頭的標頭格式。 有效值為 binary、 string或 both。 您也可以使用 INSTANA_KAFKA_TRACE_CORRELATION=false 完全停用 Kafka 追蹤相關性，但不建議這樣做。

這兩個選項也可以配置成系統內容:

• 若要變更標頭格式，請在啟動 JVM 時提供 -Dcom.instana.kafka.trace.header.format=binary、 -Dcom.instana.kafka.trace.header.format=both或 -Dcom.instana.kafka.trace.header.format=both 其中一個選項。
• 若要完全停用 Kafka 追蹤相關性 (不建議) ，請在啟動 JVM 時提供選項 -Dcom.instana.kafka.trace.correlation=false 。

另一個替代方案是在 Instana 主機代理程式層次配置 Kafka 追蹤相關性選項。

如需相關資訊，請參閱 Kafka 標頭移轉。