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 changingenabled: true
toenabled: false
in the instrumentation section. To enable the default Java Trace instrumentation again, changeenabled: false
toenabled: true
. -
To enable the OpenTracing instrumentation of Java Trace, change
opentracing: false
toopentracing: true
. To disable the OpenTracing instrumentation again, changeopentracing: true
toopentracing: 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'
If you are running a Java application that was instrumented, you must restart the application to make sure that instrumentation is disabled.
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: false
If you are running a Java application that was instrumented, you must restart the application to make sure that instrumentation is disabled.
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.
Disabling stack trace capture
Java Tracer captures stack traces for exit and intermediate spans. However, stack traces for entry spans are disabled by default. If an application has a deeper stack or a request results in several spans, capturing stack traces might impact application performance. If you are facing performance issues, you can disable stack trace to optimize performance.
To disable stack trace capturing, start the JVM with the following properties:
-Dinstana.tracing.stack.exit=-1 -Dinstana.tracing.stack.log=-1
The following example displays how to disable stack trace capturing:
$ java -Dinstana.tracing.stack.exit=-1 -Dinstana.tracing.stack.log=-1 -jar application.jar
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.
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, complete 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 alter the application, do not enable IBM MQ trace correlation support.
If the IBM MQ Trace correlation is enabled, you can 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.
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 in any of the following scenarios:
- The JVMs starts
- 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.
As an alternative, you can specify a system property on the application JVMs that contain IBM MQ clients as shown:
-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
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.
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. So, do not use this feature in production environments.
To enable capturing internal service calls, add the following lines to your agent configuration YAML file:
com.instana.plugin.javatrace:
instrumentation:
plugins:
WebmethodsIntermediate: true