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_name method_name {condition-expression} '{express}' -n {times} -x {depth}

class_name
    Target class name. Use wildcard expression to match multiple classes.

method_name
    Target method name. Use wildcard expression to match multiple methods.

{condition-expression}
    Conditional expression. Only watch when this expression is true. Example: 'params[0].length > 10'.

'{express}'
    OGNL expression to evaluate. It's the expression to watch, surrounded by single quotes. Example: '{params,returnObj,throwExp}'.

-n {times}
    The number of times to watch the method execution.

-x {depth}
    Expand the objects of return value, params, target, or exception with the depth.

arthas-watch is a powerful diagnostic tool for Java applications running in Linux environments.
It allows you to monitor method execution in real-time, view method parameters and return values, and even inspect exceptions thrown during method execution.
This makes it invaluable for troubleshooting performance bottlenecks, understanding application behavior, and debugging complex issues.
The command is part of the Arthas project, providing interactive access to inspect application internals without requiring application restarts or modifications.
arthas-watch can dramatically reduce the time required to diagnose and resolve production issues by offering deep visibility into the inner workings of Java applications.

arthas-watch relies on bytecode instrumentation, which can introduce overhead. Use it judiciously, especially in performance-critical environments. Be mindful of the complexity of OGNL expressions, as poorly crafted expressions can impact performance. Watch expressions that evaluate complex objects or throw exceptions during evaluation can also degrade performance. Make sure your java application security configuration allows bytecode instrumentation.

The OGNL expression context within arthas-watch provides access to several useful objects:
params: An array containing the method's parameters.
target: The target object on which the method is being invoked.
returnObj: The return value of the method.
throwExp: The exception thrown by the method, if any.
These objects allow you to create powerful and flexible watch expressions to monitor specific aspects of method execution.

1. Start with simple watch expressions and gradually increase complexity as needed.
2. Use conditional expressions to narrow down the scope of monitoring and reduce overhead.
3. Be mindful of the depth of object expansion, as deep expansion can impact performance.
4. Regularly review and remove unnecessary watch expressions to minimize the impact on application performance.
5. Consider using arthas-tt for time tunnel which is much more powerful when troubleshooting historical issues.

arthas-watch is part of the Arthas project, an open-source Java diagnostic tool created by Alibaba. It emerged from the need to troubleshoot complex production issues in large-scale Java applications. Initially developed internally, Arthas was later open-sourced to benefit the wider Java community. arthas-watch has been widely adopted by developers and operations teams to diagnose performance bottlenecks, debug application behavior, and understand application internals in real-time without requiring application restarts or redeployments.

arthas-jad(1), arthas-sc(1), arthas-sm(1), arthas-tt(1)