配置 Java 传感器

通常， Instana 会从以下来源自动获取应用程序名称：

• 应用程序 .jar 文件：在该 .jar 文件中，以下标准 META-INF/Manifest.MF属性可用：

  Implementation-Title=Demo App
  Implementation-Version=1.0.0
   

  通过使用构建工具，您可以在构建应用程序时同时设置这两个属性。 如需更多信息，请参阅 Oracle 文档。

• 命令行：如果无法获取名称，则使用命令行以与 Java 工具显示JVM相同的方式查找名称。

• 系统属性：如果无法从文件 .jar 中获取名称， Instana 会检查各种系统属性，例如 Tomcat -Dcatalina.home 容器的相关属性。

要自定义应用程序名称，请使用以下选项之一：

• 在 JVM 初始化时配置名称：若要显式设置应用程序名称，请在启动 JVM 时指定该 -Dcom.instana.agent.jvm.name="My Custom Name" 属性。

• 使用现有系统属性：若要配置代理以使用现有的自定义系统属性，请在代理 configuration.yaml 文件中指定属性列表。 第一个现有的属性名为 JVM ：

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

该文件 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'
 

在 JVM 仪表板中，“ JMX ”指标显示在 “自定义 JMX 指标 ”下。

默认情况下，所有 Java 进程均启用了 Java 跟踪功能。 您可以将其对所有进程或单个进程禁用。

com.instana.plugin.javatrace:
   instrumentation:
     enabled: false
 

您可以禁用特定的仪器化插件，以减少开销，或将某些技术排除在跟踪范围之外。 有关详细信息，请参阅 “禁用仪器插件 ”。

要启用 OpenTracing 对 Java Trace 的监控，请按以下方式配置代理 configuration.yaml 文件：

com.instana.plugin.javatrace:
   instrumentation:
     opentracing: true
 

要禁用 OpenTracing 的监控功能，请将 设置 opentracing: false 为 false。

要启用 Java Trace SDK，请按以下方式配置代理 configuration.yaml 文件，提供需要扫描SDK注解的包列表。 缺省情况下，不会扫描任何软件包以获取 SDK 注释。

com.instana.plugin.javatrace:
   instrumentation:
     sdk:
       packages:
         - 'com.instana.backend'
         - 'com.instana.frontend'
 

要禁用 Java 跟踪SDK，请将整个 packages 部分注释掉。

在 Kafka Streams 中，将捕获每个流操作程序作为中间范围。 如果您有大量数据流入，那么此功能会影响应用程序的性能。 请 不要 在生产环境中使用此功能。

要启用 Kafka 流的中间跨度捕获功能，请在您的代理 configuration.yaml 文件中添加以下几行：

com.instana.plugin.javatrace:
   instrumentation:
    plugins:
     Kafka011StreamIntermediate: true
 

您可以在 WebMethods 集成服务器中启用将每次服务调用捕获为中间跨段的功能。 但如果服务器处理的工作量很大，该功能就会影响应用程序的性能。

要启用 WebMethods 集成服务器的内部服务调用捕获功能，请在代理配置文件 YAML 中添加以下内容：

com.instana.plugin.javatrace:
   instrumentation:
     plugins:
       WebmethodsIntermediate: true
 

为避免在 webMethods Integration 服务器上捕获内部服务调用时，因创建中间跨度而导致的性能下降，请确保在启用内部服务调用捕获的配置之外，还向代理配置文件 YAML 中添加以下几行：

com.instana.plugin.javatrace:
   instrumentation:
     enableIntermediateSpanOpt: true
     plugins:
       WebmethodsIntermediate: true
       enableIntermediateSpanOpt: true

当 Kafka 的用户检索消息时， Instana 通常会生成一个 span 标签来表示整个轮询操作。 这意味着在一次轮询中获取的所有消息都会被归入一个 POLL 跨度中，这可能会限制对每条消息处理过程的可见性。

为了提高追踪粒度， Instana 提供了一项配置选项，可为每次单独的发送和接收操作启用关联功能——即使消息是以批处理方式消费的。 这使得可以为每条消息创建独立的跨度，从而更深入地了解消息级别的处理过程。

该 instana.kafka.correlate.send.receive 标志可让您查看在逐条处理记录时执行的操作。

何时使用该标志

单条记录处理：

@KafkaListener(topics = "topicName", containerFactory = "kafkaListenerContainerFactory")
public void listen(ConsumerRecord<?, ?> record)
{
    // Process single record
    // DB operations, Kafka sends, etc.
}

在这种情况下，该标志可让您查看在处理单个记录时发生的数据库保存操作和 Kafka 发送操作。

