基于配置的 Java 跟踪 SDK

基于配置的 Java Trace SDK 可以声明式地指定跨距和跨距应携带的标记，并通过执行应用程序的某些方法来创建跨距。

表现力与 @Span 注释和 SpanSupport.annotate() 编程 Java Trace SDK 的功能。

实施自定义跟踪前，请阅读跟踪最佳实践。

简介

基于配置的 SDK 会因应用程序中的更改而变脆弱。您可能会重命名一个类或一个方法，突然之间配置就不再匹配了，从而丢失了跟踪数据。建议您尽可能使用 Java 跟踪 SDK ，它对代码更改的适应能力要强得多，而且具有更多功能来帮助您实现目标。

配置

要使用基于配置的 Java 跟踪 SDK，您需要按照启用 Java 跟踪 SDK 中的说明启用 Java 跟踪 SDK。

注：

Instana 代理会自动接收对基于配置的 Java 跟踪 SDK 配置的更改。需要重新启动已检测的应用程序以使用已更改的配置。
基于配置的 Java Trace SDK 可在 Java Trace Sensor 1.2.351 或更高版本中使用。

格式

以下列表描述了该配置的一般格式：

# 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 键中定义多个目标，每个目标都指定要创建的一个范围。一个 target 的 match 对象指定了应用仪器的方法。 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 标记在无界分析中搜索该消息。

示例

以下片段显示了有关如何跟踪应用程序处理批处理作业的示例配置：

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 的条目范围，使用常量值 BatchJob 的注释 endpoint，以及使用第一个自变量作为其值的注释 batch.job。

此外，批处理期间的出局数据库调用（即同一类中方法 updateDatabase 的调用）将创建名称为 DatabaseCall 的出口范围，使用常量值 jdbc:mysql://127.0.0.1:3306/jobs 的注释 db.connection_string，以及使用方法调用的第一个自变量的注释 db.statement。

使用 processBatch 处理新批处理将启动新的跟踪，使用 updateDatabase 的后续数据库更新将作为子级范围列示在其中。所有 Instana 功能部件（例如，Unbounded Analytics）都可以完全用于使用 Instana 自动跟踪创建的跟踪。

限制

基于配置的 Java Trace SDK 存在以下限制：

不支持使用检测构造函数。
不支持在一个方法中启动范围并在另一个方法中关闭该范围；即基于配置的 SDK 对于 @Span.Start 和 @Span.End 注释没有等效项。
不支持在不显式创建 tag 的情况下捕获所有参数或返回值。
不支持在参数列表中为不重要的参数或所有其他参数指定占位符；基于参数的匹配以严格方式执行。
不支持为类或方法指定名称模式。
不支持在创建范围之前恢复跟踪上下文；即基于配置的 SDK 不具有等同于 SpanSupport.inheritNext() 的功能。