arthas-trace

Trace method invoke chain

$ trace [class-pattern] [method-pattern]

$ trace [class-pattern] [method-pattern] '#cost > [10]'

$ trace -E [class-pattern1]|[class-patter2] [method-pattern1]|[method-pattern2]|[method-pattern3]

$ trace [class-pattern] [method-pattern] '#cost > [10]' -n 5

trace <class_pattern> <method_pattern> [condition_expression] [options]

<class_pattern>
    The pattern for the class name(s) to trace (e.g., com.example.MyClass, *Service). Supports glob patterns.

<method_pattern>
    The pattern for the method name(s) to trace within the specified class(es) (e.g., myMethod, *Bean). Supports glob patterns.

[condition_expression]
    An OGNL expression used to filter trace triggers based on method parameters, return values, or other contextual data (e.g., params[0].id == 1).

--skipJDKMethod
    A flag to ignore tracing calls to methods belonging to JDK internal classes, simplifying the trace output.

--depth <value>
    Sets the maximum recursion depth for tracing method calls. A value of -1 (default) means unlimited depth.

--maxTimes <value>
    Specifies the maximum number of times the trace will trigger before automatically stopping. Useful for limiting output.

--threshold <value>
    Filters the output to only display method calls whose execution time exceeds the specified threshold (in milliseconds). Helps pinpoint slow operations.

--excludeMethods <method_pattern>
    Excludes specific method(s) from being traced, even if they match the primary method_pattern.

--excludeClassMethods <class_pattern#method_pattern>
    Excludes specific methods of specific classes from tracing.

--regex
    Interprets class_pattern and method_pattern as regular expressions instead of glob patterns.

The trace command is an internal command of the Arthas diagnostic tool, a powerful Java diagnostic utility used for troubleshooting production issues without restarting applications. Unlike traditional Linux shell commands, trace is executed within the Arthas console after attaching Arthas to a running Java process. Its primary function is to trace method invocations and calculate their execution duration, showing the time spent in each sub-call. This allows developers and SREs to quickly pinpoint performance bottlenecks within specific method call stacks. It supports various options to filter methods, set trace depth, and define execution thresholds, making it highly versatile for detailed performance analysis and debugging in complex Java applications. The output provides a clear, hierarchical view of method calls with their respective execution times, helping to identify slow points efficiently. It's a key tool for understanding runtime behavior and optimizing Java applications.

arthas-trace is an Arthas internal command, not a direct Linux shell command. It requires Arthas to be attached to a running Java process.
It can incur performance overhead, especially with high-frequency methods or deep tracing, potentially impacting the traced application. Use with caution in production environments.
Effective use requires understanding of Arthas OGNL expressions for advanced filtering.
Output can be verbose for complex or deeply nested call stacks, requiring careful analysis.

The trace command will automatically stop after --maxTimes triggers or when the Arthas session is terminated. It can also be manually stopped at any time by pressing Ctrl+C in the Arthas console.

The output displays method calls hierarchically, with indentation representing call depth. The time next to each method indicates its execution duration. A +--- prefix often indicates a sub-call or a child method invocation within the traced method, providing a visual representation of the call stack.

Arthas, and consequently its trace command, was open-sourced by Alibaba in 2018. It quickly gained popularity as a powerful diagnostic tool for Java applications, addressing a common need for real-time troubleshooting without requiring application restarts. The trace command, being fundamental for performance analysis and bottleneck identification, has been a core feature from early versions, continuously evolving with improvements in filtering capabilities, performance, and output clarity to better support complex Java ecosystems and production environments.