Monitoring Java virtual machine (JVM)
The Java sensor provides automated code instrumentation for supported technologies, zero-configuration health monitoring of JVM instances, and end-to-end traces of requests across all systems.
- Supported information
- Instrumented frameworks and libraries
- Installation
- Optional configuration
- Features
- Troubleshooting
Supported information
Supported languages
Instana supports the following languages:
- Clojure
- Java
- Kotlin
- Scala
Supported operating systems
The Java sensor supports the operating systems that are consistent with the host agents requirements, which can be checked in the Supported operating systems section of each host agent, such as Supported operating systems for Unix.
Supported Java Runtimes versions
For information about the supported versions of Java Runtimes and the system requirements, see System requirements.
Instrumented frameworks and libraries
Java sensor uses many technologies to collect data about the performance of Java applications. For more information, see Instrumented frameworks and libraries.
Installation
The Java sensor is automatically deployed, configured, and installed by the Instana agent. To ensure your Java applications are instrumented, make sure that your JVM distribution is supported.
Optional configuration
After you install the Instana agent, the Java sensor is automatically installed and configured. Although you do not need any configuration for out-of-the-box metrics and distributed tracing, you can configure individual components of the sensor.
For more information about configuring the sensor, see Java configuration.
Features
After the Java sensor is configured, it automaticlly starts collecting metrics from the JVM. You can view these metrics in the Instana UI. The Java sensor also supports other features of Instana like automatic tracing, custom tracing, and automatic profiling.
Metrics collection
The Java sensor monitors the JVM instance and collects the following metrics from it:
To view these metrics, complete the following steps:
- In the sidebar of the Instana UI, select Infrastructure.
- Click a specific monitored host.
The JVM dashboard displays all the collected metrics for the JVM instance.
Configuration data
| Configuration | Description |
|---|---|
| Java version | The Java version. |
| Java runtime | The Java Runtime Environment (JRE). |
| Maximum heap | Maximum heap size available for the JVM. |
| Class path | The class path parameter set in the JVM. |
Performance metrics
| Performance metrics | Description | Data point |
|---|---|---|
| Memory used | Total memory used by the JVM. The current measured KPI value is displayed. | Byte count is collected from java.lang.Runtime#totalMemory. |
| Threads | Number of threads that are in different states: new, runnable, timed-waiting, waiting, or blocked. The values are displayed on a graph over a selected time period. |
- Current thread-ids are collected from java.lang.management.ThreadMXBean#getAllThreadIds. - Thread states are collected from ThreadMXBean#getThreadInfo. |
| Heap Memory | Maximum heap size available for the JVM. | - Byte count is calculated as java.lang.Runtime#totalMemory - java.lang.Runtime#freeMemory. - The maximum heap size that is displayed in the graph is either determined by parsing the -Xmx command-line parameter or is collected from java.lang.Runtime#maxMemory. - The percentage of heap memory used out of the total heap memory. |
| Memory Pools | Memory pool usage of heap and nonheap pools are displayed on a graph over a selected time period. | - Pool information is collected from ManagementFactory#getMemoryPoolMXBeans. - Graph values are collected from each pool java.lang.management.MemoryUsage.- The maximum value is collected from getMax,
the initial value from getInit, and the current value from getUsage. |
| Garbage Collection | Garbage collection activation and runtime values are displayed on a graph over a selected time period. | - Garbage collection information is collected from ManagementFactory#getGarbageCollectorMXBeans. - Graph values are collected from each collectors java.lang.management.GarbageCollectorMXBean. - Garbage collection runtime is collected from getCollectionTime, which, according to Javadoc, is the approximate elapsed time in milliseconds for accumulated garbage collection. - Invocation count is collected from getCollectionCount.
- Both the getCollectionTime and getCollectionCount values are the calculated differential during 1 second. |
| Suspension | Delay in application execution that is displayed on a graph over a selected time period. | Calculated per the in-app Instana measurement thread. |
Health signatures
Each sensor has a curated knowledge base of health signatures that are evaluated continuously against the incoming metrics. These health signatures are used to raise issues or incidents that depend on user impact.
Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any entity.
For more information about the built-in events for the Java sensor, see the Built-in events reference.
Custom metrics
Instana supports some common Java metrics libraries:
Other metrics
Apart from configuration, performance, and custom metrics, the Java sensor also collects other metrics like live thread dump and heap dump.
Live Thread Dump
To view a live thread dump for the JVM, click Get Thread Dump.
Heap Dump
To create a heap dump for the JVM, click Get Heap Dump. To store the heap dump, indicate a location local to the JVM.
Instana AutoTrace™
By default, the Java sensor monitors all requests and automatically creates a distributed trace for each of them. This distributed trace includes cross host and cross language tracing.
For more information, see Instana AutoTrace™.
Logging
Java Tracer captures only logs that are at level WARN and above.
When Log4j, Log4j2, or Logback is used to enable a more precise correlation of logging and tracing, Instana automatically populates the Mapped Diagnostic Context (MDC) with the trace ID. The MDC variable name is instana.trace.id.
For more information about using the logging frameworks in format strings, see the documentation for your logging framework.
Custom tracing
The Java sensor provides a fully automated out-of-the-box tracing instrumentation. But in some cases, you might prefer to send custom traces to your Instana dashboard. You can use the following methods to implement custom tracing:
- Java Trace SDK
- Configuration-based Java Trace SDK
- Java OpenTracing API
- OpenCensus Instana Trace Exporter
Java Trace SDK
If you want to instrument a framework that is not yet supported by Instana, or monitor the requests of a custom application, use the Java Trace SDK, and view the GitHub repo.
Before you implement custom tracing by using the SDK, see the tracing best practices.
Configuration-based Java Trace SDK
You might encounter situations where using the Java Trace SDK, which requires manipulating the source code or contacting someone who can do that, is not feasible or desirable. In these cases, use the configuration-based Java Trace SDK. Although less feature rich than the programmatic Java Trace SDK, the configuration-based Java Trace SDK allows a declarative configuration of spans and tags that cover many common use-cases.
Before you implement custom tracing by using the configuration-based Java Trace SDK, see the Tracing best practices.
Java OpenTracing API
To collect traces that are described through the OpenTracing API, you must use Java OpenTracing. For more information, see OpenTracing.
Important: Disable automatic tracing (Instana AutoTrace™) before you use the Java OpenTracing API. For more information, see Disabling automatic instrumentation.
OpenCensus Instana Trace Exporter
Instana provides an OpenCensus Trace Exporter for applications that are written in Java. Using the Instana agent processes as proxy, Instana forwards traces that are exported by applications that are instrumented with Census to its backend.
For more information, see the OpenCensus Exporters.
Important: Disable automatic tracing (Instana AutoTrace™) if the agent is used on the same host as Census. For more information, see Disabling automatic instrumentation.
Instana AutoProfile™
Profiles are essential for locating performance hot spots and bottlenecks at the code level. They are instrumental in reducing resource consumption and improving performance.
AutoProfile™ generates and reports process profiles to Instana. Unlike development-time and on-demand profilers, where you must manually initiate profiling, AutoProfile™ automatically schedules and continuously performs profiling appropriate for critical production environments.
For more information, see our Instana AutoProfile™ docs.
Excluding JVMs
You can set the INSTANA_IGNORE environment variable to true in your JVM environment to avoid the attachment of Instana Agent to JVM.
Troubleshooting
You might encounter some monitoring issues with Instana. For more information, see Troubleshooting.