何时不建议使用该标志

使用批量操作进行批处理：

@KafkaListener(topics = "topicName")
public void receive(List<ConsumerRecord<?, ?>> consumerRecords) {
    // Direct bulk operations without iterating through individual records
}

当记录以批处理方式处理且直接执行批量操作（例如数据库批量写入）时，此标志并无实际意义，且可能会在 POLL 跨度中隐藏下游调用。

批量处理建议

对于批处理用例，您可以通过在应用程序启动时设置系统属性来禁用该标志，从而排除特定的 JVM。 此配置可确保下游呼叫保持可见。

java -jar -Dcom.instana.kafka.correlate.send.receive=false app.jar

混合处理模型的重要考虑因素

如果您的应用程序同时使用了 Kafka 批处理监听器（批处理）和标准 Kafka 监听器（单条记录处理），请注意该 instana.kafka.correlate.send.receive 标志的以下限制。

当该标志被禁用时，单记录 Kafka 监听器将不再以单独的POLL跨度显示处理过程。 相反，它们会显示为一个单独的 POLL 跨度，所有下游调用都归入该跨度之下，尽管应用程序实际上是逐条处理这些记录的。

要启用 Kafka 跨域关联，请使用以下配置之一：

• 代理配置：配置代理 configuration.yaml 文件。

  com.instana.tracing:  
    kafka:  
      correlateEverySendReceive: true # possible values: true or false

  注：

  编辑代理 configuration.yaml 程序文件后，请重新启动代理程序或应用程序。

• 环境变量配置：请按照以下示例设置环境变量：

  INSTANA_KAFKA_CORRELATE_SEND_RECEIVE=true # possible values: true or false

• 系统属性配置：启动 JVM 时，请设置以下属性：

  -Dcom.instana.kafka.correlate.send.receive=true # possible values: true or false 

下图展示了在启用和未启用该配置时，跨段相关性的表现。

要在 Instana 中完全禁用 Kafka 的跨域关联，请使用以下任一配置：

• 代理程序配置:

  com.instana.tracing: 
    kafka: 
      correlateEverySendReceive: false 

• 环境变量配置：设置环境变量。

  INSTANA_KAFKA_CORRELATE_SEND_RECEIVE=false

• 系统属性配置：启动 JVM 时，请提供 -Dcom.instana.kafka.correlate.send.receive=false 该选项。

该 instana.kafka.correlate.send.receive 标志默认处于禁用状态，以防止不必要的数据摄入。

要配置 IBM Db2 的跟踪关联，请使用以下配置选项之一：

• 代理配置：按以下方式配置 configuration.yaml 代理文件：

    com.instana.tracing:
      db2:
        trace-correlation: true
        db2CorrelationMode: dont-override
        db2CorrelationDelimiter: '|'
        db2CorrelationField: ClientHostname
   

• 环境变量配置：设置以下环境变量：

   INSTANA_DB2_TRACE_CORRELATION=true
   INSTANA_DB2_TRACE_CORRELATION_MODE=dont-override
   INSTANA_DB2_TRACE_CORRELATION_DELIMITER='|'
   INSTANA_DB2_TRACE_CORRELATION_FIELD=ClientHostname
   

• 系统属性配置：在已进行性能监控的 JVM 中设置以下系统属性：

   -Djdbc.db2.correlation.enable=true
   -Djdbc.db2.correlation.mod=dont-override
   -Djdbc.db2.correlation.delimiter=|
   -Djdbc.db2.correlation.field=ClientHostname
   

企业级 Java Bean (EJB) 调用支持 WebLogic T3 关联。

要配置 WebLogics T3 的跟踪关联，请使用以下配置选项之一：

• 代理配置：按以下方式配置 configuration.yaml 代理文件：

    # General Tracing Settings
    com.instana.tracing:
      weblogic:
        trace-correlation: true
   

• 环境变量配置：请设置以下环境变量：

  INSTANA_WEBLOGIC_EJB_TRACE_CORRELATION=true
   

• 系统属性配置：在已进行性能分析的 JVM 中设置以下系统属性：

  -Dcom.instana.weblogic.ejb.trace.correlation=true
   

  此配置仅在 T3 通信发生在 WebLogic 服务器之间时才有效。 但是，如果在 WebLogic 服务器之外使用 WebLogic 客户端，则无法进行关联。

