Monitoring Java virtual machine (JVM)
You can comprehensively monitor your Java virtual machine (JVM) with Instana to identify bottlenecks and optimize performance. To monitor JVM, install the Instana host agent. After you install the agent, the Instana Java sensor automatically activates, collecting real-time metrics and tracing data that you can view in the Instana UI.
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
The Java sensor supports the following languages, operating systems and runtimes:
Supported languages
The sensor 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 distributions and runtimes
For information about supported Java distributions and runtimes, see System requirements.
Supported frameworks and libraries for tracing
The Java sensor instruments several frameworks and libraries for tracing. For more information, see Instrumented frameworks and libraries.
System requirements
Before you install the Instana agent, ensure the necessary system requirements are met. For more information, see System requirements.
Installing the Instana agent
To monitor JVM, you must install the Instana host agent. For more information, see Installing host agents. The agent automatically deploys, configures, and installs the Java sensor. To ensure that your Java applications are instrumented, make sure that your JVM distribution is supported.
Do not attempt to use agents from multiple vendors at the same time. You might encounter unpredictable results that might lead to application failure. For more information, see Incompatible agents.
Excluding JVMs from monitoring
To avoid the attachment of the Instana agent to a JVM, you can set the INSTANA_IGNORE environment variable to true in your JVM environment.
Optional: Configuring the sensor
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.
After the Java sensor is configured, it automatically 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
The following table lists the configuration data that is collected from the JVM instance:
| 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
The following table lists the performance metrics data that is collected from the JVM instance:
| 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. If you use the following libraries, you can manually instrument your application code to collect custom metrics:
For more information, see Custom tracing.
Other metrics
Apart from configuration, performance, and custom metrics, the Java sensor also collects other metrics, such as 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.
Tracing Java applications
The Java sensor in Instana uses the following methods to trace Java applications:
- Instana AutoTrace: Automatic tracing of Java applications without requiring manual configuration or code changes.
- Custom tracing: Manual instrumentation of specific parts of the Java application code to capture custom metrics and gain deeper insights.
- Instana AutoProfile: Automatic profiling of Java applications provides detailed information about performance, CPU usage, memory allocation, and other system resources.
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™.
You can view these traces in the Instana UI. For more information, see Analyzing traces and calls.
Logging
You can view only logs that are at level WARN and later.
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.
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. By using the Instana agent processes as a proxy, Instana forwards traces that are exported by applications that are instrumented with Census to its backend.
For more information, see the OpenCensus Exporters.
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.
Instana 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.
For more information, see Instana AutoProfile™.
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.