DOCSEARCHbyAlgolia
Submit Docs

Arthas Java Diagnostic Tool

repository·master·Indexed 12 days ago

https://github.com/alibaba/arthas

An open-source Java diagnostic tool by Alibaba that allows developers to troubleshoot production issues on-the-fly without modifying code or restarting the JVM. It includes a wide array of tools for JVM monitoring, classloader diagnosis, and method tracing, as well as an experimental MCP (Model Context Protocol) server for AI agent integration.

Tokens
168.7K
Snippets
638
Records
863
Agent score
98%

What's inside Arthas

  1. Overview of the Arthas Http API

    master

    The Arthas Http API provides a RESTful-like interactive interface using JSON for both requests and responses. Unlike the unstructured text output from Telnet or the WebConsole, the Http API provides structured data, making it suitable for complex diagnostic automation and application scenarios.

    Access Details

    • Endpoint: http://ip:port/api
    • Method: All requests must use POST.
    • Recommended Port: Use the HTTP port 8563. Avoid the telnet port 3658 if accessing via Chrome due to compatibility issues.

  2. Overview of arthas-mcp-server

    master

    The arthas-mcp-server is an experimental module for Arthas that implements a server based on the Model Context Protocol (MCP) (version 2025-03-26). It provides a unified JSON-RPC 2.0 interface via HTTP/Netty, allowing AI agents to execute Arthas diagnostic commands using tool-calling capabilities.

    The server integrates 26 core diagnostic tools categorized into three main groups:

    JVM Related Tools

    • dashboard: Real-time JVM/application dashboard.
    • heapdump: Generates JVM heap dump files (supports --live for live objects only).
    • jvm: Views current JVM information.
    • mbean: Views or monitors MBean attributes.
    • memory: Views JVM memory information.
    • thread: Views thread information and stacks (supports finding blocked or busiest threads).
    • sysprop: Views or modifies system properties.
    • sysenv: Views system environment variables.
    • vmoption: Views or updates VM options.
    • perfcounter: Views JVM performance counters.
    • vmtool: Virtual machine tools (force GC, get instances, interrupt threads, etc.).
    • getstatic: Views static field values of a class.
    • ognl: Executes OGNL expressions to dynamically call methods and access fields.

    Class/ClassLoader Related Tools

    • sc: Views loaded class information.
    • sm: Views loaded class method information.
    • jad: Decompiles loaded classes into Java source code.
    • classloader: Diagnoses ClassLoaders (statistics, inheritance trees, URLs).
    • mc: Memory compiler (compiles Java source to bytecode).
    • redefine: Redefines classes using external .class files.
    • retransform: Triggers class retransformation and bytecode enhancement.
    • dump: Exports actual running class bytecode to a directory.

    Monitoring and Diagnostic Tools

    • monitor: Real-time monitoring of specific method calls.
    • stack: Outputs the call stack for the current method.
    • trace: Traces internal method call paths with timing information and filtering.
    • tt: Time Tunnel; records method call arguments and return values for later replay.
    • watch: Observes method calls, including arguments, return values, and exceptions.

  3. What is Arthas

    master

    Arthas is a Java diagnostic tool designed for troubleshooting issues in production environments for Java-based applications. It allows developers to diagnose problems on the fly without modifying code or restarting servers.

    Key characteristics include:

    • Non-intrusive: It works as an observer and never suspends running threads, preventing service downtime.
    • Production-ready: Designed to solve issues that are difficult to reproduce in test/staging environments or that disappear upon JVM restart.
    • Cross-platform: Supports Linux, Mac, and Windows.
    • JDK Compatibility: Supports JDK 8+ (including JDK 17, 21, and 25).

  4. Overview of Arthas Java Diagnostic Tool

    master

    Arthas is an online monitoring and diagnostic tool for Java applications. It provides a global view of application load, memory, GC, and thread status in real-time.

    Key capabilities include:

    • Non-intrusive Diagnosis: Diagnose business issues without modifying application code or restarting the JVM.
    • Method Inspection: View input/output parameters and exceptions of method calls.
    • Performance Monitoring: Monitor method execution time and identify application hotspots.
    • Class Inspection: View class loading information and locate which JAR package a class is loaded from.
    • Instance Lookup: Find specific class instances directly within the JVM.
    • Flame Graphs: Quickly locate application hotspots by generating flame graphs.

    Arthas operates as an observer and does not pause running threads, making it safe for use in production environments where traditional IDE remote debugging is unacceptable.

  5. Overview of advanced Arthas features

    master

    Arthas provides several advanced capabilities for deep diagnostics and integration:

    • Background Async Tasks: Run detection commands in the background and save results to logs for issues that occur at unpredictable times.
    • Log Persistence: All execution records are saved to log files for later analysis.
    • Arthas Tunnel: Remote management and connection to multiple Java services via a Tunnel Server/Client.
    • HTTP API: Provides structured data for custom UI integration.
    • Batch Support: Run multiple commands at once using custom scripts, which can be combined with --select to target specific processes.
    • Integration Options:
      • Java Agent: Start Arthas as a java agent.
      • Spring Boot Starter: Start Arthas automatically with your Spring Boot application.
      • IDEA Plugin: Faster command construction within IntelliJ IDEA.
      • External Commands: Load custom command JARs to extend Arthas functionality.

  6. Key features of Arthas

    master

    Arthas provides several diagnostic capabilities for Java applications:

    • Dashboard: Real-time monitoring of system running status.
    • Parameter/Return Value/Exception Inspection: Inspect function call arguments, return values, and exceptions.
    • Online Hot Patching: Perform code hot updates using jad, sc, and redefine.
    • Class Conflict Resolution: Quickly resolve class conflicts and locate class loading paths.
    • Performance Hotspot Detection: Rapidly locate application hotspots and generate flame graphs.
    • WebConsole: Perform online diagnostics via a web-based interface.

  7. What is the tt (TimeTunnel) command

    master

    The tt (TimeTunnel) command acts as a 'time tunnel' for method execution data. It records the input parameters, return values, and thrown exceptions for every invocation of a specified method.

    Unlike the watch command, which requires you to pre-define an observation expression, tt captures all available data for a period of time. This makes it ideal for troubleshooting when you are unsure of the exact cause of an issue and need to observe the full context of method calls over time.

  8. Use OGNL expression variables with `line`

    master

    The line command uses the Arthas OGNL expression mechanism. When evaluating expressions at a line probe, you can use the following variables:

    VariableDescription
    paramsMethod argument array.
    targetCurrent object (null for static methods).
    clazzCurrent class.
    methodCurrent method information.
    lineNumberThe matched source line number.
    argNamesMethod argument name array (requires debug metadata).
    localVars / localsLocal variable value array visible at the current line.
    localVarNamesLocal variable name array visible at the current line.
    localVarMapMap from local variable name to value.
    #costElapsed time from method entry to the current line (ms).

    Note: Local variable visibility (localVarMap, locals, etc.) depends on the target bytecode retaining LocalVariableTable debug metadata. If the class lacks this metadata, these maps may be empty or incomplete.

  9. General Principles for Using Arthas

    master

    When using Arthas for online Java application diagnosis, follow these safety and methodology principles:

    • Risk Management: Start with low-risk, read-only commands to collect information before using more invasive commands.
    • Limit Execution: All commands that intercept method calls, such as watch, trace, tt, and stack, must include the -n flag to limit the number of executions. This prevents excessive pressure on the production application.
    • Evidence-Based Conclusion: When reporting findings, always include key evidence (command output summaries) and provide clear next steps.

  10. Use OGNL expressions in trace conditions

    master

    The condition-express parameter supports full OGNL (Object-Graph Navigation Language) grammar. This allows you to create complex conditional traces based on method parameters, return values, or other object states.

    Example: trace com.example.MyClass myMethod "params[0] < 0" will only trace calls where the first parameter is less than zero.

  11. Manage Session IDs in the Web Console

    master

    Some Arthas commands require a sessionID to maintain state, while others do not.

    • Automatic Handling: In the current version, you generally do not need to manually manage the sessionID during normal use.
    • Manual Control: If necessary, you can manually obtain or destroy a sessionID by clicking the buttons located in the top-right corner of the interface.

  12. Directory scanning rules for external commands

    master

    When pointing to a directory for external commands, Arthas follows these rules:

    • It scans only the immediate directory for *.jar files; it does not scan subdirectories recursively.
    • Duplicate JAR paths are removed based on their normalized absolute paths.
    • If your external command depends on third-party libraries, you must either bundle them into the command JAR or place the dependency JARs in the same scanned directory.