• WeblogicRpcIntermediate: 若要在 WebLogic RPC 的调用跟踪中启用远程过程调用（ RPC ）的中间调用跨度，必须按以下方式配置代理 configuration.yaml 文件。 启用 RPC 中间呼叫跨度后，您可以在同一台 WebLogic 服务器内查看 RPC 呼叫。

   com.instana.plugin.javatrace:
     instrumentation:
       enableIntermediateSpanOpt: true
       plugins:
         WeblogicRpcIntermediate: true

  WeblogicRpcIntermediate 该功能默认处于禁用状态，以防止不必要的数据导入。

  为避免系统创建中间跨度时出现的性能下降问题，您可以启用该功能 enableIntermediateSpanOpt。

在某些 IBM MQ 客户端中， IBM MQ 消息中包含额外的标头数据可能会导致消息处理错误或消息被拒收。 因此，对于 IBM MQ Java 应用程序， Instana 跟踪头关联功能默认处于禁用状态。

在生产环境中启用 IBM MQ 跟踪关联功能之前，必须先在非生产环境中进行测试。 如果在启用跟踪关联后， IBM MQ 客户端应用程序出现错误，请按以下步骤进行故障排除：

• 如果您能够修改该应用程序，请将其更新为忽略由 Instana 添加的额外 IBM MQ 标头数据。 如需协助修改 IBM MQ 客户端，请联系 IBM MQ 技术支持。
• 如果无法修改应用程序，请勿启用 IBM MQ 的跟踪关联支持。

要为 IBM MQ 启用跟踪关联，请使用以下配置选项之一：

• 代理配置：按照以下示例编辑 configuration.yaml 代理文件：

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

  设置 ibmmq-optin-queues-regexp 正则表达式值，以筛选出您希望为其启用跟踪关联的队列名称。 正则表达式值是可选的，如果缺少该值，那么跟踪关联将应用于所有队列。

  在以下任何场景中，都会选取此配置:

  • 当 JVM 启动时
  • Java Tracer 更新时
  • Instana 代理关闭约15分钟后

  它在运行时未进行热重新装入。 由于此功能已优化，因此快速代理程序重新启动可能无法获取此配置更改。 配置更改需要完全重新检测。

• 系统属性配置：或者，可以在包含 IBM MQ 客户端的应用程序JVM上设置系统属性，如下例所示：

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

IBM MQ 传感器还通过使用用户退出点提供了跟踪功能（针对 IBM MQ 的服务器端跟踪）。 有关 IBM MQ 传感器的更多信息，请参阅监视 IBM MQ。

要启用“ Java ”跟踪器所使用的 Kafka 跟踪关联标头的格式，请使用以下配置选项之一：

• 代理配置：配置代理 configuration.yaml 文件。 如需更多信息，请参阅 Instana 主机代理。

• 环境变量配置：请按照以下示例设置环境变量：

  INSTANA_KAFKA_HEADER_FORMAT= both # possible values: binary, both, string
   

  有效值为 binary、 string 或 both。

• 系统属性配置：启动 JVM 时，请设置以下属性：

  -Dcom.instana.kafka.trace.header.format=binary # possible values: binary, both, string
   

若要完全禁用 Kafka 的跟踪关联功能，请使用以下配置选项之一：

• 代理配置：请参阅 Instana host agent。
• 环境变量配置：设置环境变量 INSTANA_KAFKA_TRACE_CORRELATION=false，但不建议使用此选项。
• 系统属性配置：启动 JVM 时，请提供 -Dcom.instana.kafka.trace.correlation=false 该选项。

有关更多信息，请参阅 Kafka 头迁移。

如果禁用跨度批处理，发送的单个跨度数量会增加，从而导致数据量增大。

要禁用 span 批处理，请使用以下任一配置选项：

• 代理配置：请按以下方式配置代理配置文件 ：

    com.instana.plugin.javatrace:
      instrumentation:
        spanBatchingEnabled: false
   

• 环境变量配置：请按以下方式设置环境变量：

  INSTANA_SPANBATCHING_ENABLED=false
   

• 系统属性配置：在已进行性能监控的 JVM 中按以下方式设置系统属性：

  -DspanBatchingEnabled=false
   

中间跨度批量处理会导致父跨度被合并，从而破坏父子关系，并导致子跨度变成孤立状态。 禁用 RPC -intermediate spans的批处理功能可避免此问题，并保持正确的跟踪结构。 要禁用 WebLogic RPC 中间区段的批量处理，请使用以下任一配置选项：

• 代理配置：请按以下方式配置代理配置文件 （<agent_install_dir>/etc/instana/configuration.yaml）：

   com.instana.tracing:
     batching:
       disabled:
         - rpc-intermediate

• 环境变量配置：请按以下方式设置环境变量：

  INSTANA_TRACING_BATCHING_DISABLED=rpc-intermediate

