- Configuring the application name
- Custom JMX metrics
- Disabling Automatic instrumentation
- Enabling trace correlation for IBM MQ
- Kafka Trace Correlation Headers
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.
.jar file the two standard attributes in
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
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:
deltais used for values that increase over time, such as counters, where the relative change is considered interesting.
absoluteis 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
Double) or a
String representing a number.
On the JVM dashboard, the JMX metrics are displayed under Custom JMX metrics.
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'
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
com.instana.plugin.javatrace: instrumentation: # Lightweight Bytecode Instrumentation, enabled by default # Disabling currently requires an agent restart enabled: true
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. This is the reason that Instana trace header correlation is not enabled by default for IBM MQ Java applications.
It is strongly recommended to 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 it is an application that can be changed, 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 it is an application that can not be changed, 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. It is an optional value. If it's missing,
it means that the trace correlation applies to all queues.
To enable trace correlation for IBM MQ, edit the agent
# General Tracing Settings com.instana.tracing: ibm-mq: trace-correlation: true ibmmq-optin-queues-regexp: '^QueueName.*'
This configuration will be picked up for new JVMs, when the Java Trace Sensor is updated or after the Instana agent has been shutdown for approximately 15 minutes. It will not be hot-reloaded during runtime, and a quick agent restart will also not pick up this configuration (this 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:
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.
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
You can also disable Kafka trace correlation entirely with
INSTANA_KAFKA_TRACE_CORRELATION=false , but this is not recommended.
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=bothwhen you start the JVM.
- To disable Kafka trace correlation entirely (not recommended), provide the option
-Dcom.instana.kafka.trace.correlation=falsewhen 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.