Skip to main content

Attach Installation Guide

Important Notes​

Please do not mount probes during business peak hours. When mounting probes, applications may experience brief Safepoints, which will affect business processing.

  • Jetty9.4.16 / 9.4.17 may experience deadlock issues, temporary use not recommended

  • If you are using Java 8, please upgrade to Java 8 1.8.0_231 or higher. In versions before Java 8 1.8.0_231, there are many known issues related to class Retransform. Therefore, you must upgrade to a higher version as some crash issues have been fixed.

  • When starting applications in Debug mode, after mounting and then unmounting probes, the application may crash with the following error:

JDWP exit error AGENT_ERROR_INVALID_EVENT_TYPE(204): ExceptionOccurred [eventHelper.c:834]
FATAL ERROR in native method: JDWP ExceptionOccurred, jvmtiError=AGENT_ERROR_INVALID_EVENT_TYPE(204)

  • Mounting probes will have a certain impact on the startup time of the application, and the startup time of the SpringBoot application will be increased by about 10%.

  • When deploying probes via attach on containers, Dispatcher Version and Dispatcher are not collected

  • When deploying probes in mount mode, Resin 4.0.12, RESTEasy, CompletableFuture occasionally incompatible

  • When deploying probes in mount mode, Jedis plugin is compatible but cannot collect Jedis data [occasional]

  • New versions of Java Agent do not support Java Agent API in mount mode

Technical Advantages​

Mounting probes is implemented through JavaAgent Attach technology, which brings multiple advantages such as high real-time performance, flexibility, and adaptability. Especially the feature of dynamically mounting probes during Java application runtime without restarting the application makes monitoring more convenient in production environments. The same technical principle also makes it possible to unload probes while the application is running normally. The probe can automatically restore bytecode without affecting the application's business processing logic. This flexible and automated unloading process makes maintenance of the monitoring system more convenient. Maintainers can dynamically mount or unload probes according to actual needs to achieve precise control of application performance and behavior. The feasibility and effectiveness of this operation provide higher operability for monitoring system optimization and customization.

Prerequisites​

  • Before installing the probe, please install Agent Collector first.
  • Before installing the probe, ensure that the local browser time is consistent with the server timezone and time. If there are multiple servers, ensure that the local browser, multiple servers' timezones and times are all consistent. Otherwise, it may affect data accuracy, such as incorrect topology.
  • For private deployment environments, please ensure the platform has UniAgent 4.3.0.0+
  • Applications that have installed probes through -javaagent method do not support mount/unmount operations
  • Applications mounting probes need available heap space greater than 500MB
  • Applications mounting probes need available metaspace (permanent generation) greater than 50MB
  • On OpenJDK, Oracle HotSpot, please ensure the tools.jar file is available in the runtime of each monitored JVM. This file is located at $JAVA_HOME/lib/tools.jar.

Mounting Probes​

  • Deploy UniAgent, please refer to UniAgent>Auto Deployment for deployment method
  • In the light application list, select the UniAgents Management page to find the host deploying the probe, click the host to view the process list on the host, click the concerned process in the process list, and select Enable in the Operations on the right to mount the probe at runtime

Unmounting Probes​

  • For applications that have mounted probes, you can find the host deploying the probe in the UniAgents Management page, click the host to view the process list on the host, click the concerned process in the process list, and click the Unmount button on the right to unmount the probe at runtime
  • Only supports unmount operations for applications that installed probes using mount operation, for applications installed probes in other ways, please use disable operation

Support List​

The following is the list supported by mounting probes. If the application environment does not meet the following support list, please use manual installation methods.

JVM​

NameSupported VersionNotes
Open JDK1.7 ~ 22JDK8 versions below 8u231 are not supported
Oracle Hotspot JVM1.7 ~ 22JDK8 versions below 8u231 are not supported

Operating System​

NameSupported VersionNotes
Linux3.10+Does not support Java applications in Alpine Linux containers, does not support Java applications with Selinux or AppArmor enabled