Skip to content

Commit afae5c2

Browse files
authored
Update README.md
1 parent 18c6f52 commit afae5c2

File tree

1 file changed

+24
-28
lines changed

1 file changed

+24
-28
lines changed

README.md

Lines changed: 24 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,45 @@
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
22

33
[![CMake on a single platform](https://github.com/nenuadrian/c-java-native-interface-agent-stack-trace-heap-capture/actions/workflows/cmake-single-platform.yml/badge.svg)](https://github.com/nenuadrian/c-java-native-interface-agent-stack-trace-heap-capture/actions/workflows/cmake-single-platform.yml)
44
[![LaTeX Build](https://github.com/nenuadrian/bsc-dissertation-c-java-native-interface-agent-stack-trace-heap-capture/actions/workflows/main.yml/badge.svg)](https://github.com/nenuadrian/bsc-dissertation-c-java-native-interface-agent-stack-trace-heap-capture/actions/workflows/main.yml)
55

66
## 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.
87

9-
![design](DISSERTATION/end-design.png)
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]
169

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+
![design](DISSERTATION/end-design.png)
2311

24-
## Scala Spray Server Integration
25-
This agent interfaces with a basic Scala Spray server to record captured values in MongoDB.
12+
## Key Features
2613

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.
3018

31-
## FuelPHP Dashboard
19+
## Technologies Used
3220

33-
![dashboard](DISSERTATION/dashboard-app.png)
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.
3429

35-
A FuelPHP dashboard displays the analysis results by communicating with the Scala Spray server.
30+
## Installation and Usage
3631

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.
3933

4034
## 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.
4237

4338
## Disclaimer
44-
This was academic research, and no guarantees or maintenance are provided.
4539

46-
# Cite
40+
This project was developed as part of academic research. No guarantees or maintenance are provided.
41+
42+
## Cite
4743

4844
```
4945
@article{jniAgents,

0 commit comments

Comments
 (0)