诸如 Data Grid 和 JDBC 之类的应用程序，实现了以下用于跨度批处理的自定义批处理策略：

• 数据网格：只有当连续的跨度中 和 datagrid.cacheName 的 datagrid.operation 值相同时，才会合并这些跨度。 只有满足此条件时，才会启用跨批处理。

• JDBC ：支持以下类型的 span 批处理策略：

  • 默认批处理 （默认启用）

    无论 JDBC 的span属性取值如何，跨度都会被合并。

  • 自定义批处理 （可选）

    只有当连续的跨度中 的值 JDBC.statement 完全相同时，才会合并这些跨度。

如果为 JDBC 跨度启用自定义分批处理，摄入的数据量将会增加。

要为 JDBC 跨度启用自定义分批处理，请使用以下任一配置选项：

• 代理配置：请按以下方式配置代理配置文件 ：

    com.instana.plugin.javatrace:
      instrumentation:
        customJDBCSpanBatchingEnabled: true
   

• 环境变量配置：请按以下方式设置环境变量：

  INSTANA_CUSTOM_JDBC_SPANBATCHING_ENABLED=true
   

• 系统属性配置：在已进行性能监控的 JVM 中按以下方式设置系统属性：

  -DcustomJDBCSpanBatchingEnabled=true
   

可以通过以下配置参数来配置跨度抑制：

• minspanduration: 此参数指定最小时长（默认值：4 毫秒）。 任何小于该值的跨度都将被忽略。

  com.instana.plugin.javatrace:
    instrumentation:
      minspanduration: 1

• span-suppression-start: 此参数用于设置开始抑制的跨度速率阈值。 如果该速率低于此值，则不会抑制任何跨度。 然而，当速率超过该阈值时，抑制作用会逐渐增强，直至达到每秒 5000 个跨度（此时所有跨度均被抑制）。 例如，如果将此参数设置为 3000，则只有当扫描速率超过每秒 3000 次时，才会开始抑制。

  com.instana.plugin.javatrace:
    instrumentation:
      span-suppression-start: 3000

要配置日志级别，请使用以下配置选项之一：

• 系统属性配置：设置 instana_log_level_capture 为 ERROR 或 WARN。
• 环境变量配置：将 INSTANA_LOG_LEVEL_CAPTURE 设置为 ERROR 或 WARN。

如果您指定了无效的日志级别（例如 或 TRACE），代理日志 INFO 中将记录以下警告，并使用默认日志 WARN 级别。

The value 'INFO' for 'INSTANA_LOG_LEVEL_CAPTURE' is not valid. Valid values are 'WARN', 'ERROR' and 'OFF'.
 

要禁用所有日志插件的日志记录，您可以使用以下配置选项之一：

• 代理配置：配置 Java 跟踪功能，以禁用代理 configuration.yaml 文件中的所有日志插件：

      com.instana.plugin.javatrace:
        instrumentation:
          plugins:
            Logging: false
   

• 系统属性配置：设置 instana_log_level_capture="OFF".

• 环境变量配置：设置 INSTANA_LOG_LEVEL_CAPTURE="OFF".

  注意： 编辑代理的 ` configuration.yaml ` 文件后，必须重启代理或应用程序。

在配置“忽略端点”功能之前，请先查看以下用于过滤跨段的规则：

• 当忽略一个跟踪时，所有后续的下游跟踪也将被忽略。
• 使用 * 来忽略所有端点、方法或命令。
• 端点值（例如 Kafka 主题名称或 Redis 命令）在各项服务中保持一致。
• 方法名称可能会因编程语言和技术而异。 请参考 Instana 用户界面，以确定您服务的正确方法和端点。

以下 Instana 的界面截图为识别正确的配置方法和端点提供了直观参考：

“忽略端点”功能仅支持完全匹配的方法名称。 请确保使用正确的的方法名称进行过滤。

您可以通过代理进行配置，从而全局忽略所有服务的端点。

要配置需忽略的端点，请在代理配置文件的 com.instana.tracing.ignore-endpoints 部分中指定必须从监控中排除的端点，如下例所示：

com.instana.tracing:
  ignore-endpoints:

    # Filtering by Method Name
    redis:
      - 'get'
      - 'type'
    dynamodb:
      - 'query'

    # Filtering by Method Name and Endpoint for Kafka
    kafka:
      - methods: ["consume"]
        endpoints: ["topic1", "topic2"]  # Exclude consume calls for topic1 and topic2
      - methods: ["consume", "publish"]
        endpoints: ["topic3"]  # Exclude both consume and send calls for topic3
      - methods: ["*"]
        endpoints: ["topic4"]  # Exclude all methods for topic4
      - methods: ["consume"]
        endpoints: ["*"]  # Exclude consume method for all topics

