Configuring Java sensor

Automatic naming

Typically, Instana picks the application name automatically from the following sources:

• Application .jar file: Within the .jar file, the following standard attributes are available in META-INF/Manifest.MF:

  Implementation-Title=Demo App
  Implementation-Version=1.0.0
  

  By using build tools, you can set both attributes when you build the application. For more information, see the Oracle documentation.

• Command line: If the name is unavailable, the command line is used to find the name in the same way Java tools display JVMs.

• System properties: If no name is obtained from the .jar file, Instana inspects various system properties, for example -Dcatalina.home for Tomcat containers.

Manual naming

To customize the application name, use one of the following options:

• Configure the name during JVM initialization: To explicitly set the application name, specify the -Dcom.instana.agent.jvm.name="My Custom Name" attribute when you start the JVM.

• Use existing system property: To configure the agent to use an existing custom system property, specify a list of properties in the agent configuration.yaml file. The first existing property names the JVM:

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

Configuring JMX metrics with wildcard patterns

The object_name might contain wildcard patterns as specified in the Java ObjectName API documentation.

The following example shows the configuration with wildcard patterns:

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'

Viewing custom JMX metrics

On the JVM dashboard, the JMX metrics are displayed under the Custom JMX metrics.

Disabling Java Trace instrumentation

By default, Java trace instrumentation is enabled for all the Java processes. You can disable it for all processes or for a single process.

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

Enabling OpenTracing instrumentation

To enable the OpenTracing instrumentation of Java Trace, configure the agent configuration.yaml file as follows:

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

To disable the OpenTracing instrumentation, set opentracing: false to false.

Enabling Java Trace SDK

To enable the Java Trace SDK, configure the agent configuration.yaml file by providing a list of packages that need to be scanned for SDK annotation as follows. By default, no packages are scanned for SDK annotations.

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

To disable the Java Trace SDK, comment the entire packages section.

Enabling intermediate spans for Kafka Streams

In Kafka Streams, every stream operator is captured as an intermediate span. This feature impacts the performance of the application if you have large data inflows. Do not use this feature in production environments.

To enable capturing of intermediate spans for Kafka Streams, add the following lines to your agent configuration.yaml file:

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

Enabling internal service calls for WebMethods Integration Server

You can enable the feature of capturing every service call in WebMethods Integration Server as an intermediate span. But if the server handles heavy workloads, this feature can impact the performance of your application.

To enable capturing internal service calls for WebMethods Integration Server, add the following lines to your agent configuration YAML file:

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

Configuring IBM Db2 trace correlation

To configure IBM Db2 trace correlation, use one of the following configuration options:

• Agent configuration: Configure the agent configuration.yaml file as follows:

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

• Environmental variable configuration: Set the following environmental variables:

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

• System property configuration: Set the following system properties in the instrumented JVM:

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

By default, correlation (propagating TraceId and SpanId) is disabled. Propagation happens by using client information properties of Db2. The correlation field sets the field name as ClientHostname by default. The default delimiter is |. If the correlation mode is set to override (default), the correlation data overwrites any existing value. However, if it is not set to override, the correlation data is appended to the existing value.

Configuring WebLogic T3 trace correlation

Enterprise Java Bean (EJB) calls support WebLogic T3 correlation.

To configure WebLogics T3 trace correlation, use one of the following configuration options:

• Agent configuration: Configure the agent configuration.yaml file as follows:

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

• Environmental variable configuration: Set the following environment variable:

  INSTANA_WEBLOGIC_EJB_TRACE_CORRELATION=true
  

• System property configuration: Set the following system property in the instrumented JVM:

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

  This configuration works only if the T3 communication happens between WebLogic servers. However, if the WebLogic client is used outside the WebLogic server, correlation is not possible.

Enabling IBM MQ trace correlation

In some IBM MQ consumer clients, the presence of extra header data in IBM MQ messages can cause message processing errors and message rejection. Therefore, Instana Trace header correlation is not enabled by default for IBM MQ Java applications.

You must test IBM MQ trace correlation in a nonproduction environment before you enable it in a production environment. If you encounter errors on the IBM MQ client applications after you enable trace correlation, troubleshoot as follows:

