[Upgrade] ARMS Application Monitoring Agent 4.x

Changes and impacts

• By default, method instrumentation for Spring-managed beans is disabled. The agent now only instruments controller methods.

  Potential risks:

  • After upgrading, methods in classes annotated with @Service or @Component will no longer appear in traces.

  • Exceptions thrown from methods in classes annotated with @Service or @Component will not be captured.

• The metric names for thread pool monitoring and connection pool monitoring have changed. For details, see Thread pool and connection pool monitoring.

  Potential risks:

  • If you have configured alert rules for thread pool monitoring in Application Monitoring, you must reconfigure them.

    On the Create Application Monitoring Alert Rule page, set Metric Type to Thread_Pool_Version_2.

  • If you have a custom dashboard that uses thread pool metrics, it will show no data.

  • The increase in metric volume may lead to higher pay-as-you-go costs.

• The metric for monitoring message delay has been renamed to arms_mq_delay_seconds.

  Potential risk: If you have a custom dashboard that uses this metric, it will show no data.

• The agent now automatically propagates trace context for asynchronous calls, eliminating the need to configure package names.

• You no longer need to define custom consumers for RabbitMQ or custom consumption methods for Kafka. Existing definitions are not affected.

• Obtaining the trace ID by using MDC.get("EagleEye-TraceID") is no longer supported. However, log-to-trace ID correlation is not affected.

  Potential risk: The trace ID retrieved by using MDC.get("EagleEye-TraceID") will be null.

• Internal calls without an entry point now generate a span.

  Potential risk: The increased number of spans may lead to higher pay-as-you-go costs.

• The agent now calculates quantile statistics using a bucket distribution method based on linear interpolation, replacing the previous Prometheus Summary-based algorithm.

  Potential risk: Quantile metrics may become inaccurate if the actual duration distribution differs significantly from the current bucketing.

• The SpanStatus now aligns with the OpenTelemetry standard. In this standard, HTTP requests with a 4xx or 5xx response code are marked as error. All other cases are marked as unset. Previous agent versions marked these other cases as ok.

• After upgrading to the 4.x agent, the trace ID must be 32 characters long. This format is incompatible with the legacy Browser Monitoring feature. We recommend integrating with the new Real User Monitoring service.

• Agent versions 4.1.12 and earlier are not compatible with the virtual threads feature in JDK 21. Full compatibility is planned for the 4.3.x release. If your application depends heavily on virtual threads, we recommend staying on a 3.x agent version.

• For applications that use arms-sdk to add baggage via a spring-cloud-gateway filter, baggage propagation fails when you upgrade to agent 4.2.x and enable the spring-bean plugin in custom configuration.

Increased data reporting in 4.x

After upgrading from a 3.x agent to a 4.x agent, you may notice an increase in reported metric volume in certain scenarios. This increase is due to the following changes:

• The agent now creates spans for internal calls without an entry point, which increases the number of reported spans and metrics.

• The agent now supports more custom thread pools in thread pool monitoring, which increases the number of reported metrics.

• The agent now supports more connection pool types in connection pool monitoring, which increases the number of reported metrics.

• For asynchronous calls, the number of upstream and downstream metrics increases because the 4.x agent automatically propagates the trace context.

• The agent now provides broader support for plugins, such as extended instrumentation for Lettuce, which results in more reported metrics.

• To improve the performance of thread profiling in applications with a high thread count, the 4.x agent adjusts how data is collected and stored. Compared to the 3.x agent, enabling thread profiling now reports a small number of additional metrics prefixed with arms_grouped_thread. To disable this feature, see Thread Profiling.

• For batch message consumption in a message queue (MQ), the agent now creates a separate span for each message in a batch, instead of one span for the entire batch. This can significantly increase the number of reported spans if batches contain many messages. This is an intended change that provides more granular data. If data volume is a concern, consider adjusting the sampling rate or disabling the relevant MQ plugin.