Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ashutoshiwnl/monarch-java-agent
Monarch-Java-Agent is a powerful Java agent for method monitoring and analysis. It offers various features to track method execution time, print stack traces, log method arguments and return values, capture heap dumps, and gather JVM-related information.
https://github.com/ashutoshiwnl/monarch-java-agent
bytecode-manipulation instrumentation java-agent
Last synced: 16 days ago
JSON representation
Monarch-Java-Agent is a powerful Java agent for method monitoring and analysis. It offers various features to track method execution time, print stack traces, log method arguments and return values, capture heap dumps, and gather JVM-related information.
- Host: GitHub
- URL: https://github.com/ashutoshiwnl/monarch-java-agent
- Owner: AshutoshIWNL
- License: apache-2.0
- Created: 2024-04-11T18:31:49.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2024-10-05T09:27:07.000Z (4 months ago)
- Last Synced: 2024-11-23T08:14:04.749Z (3 months ago)
- Topics: bytecode-manipulation, instrumentation, java-agent
- Language: Java
- Homepage:
- Size: 108 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project
README
# Monarch-Java-Agent
Monarch-Java-Agent is a powerful Java agent for method monitoring and analysis. It offers various features to track method execution time, print stack traces, log method arguments and return values, capture heap dumps, and gather JVM-related information.
## Features
- **Method Execution Time**: Print the time taken for a method's execution.
- **Stack Trace Printing**: Print the stack trace when a certain method is invoked.
- **Argument Logging**: Log the arguments provided to a method.
- **Return Value Logging**: Log the return value of a method.
- **Custom code addition**: Add custom code to a method.
- **Heap Dump Capture**: Take a heap dump when a method is invoked or exits.
- **System Flags Printing**: Print system flags of the target application.
- **JVM Options Printing**: Print JVM options of the target application.
- **JVM Heap Usage Details**: Print JVM heap usage details of the target application.
## Agent Arguments
When attaching the Monarch-Java-Agent, you can pass the following arguments:
- **configFile**: Path to the configuration file that the agent will use. This file contains settings and configurations for the agent's behavior.
- **agentLogFileDir**: Directory where the agent's initialization logging will be written. This log provides insights into the agent's startup process and any initialization-related activities.
- **agentLogLevel**: Specifies the log level for the agent's log messages. Available log levels include DEBUG, INFO, WARN, and ERROR. Adjusting this setting can help manage the verbosity of the agent's log output.
You can find the runtime attach scripts in the attachScript directory.
## Usage
You can attach Monarch-Java-Agent either during startup or during runtime.
**For startup:**
1. Build the agent JAR file.
2. Start your Java application using the `-javaagent` option.
3. Specify the configuration file and other options as needed.
Example command to attach the agent:
```bash
java -javaagent:/path/to/monarch-java-agent.jar=configFile=/path/to/config.yaml,agentLogFileDir=/path/to/log/dir,agentLogLevel=DEBUG YourMainClass
```
**For Runtime:**
1. Build the agent JAR file.
2. Start your application.
3. Run "monarchAgentStart.bat"/"monarchAgentStart.sh" and provide the requested details.
Example command run:
```bash
C:\Users\ashut\monarch-java-agent\attachScript> .\monarchAgentStart.bat
Enter path to the agent JAR file: C:\Users\ashut\monarch-java-agent\target\monarch-java-agent-1.0-SNAPSHOT.jar
Enter path to the agent config file: C:\Users\ashut\monarch-java-agent\sampleConfig\mConfig.yaml
Enter arguments to pass to the agent: agentLogFileDir=C:\Users\ashut\manualTesting,agentLogLevel=DEBUG
Enter PID of the target JVM (press Enter to use current JVM): 24300
Agent attached successfully to PID 24300
```
## Configuration
Below is a sample configuration YAML that you can use with Monarch-Java-Agent:
```yaml
shouldInstrument: true
configRefreshInterval: 15
traceFileLocation: C:\\TraceDumps
agentRules:
- ClassA::methodA@ENTRY::STACK
- ClassA::methodA@ENTRY::ARGS
- ClassA::methodA@EXIT::RET
- ClassA::methodB@ENTRY::ARGS
- ClassA::methodB@ENTRY::STACK
- ClassA::methodB@EXIT::STACK
- ClassA::methodB@EXIT::RET
- ClassB::methodC@PROFILE
- ClassB::methodC@ENTRY::HEAP
- ClassB::methodC@ENTRY::ADD::[System.out.println(20);]
- ClassA::methodA@ENTRY::ADD::[System.out.println(this.getClass().getName());]
- ClassA::methodA@AT(11)::ADD::[System.out.println(499);]
- ClassA::methodA@AT(11)::ADD::[System.out.println(499 + "," + "Ashutosh");]
printClassLoaderTrace: true
printJVMSystemProperties: true
printEnvironmentVariables: true
printJVMHeapUsage: true
maxHeapDumps: 3
```
## Rule Syntax
The rule syntax for Monarch-Java-Agent follows the format:
```plaintext
::@::
```
Where:
- ``: Fully Qualified Class Name.
- ``: Name of the method.
- ``: Event at which the action should be performed. Possible values are:
- ENTRY
- EXIT
- AT
- PROFILE (Note: PROFILE is a special case and no ACTION is required along with it.)
- ``: Action to be performed. Possible values are:
- STACK: Print stack trace.
- HEAP: Capture heap dump.
- ARGS: Log method arguments.
- RET: Log method return value.
- ADD: Add custom code.
# Author
- **Ashutosh Mishra** (https://github.com/AshutoshIWNL)
# License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.