|
1 |
| -# BSc Dissertation Project - University of Manchester - Non-intrusive JVM agents for capturing the internal state of live production applications |
| 1 | +# BSc Dissertation Project - University of Manchester - Non-intrusive JVM agents for capturing the internal state of live production applications |
2 | 2 |
|
3 | 3 | [](https://github.com/nenuadrian/c-java-native-interface-agent-stack-trace-heap-capture/actions/workflows/cmake-single-platform.yml)
|
4 | 4 | [](https://github.com/nenuadrian/bsc-dissertation-c-java-native-interface-agent-stack-trace-heap-capture/actions/workflows/main.yml)
|
5 | 5 |
|
6 | 6 | ## Overview
|
7 |
| -This repository contains the implementation of a C JNI Agent designed to recursively capture the values of objects within methods on a stack trace. |
8 | 7 |
|
9 |
| - |
10 |
| - |
11 |
| -## Prerequisites |
12 |
| -To utilize this agent, you need to install the following libraries: |
13 |
| -- `libxml2` |
14 |
| -- `crypto` |
15 |
| -- `openssl` |
| 8 | +This project implements a non-intrusive JVM agent capable of capturing the internal state of live production applications. The agent is written in C and utilizes the Java Native Interface (JNI) to interact with the Java Virtual Machine (JVM). It recursively captures the values of objects within methods on a stack trace, providing valuable debugging information without impacting application performance. [cite: 23, 24, 25, 55, 56, 57] |
16 | 9 |
|
17 |
| -## Installation and Usage |
18 |
| -1. **Building the JNI Agent**: |
19 |
| - Compile the JNI agent and generate the library files. |
20 |
| - |
21 |
| -2. **Running with Java**: |
22 |
| - Incorporate the resulting library files using the Java command's `-agentpath` flag. |
| 10 | + |
23 | 11 |
|
24 |
| -## Scala Spray Server Integration |
25 |
| -This agent interfaces with a basic Scala Spray server to record captured values in MongoDB. |
| 12 | +## Key Features |
26 | 13 |
|
27 |
| -### Configuration |
28 |
| -- Modify the `src/main/resources/application.conf` file to configure the server settings. |
29 |
| -- Build and run the server using `sbt run`. |
| 14 | +* **Non-intrusive:** The agent operates independently of the JVM, minimizing performance overhead and avoiding any interference with the application's normal execution. |
| 15 | +* **Cross-Platform Compatibility:** The agent is designed to be compatible with various operating systems, including macOS, Windows, and Linux. |
| 16 | +* **Recursive Object Capture:** The agent can recursively capture the values of objects on the heap, providing a comprehensive snapshot of the application's state at the time of an exception. |
| 17 | +* **Efficient Data Handling:** The agent employs data compression techniques to reduce the amount of data transmitted and stored, improving efficiency and minimizing resource usage. |
30 | 18 |
|
31 |
| -## FuelPHP Dashboard |
| 19 | +## Technologies Used |
32 | 20 |
|
33 |
| - |
| 21 | +* **JNI (Java Native Interface):** Enables the C agent to interact with the JVM and access its internal state. |
| 22 | +* **JVMTI (JVM Tool Interface):** Provides additional capabilities for monitoring and debugging the JVM. |
| 23 | +* **Scala:** Used to implement the API server, which handles data communication between the agent and the dashboard. |
| 24 | +* **Spray:** A Scala library used for building RESTful APIs, facilitating communication between the agent and the dashboard. |
| 25 | +* **MongoDB:** A NoSQL database used for storing the captured data. |
| 26 | +* **FuelPHP:** A PHP framework used to develop the dashboard for visualizing and exploring the captured data. |
| 27 | +* **Miniz:** A data compression library used to optimize data transfer and storage. |
| 28 | +* **OpenSSL:** A cryptography library used for data encryption and security. |
34 | 29 |
|
35 |
| -A FuelPHP dashboard displays the analysis results by communicating with the Scala Spray server. |
| 30 | +## Installation and Usage |
36 | 31 |
|
37 |
| -### Setup |
38 |
| -- Perform `composer install` to set up the FuelPHP dashboard. |
| 32 | +Refer to the project's README for detailed instructions on building and deploying the agent, API server, and dashboard. |
39 | 33 |
|
40 | 34 | ## Note
|
41 |
| -This implementation serves as a Minimum Viable Product (MVP). It is not stable, secure, or optimized. However, relevant code snippets can be extracted and used, especially those demonstrating communication with the JNI. |
| 35 | + |
| 36 | +This implementation is a Minimum Viable Product (MVP) and is not intended for production use without further development and hardening. |
42 | 37 |
|
43 | 38 | ## Disclaimer
|
44 |
| -This was academic research, and no guarantees or maintenance are provided. |
45 | 39 |
|
46 |
| -# Cite |
| 40 | +This project was developed as part of academic research. No guarantees or maintenance are provided. |
| 41 | + |
| 42 | +## Cite |
47 | 43 |
|
48 | 44 | ```
|
49 | 45 | @article{jniAgents,
|
|
0 commit comments