Java configuration

Configuring the application name

If present, the application name is automatically picked up from the .jar file that launches, otherwise the command line is used in the same way Java tools display JVMs.

Within the .jar file the two standard attributes in META-INF/Manifest.MF are:

Implementation-Title=Demo App
Implementation-Version=1.0.0

Using build tools, both attributes can be set when building the application. For more information, see the Oracle documentation.

If no name is obtained using the procedure above, it's then determined by inspecting various system properties, for example -Dcatalina.home for Tomcat containers.

To explicitly set the application name, when starting the JVM specify the -Dcom.instana.agent.jvm.name="My Custom Name" attribute.

To have the agent use an already existing custom system property, specify a list of properties in the agent configuration.yaml. First existing property will name the JVM:

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

Custom JMX metrics

To configure which JMX metrics to monitor, edit the agent configuration.yaml file.

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

Two types of metrics are specified in the example above:

  • delta is used for values that increase over time, such as counters, where the relative change is considered interesting.
  • absolute is used to show the actual value each time the metric is accessed.

The attribute specified must either be a Number (or one of its subclasses like Integer or Double) or a String representing a number.

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

The object_name may contain wildcard patterns as specified in Java's ObjectName API documentation. Here's an example of a 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'

Enabling and disabling Java Trace

After you install the Instana host agent, the default (non-SDK) Java Trace instrumentation is enabled by default, but the OpenTracing instrumentation and Java Trace SDK are not enabled.

  • To disable the default Java Trace instrumentation, configure the agent configuration.yaml file by changing enabled: true to enabled: false in the instrumentation section. To enable the default Java Trace instrumentation again, change enabled: false to enabled: true.

  • To enable the OpenTracing instrumentation of Java Trace, change opentracing: false to enabled: true. To enable the OpenTracing instrumentation again, change opentracing: true to enabled: false.

  • 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. By default, no packages are scanned for SDK annotations. To disable the Java Trace SDK again, comment the whole packages section.

In the following example, the default Java Trace instrumentation is disabled, and the OpenTracing instrumentation and Java Trace SDK are enabled.

# 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'

Disabling Automatic instrumentation

This Instana package includes automatic instrumentation that is initialized on package load. This instrumentation provides distributed tracing information to your Instana dashboard.

To disable automatic instrumentation (tracing), edit the agent configuration.yaml file.

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

Disabling trace instrumentation for a Java process

Java trace instrumentation is enabled for all the Java processes by default.

To disable trace instrumentation for a Java process, do one of the following steps:

  • Add the -Dinstana.java.tracer.enabled=false system property as a Java virtual machine (JVM) argument.
  • Add the INSTANA_JAVA_TRACER_ENABLED=false system environment variable.

The system property has higher priority than the system environment variable if both are provided.

Configuring Java Tracing

You can use Java Tracer to instrument Kafka Streams application, trace IBM Db2, and enable Weblogic T3 correlation to get insights into their performance.

Enabling 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 Kafka Streams, add the following lines to your agent configuration.yaml file:

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

Configuring IBM DB2 Tracing

You can configure IBM Db2 Tracing by using agent configuration in the agent configuration.yaml file, or environmental variable or system properties in the instrumented JVM.

Sample configurations:

  Agent configuration:

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

  Environmental variable:

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

  System properties:

  -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. By default, it is ClientHostname. 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 (default), the correlation data is appended to the existing value.

Configuring Weblogic T3 Trace correlation

Enterprise Java Bean (EJB) calls support Weblogic T3 correlation when you configure Weblogics T3 by using agent configuration in the agent configuration.yaml file, or environmental variable or system properties in the instrumented JVM.

  • Agent configuration:

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

  • Environmental variable:

    INSTANA_WEBLOGIC_EJB_TRACE_CORRELATION

  • System property:

    -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 trace correlation for IBM MQ

In some IBM MQ consumer clients, the presence of additional 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.

Do not test IBM MQ Trace correlation in a non-production environment before you enable it in a production environment. If enabling trace correlation support causes errors in IBM MQ client applications, do one of the following actions:

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

If the IBM MQ Trace correlation is enabled, you can also set the ibmmq-optin-queues-regexp regular expression value to filter the queue names for which you want to enable the trace correlation. The value is optional. If it's missing, it means that the trace correlation applies to all queues.

To enable trace correlation for IBM MQ, edit the agent configuration.yaml file:

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

This configuration is picked up for new JVMs, when the Java Tracer is updated or after the Instana agent is shutdown for approximately 15 minutes. It is not hot-reloaded during runtime, and a quick agent restart might also not pick up this configuration (this feature is an optimization, since a configuration change needs a full re-instrumentation).

As an alternative, a system property can be specified on the application JVMs that contain IBM MQ clients:

-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. For more information about the IBM MQ sensor, see Monitoring IBM MQ.

Configuring Kafka Trace correlation headers

You can configure the header format for Kafka Trace correlation headers that are used by the Java Tracer with the environment variable INSTANA_KAFKA_HEADER_FORMAT. Valid values are binary, string, or both. You can also disable Kafka Trace correlation entirely with INSTANA_KAFKA_TRACE_CORRELATION=false, but you must not use this option. You can configure the header format for Kafka Trace correlation headers that are used by the Java Tracer with the environment variable INSTANA_KAFKA_HEADER_FORMAT. Valid values are binary, string, or both. You can also disable Kafka Trace correlation entirely with INSTANA_KAFKA_TRACE_CORRELATION=false. Both options can also be configured as a system property:

  • To change the header format, provide one of the options -Dcom.instana.kafka.trace.header.format=binary, -Dcom.instana.kafka.trace.header.format=both, or -Dcom.instana.kafka.trace.header.format=both when you start the JVM.
  • To disable Kafka Trace correlation entirely, provide the option -Dcom.instana.kafka.trace.correlation=false when you start the JVM.

Another alternative is to configure the Kafka Trace correlation options at the level of the Instana host agent.

For more information, see Kafka Header Migration.