{"id":21466430,"url":"https://github.com/ashutoshiwnl/monarch-java-agent","last_synced_at":"2025-03-17T05:47:36.049Z","repository":{"id":276609386,"uuid":"929725998","full_name":"AshutoshIWNL/monarch-java-agent","owner":"AshutoshIWNL","description":"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.","archived":false,"fork":false,"pushed_at":"2025-02-09T11:27:40.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-09T12:20:43.772Z","etag":null,"topics":["application-monitoring","bytecode-manipulation","instrumentation-agent","java-agent"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AshutoshIWNL.png","metadata":{},"created_at":"2025-02-09T08:38:43.000Z","updated_at":"2025-02-09T11:27:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"787b1545-3eb5-4d99-a868-9d558003e24f","html_url":"https://github.com/AshutoshIWNL/monarch-java-agent","commit_stats":null,"previous_names":["ashutoshiwnl/monarch-java-agent"],"tags_count":null,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AshutoshIWNL%2Fmonarch-java-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AshutoshIWNL%2Fmonarch-java-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AshutoshIWNL%2Fmonarch-java-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AshutoshIWNL%2Fmonarch-java-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AshutoshIWNL","download_url":"https://codeload.github.com/AshutoshIWNL/monarch-java-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243982136,"owners_count":20378606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-monitoring","bytecode-manipulation","instrumentation-agent","java-agent"],"created_at":"2024-11-23T08:14:07.689Z","updated_at":"2025-03-17T05:47:36.038Z","avatar_url":"https://github.com/AshutoshIWNL.png","language":"Java","readme":"# Monarch-Java-Agent\n\nMonarch-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.\n\n## Features\n\n- **Method Execution Time**: Print the time taken for a method's execution.\n- **Stack Trace Printing**: Print the stack trace when a certain method is invoked.\n- **Argument Logging**: Log the arguments provided to a method.\n- **Return Value Logging**: Log the return value of a method.\n- **Custom code addition**: Add custom code to a method.\n- **Heap Dump Capture**: Take a heap dump when a method is invoked or exits.\n- **System Flags Printing**: Print system flags of the target application.\n- **JVM Options Printing**: Print JVM options of the target application.\n- **JVM Heap Usage Details**: Print JVM heap usage details of the target application.\n\n## Agent Arguments\n\nWhen attaching the Monarch-Java-Agent, you can pass the following arguments:\n\n- **configFile**: Path to the configuration file that the agent will use. This file contains settings and configurations for the agent's behavior.\n- **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.\n- **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.\n\nYou can find the runtime attach scripts in the attachScript directory.\n\n\n## Usage\n\nYou can attach Monarch-Java-Agent either during startup or during runtime.\n\n**For startup:**\n\n1. Build the agent JAR file.\n2. Start your Java application using the `-javaagent` option.\n3. Specify the configuration file and other options as needed.\n\nExample command to attach the agent:\n\n```bash \njava -javaagent:/path/to/monarch-java-agent.jar=configFile=/path/to/config.yaml,agentLogFileDir=/path/to/log/dir,agentLogLevel=DEBUG YourMainClass\n```\n\n**For Runtime:**\n\n1. Build the agent JAR file.\n2. Start your application.\n3. Run \"monarchAgentStart.bat\"/\"monarchAgentStart.sh\" and provide the requested details.\n\nExample command run:\n```bash \nC:\\Users\\ashut\\monarch-java-agent\\attachScript\u003e .\\monarchAgentStart.bat\nEnter path to the agent JAR file: C:\\Users\\ashut\\monarch-java-agent\\target\\monarch-java-agent-1.0-SNAPSHOT.jar\nEnter path to the agent config file: C:\\Users\\ashut\\monarch-java-agent\\sampleConfig\\mConfig.yaml\nEnter arguments to pass to the agent: agentLogFileDir=C:\\Users\\ashut\\manualTesting,agentLogLevel=DEBUG\nEnter PID of the target JVM (press Enter to use current JVM): 24300\nAgent attached successfully to PID 24300\n```\n\n## Configuration\n\nBelow is a sample configuration YAML that you can use with Monarch-Java-Agent:\n\n```yaml\nshouldInstrument: true\nconfigRefreshInterval: 15\ntraceFileLocation: C:\\\\TraceDumps\nagentRules:\n  - ClassA::methodA@ENTRY::STACK\n  - ClassA::methodA@ENTRY::ARGS\n  - ClassA::methodA@EXIT::RET\n  - ClassA::methodB@ENTRY::ARGS\n  - ClassA::methodB@ENTRY::STACK\n  - ClassA::methodB@EXIT::STACK\n  - ClassA::methodB@EXIT::RET\n  - ClassB::methodC@PROFILE\n  - ClassB::methodC@ENTRY::HEAP\n  - ClassB::methodC@ENTRY::ADD::[System.out.println(20);]\n  - ClassA::methodA@ENTRY::ADD::[System.out.println(this.getClass().getName());]\n  - ClassA::methodA@AT(11)::ADD::[System.out.println(499);]\n  - ClassA::methodA@AT(11)::ADD::[System.out.println(499 + \",\" + \"Ashutosh\");]\nprintClassLoaderTrace: true\nprintJVMSystemProperties: true\nprintEnvironmentVariables: true\nprintJVMHeapUsage: true\nmaxHeapDumps: 3\n```\n\n## Rule Syntax\n\nThe rule syntax for Monarch-Java-Agent follows the format:\n\n```plaintext\n\u003cFQCN\u003e::\u003cMethodName\u003e@\u003cEVENT\u003e::\u003cACTION\u003e\n```\n\nWhere:\n\n- `\u003cFQCN\u003e`: Fully Qualified Class Name.\n- `\u003cMethodName\u003e`: Name of the method.\n- `\u003cEVENT\u003e`: Event at which the action should be performed. Possible values are:\n    - ENTRY\n    - EXIT\n    - AT\n    - PROFILE (Note: PROFILE is a special case and no ACTION is required along with it.)\n- `\u003cACTION\u003e`: Action to be performed. Possible values are:\n    - STACK: Print stack trace.\n    - HEAP: Capture heap dump.\n    - ARGS: Log method arguments.\n    - RET: Log method return value.\n    - ADD: Add custom code.\n\n\n# Author\n\n- **Ashutosh Mishra** (https://github.com/AshutoshIWNL)\n\n# License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashutoshiwnl%2Fmonarch-java-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashutoshiwnl%2Fmonarch-java-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashutoshiwnl%2Fmonarch-java-agent/lists"}