arthas-watch

Observe the first parameter and return value of method, and expand the nested attributes of the object to 4 levels

$ watch [class-pattern] [method-pattern] ['{ params[0],returnObj }'] -x 4

$ watch [class-pattern] [method-pattern] ['{ params[1],returnObj }'] ['"5".equals(params[0])'] -x 4

$ watch [class-pattern] [method-pattern] ['{ params[1].count }'] -e -s

watch class_pattern method_pattern [expression] [condition_expression] [options]

class_pattern: A pattern matching the fully qualified Java class name (e.g., com.example.MyClass, *Service).
method_pattern: A pattern matching the method name within the class (e.g., myMethod, get*).
expression: (Optional) A SpEL expression specifying the data to display. Common variables include params (method arguments), returnObj (return value), throwExp (thrown exception), this (the object instance). Default is {params, returnObj, throwExp}.
condition_expression: (Optional) A SpEL expression that must evaluate to true for the watch event to be captured. This allows filtering based on argument values, return values, or other conditions (e.g., '{params[0].name == "test"}').

class_pattern
    The fully qualified class name or a pattern to match (e.g., com.example.MyClass, *Service).

method_pattern
    The method name within the specified class or a pattern to match (e.g., myMethod, get*).

[expression]
    An optional SpEL expression defining the data to be printed. For example, {params[0], returnObj.name} to print the first argument and the 'name' property of the return object.

[condition_expression]
    An optional SpEL expression that must evaluate to true for the watch event to be triggered. For example, '{params[0] == null}' to watch only when the first argument is null.

-b, --before
    Observe the method before it executes. Default is off.

-s, --success
    Observe the method upon successful return. This is enabled by default if no other observation point is specified.

-e, --exception
    Observe the method when it throws an exception. This is enabled by default if no other observation point is specified.

-f, --finish
    Observe the method upon completion, regardless of success or exception. This is enabled by default if no other observation point is specified.

-x level, --expand level
    Specify the maximum depth to expand objects in the output. A value of 0 means no expansion, 1 shows immediate fields, etc. Default is 1.

-n times, --limit times
    Limit the number of times the watch command will trigger. The command will automatically exit after reaching this limit.

--timeout ms
    Specify a timeout in milliseconds for the command to execute. If the timeout is reached, the command will be terminated.

The watch command is a powerful feature within the Arthas diagnostic tool for Java applications. It allows developers to observe the real-time execution of specified methods, providing deep insights into their arguments, return values, thrown exceptions, and the this object instance. Unlike simply printing logs, watch dynamically instruments the target method at runtime, enabling detailed inspection without modifying source code or restarting the application. This makes it invaluable for debugging complex issues, understanding method behavior, and analyzing performance bottlenecks.

Users can define powerful Spring Expression Language (SpEL) expressions to filter events or extract specific data points, making the output highly customizable and relevant to the task at hand. It supports observation at various points of method execution: before invocation, upon successful return, on exception, or upon completion (whether success or exception).

While arthas-watch is highly efficient, continuous monitoring of frequently called methods or using complex SpEL expressions can introduce a slight performance overhead due to runtime bytecode instrumentation and data processing.
The command operates within the context of the attached JVM; it cannot watch static initializers or constructors directly in the same way as regular methods.
Output can be extensive for deeply nested objects or high-frequency calls, requiring careful use of -x and -n options, and precise condition_expression to manage verbosity.

SpEL (Spring Expression Language) is central to the power of watch. It allows you to programmatically define what data to extract and under what conditions. Key variables available in the watch context include:
params: An array of method arguments.
returnObj: The object returned by the method (available at -s and -f points).
throwExp: The exception thrown by the method (available at -e and -f points).
this: The current object instance (null for static methods).
clazz: The Class object of the current method.
method: The Method object of the current method.
target: Equivalent to this.
cost: The execution time of the method in milliseconds (available at -s, -e, -f points).

The watch command offers fine-grained control over when data is captured:
Before execution (-b): Captures data right before the method's body is executed. Useful for inspecting initial arguments.
On successful return (-s): Captures data when the method returns normally.
On exception (-e): Captures data when the method throws an exception.
On finish (-f): Captures data when the method completes, regardless of whether it returned successfully or threw an exception.
By default, if no specific observation point is selected, watch combines -s, -e, and -f to provide comprehensive insight into method completion, showing return values, exceptions, and execution time.

Arthas itself was open-sourced by Alibaba in 2018, evolving from internal diagnostic tools used to troubleshoot complex Java applications in large-scale production environments. The watch command has been a fundamental and indispensable feature from its early versions, crucial for its ability to provide real-time, non-invasive insights into application behavior. Its development has focused on enhancing flexibility through advanced SpEL support, improving performance, and expanding the range of observable data points, making it a cornerstone for dynamic debugging in the Java ecosystem.

This section refers to commands within the Arthas ecosystem itself, as arthas-watch is a sub-command of the Arthas tool and not a standalone Linux utility in the typical sense of having its own man page., trace: Trace method invocations, showing the call stack and time spent., monitor: Monitor method statistics, including QPS, success/failure count, and average RT., stack: Display the current method's stack trace., tt: Time Tunnel, record method invocations and replay them, allowing for post-mortem debugging.