• If you can alter the application, update the application to ignore the additional IBM MQ header data that is added by Instana. For assistance to make IBM MQ client changes, contact IBM MQ support.
• If you cannot alter the application, do not enable the IBM MQ trace correlation support.

To enable trace correlation for IBM MQ, use one of the following configuration options:

• Agent configuration: Edit the agent configuration.yaml file as shown in the following example:

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

  Set the ibmmq-optin-queues-regexp regular expression value to filter the queue names for which you want to enable the trace correlation. The regular expression value is optional and if it is missing then the trace correlation applies to all queues.

  This configuration is picked up in any of the following scenarios:

  • When the JVMs starts
  • When the Java Tracer is updated
  • After the Instana agent is shut down for approximately 15 minutes

  It is not hot-reloaded at run time. A quick agent restart might not pick up this configuration change because this feature is optimized. A configuration change needs a full reinstrumentation.

• System property configuration: Alternately, specify a system property on the application JVMs that contain IBM MQ clients as shown in the following example:

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

The IBM MQ sensor also provides a trace capability by using user exits (server-side tracing for IBM MQ). For more information about the IBM MQ sensor, see Monitoring IBM MQ.

Configuring Kafka trace correlation headers

To enable the header format for Kafka trace correlation headers that are used by the Java Tracer, use one of the following configuration options:

• Agent configuration: Configure the agent configuration.yaml file. For more information, see the Instana host agent.

• Environment variable configuration: Set the environment variable as shown in the following example:

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

  Valid values are binary, string, or both.

• System property configuration: Set the following property when you start the JVM:

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

To disable Kafka Trace correlation entirely, use one of the following configuration options:

• Agent configuration: See Instana host agent.
• Environment variable configuration: Set the environment variable INSTANA_KAFKA_TRACE_CORRELATION=false, but the use of this option is not suggested.
• System property configuration: Provide the option -Dcom.instana.kafka.trace.correlation=false when you start the JVM.

For more information, see Kafka Header Migration.

Disabling span batching

If you disable span batching, the number of individual spans sent increases, resulting in a higher data volume.

To disable span batching, use any one of the following configuration options:

• Agent configuration: Configure the agent configuration file as follows:

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

• Environmental variable configuration: Set the environmental variable as follows:

  INSTANA_SPANBATCHING_ENABLED=false
  

• System property configuration: Set the system property in the instrumented JVM as follows:

  -DspanBatchingEnabled=false
  

Span batching strategies for Data Grid and JDBC spans

Applications, such as Data Grid and JDBC, implement the following custom batching strategies for span batching:

• Data Grid: Span are merged only if both datagrid.operation and datagrid.cacheName have the same value in sequential spans. Span batching is enabled only if this condition is met.

• JDBC: The following types of span batching strategies are supported:

  • Default batching (enabled by default)

    Spans are merged regardless of the value of JDBC span attributes.

  • Custom batching (optional)

    Spans are merged only if the value of JDBC.statement is identical in sequential spans.

Enabling custom batching for JDBC spans

The size of the ingested data increases if you enable custom batching for JDBC spans.

To enable custom batching for JDBC spans, use any of the following configuration options:

• Agent configuration: Configure the agent configuration file as follows:

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

• Environmental variable configuration: Set the environmental variables as follows:

  INSTANA_CUSTOM_JDBC_SPANBATCHING_ENABLED=true
  

• System property configuration: Set the system property in the instrumented JVM as follows:

  -DcustomJDBCSpanBatchingEnabled=true
  

Enabling customer-defined logging level

To configure the logging level, use one of the following configuration options:

• System property configuration: Set instana_log_level_capture to ERROR or WARN.
• Environment variable configuration: Set INSTANA_LOG_LEVEL_CAPTURE to ERROR or WARN.

If you provide an invalid logging level (for example, INFO or TRACE), the following warning is logged in the agent logs and the default logging level WARN is used.

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

Disabling logging plug-ins

To disable logging for all logging plug-ins, you can use one of the following configuration options:

• Agent configuration: Configure Java tracing to disable all logging plug-ins in the agent configuration.yaml file:

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

• System property configuration: Set instana_log_level_capture="OFF".

• Environment variable configuration: Set INSTANA_LOG_LEVEL_CAPTURE="OFF".