在上一个示例中，对于所列的过滤选项，以下跟踪信息将被忽略：

• 按方法筛选（ Redis 和 DynamoDB ）

  • GET 以及 TYPERedis 中的命令
  • QUERY DynamoDB 中的命令

• 按方法和终点筛选（仅限 Kafka ）

  • CONSUME 针对 topic1Kafka 中的 topic2 和 以及所有下游跟踪记录的方法
  • CONSUME 以及在 PUBLISHKafka 及其所有下游跟踪中的 topic3 方法
  • Kafka 中 topic4 针对 的所有方法 (*) 以及所有下游追踪
  • CONSUME 适用于所有主题 (*) 和所有下游跟踪的方法

  ignore-endpoints:
    kafka:
      - methods: [ "consume", "publish" ]
        endpoints: [ "topic1", "topic2" ]
      - methods: [ "consume" ]
        endpoints: [ "topic3" ]
      - methods: [ "*" ] # Applied to all methods
        endpoints: [ "topic4" ]
      - methods: [ "consume", "publish" ]
        endpoints: [ "*" ] # Applied to all topics

您可以通过使用环境变量 INSTANA_IGNORE_ENDPOINTS 来配置被忽略的端点，从而按服务过滤端点。

通过此环境变量，您可以根据方法和端点来排除跟踪信息。

INSTANA_IGNORE_ENDPOINTS=redis:get,type;dynamodb:query,scan;kafka:publish,consume

此配置会过滤以下跟踪信息：

• GET 以及 TYPERedis 中的命令
• QUERY 以及 SCANDynamoDB 中的命令
• PUBLISH 以及 CONSUMEKafka 中所有端点的方法

对于 Kafka ，您可以应用环境变量来忽略端点，但每次只能指定一个端点和一个方法。

INSTANA_IGNORE_ENDPOINTS=kafka:topic1,topic2,topic3,topic4,topic5,topic6,topic7,topic8,topic9,topic10,topic11

对于 Kafka ，与 Redis 和 DynamoDB, 不同，其端点列表不限于 10 个。 因此，您必须仔细考虑列表的大小，因为这会影响性能。

通过使用 ` Kafka ` 的方法选项 ，请按以下方式配置环境变量：

INSTANA_IGNORE_ENDPOINTS=kafka:consume,publish
OR
INSTANA_IGNORE_ENDPOINTS=kafka:poll,send
OR
INSTANA_IGNORE_ENDPOINTS=kafka:*

您还可以使用 Java 系统属性来配置忽略的端点。 以下示例演示了如何使用系统属性配置忽略端点：

java -Dinstana.ignore-endpoints="redis:get,type;dynamodb:query,scan;kafka:publish,consume" -jar application-jar

对于 Kafka ，您可以应用该系统属性来忽略端点，但每次只能指定一个方法和一个端点。

java -Dinstana.ignore-endpoints="kafka:topic1,topic2,topic3,topic4,topic5,topic6,topic7,topic8,topic9,topic10,topic11" -jar application-jar

对于 Kafka ，与 Redis 和 DynamoDB, 不同，其端点列表不限于 10 个。 因此，您必须仔细考虑列表的大小，因为这会影响性能。

通过使用 Kafka 的方法选项 ，请按以下方式配置系统属性：

java -Dinstana.ignore-endpoints="kafka:consume,publish" -jar application-jar
OR
java -Dinstana.ignore-endpoints="kafka:poll,send" -jar application-jar
OR
java -Dinstana.ignore-endpoints="kafka:*" -jar application-jar

默认情况下，您最多可以在一个Span上添加10个注释，并在 Instana 用户界面中显示它们。

-Dinstana.tracing.annotation.size=<desired_limit>

java -Dinstana.tracing.annotation.size=20 -jar application.jar

在代理配置文件中设置以下配置：

com.instana.tracing:
  stack.capture.timing: error

行为 ：仅捕获出错跨度（即元数据中包含错误的跨度 ）的堆栈跟踪，通过排除成功跨度的堆栈跟踪，从而提升性能并减少数据摄入量。

请按照以下方式在您的环境中设置 INSTANA_TRACING_STACK_CAPTURE_TIMING 并导出该环境变量：

export INSTANA_TRACING_STACK_CAPTURE_TIMING=error

中设置以下属性：

-Dcom.instana.tracing.stack.capture.timing=error 

要使用此系统属性，您需要在启动应用程序时添加以下参数：

java -Dcom.instana.tracing.stack.capture.timing=error -jar application.jar