Skip to content

Commit 73c37a0

Browse files
nenuadriannenuadrian
committed
Add README TOC and MkDocs Material docs with Pages workflow
1 parent 7f2d9e1 commit 73c37a0

11 files changed

Lines changed: 266 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Docs (MkDocs Material)
2+
3+
on:
4+
push:
5+
branches: ["master"]
6+
pull_request:
7+
branches: ["master"]
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: pages
17+
cancel-in-progress: false
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- name: Checkout
25+
uses: actions/checkout@v4
26+
27+
- name: Setup Python
28+
uses: actions/setup-python@v5
29+
with:
30+
python-version: "3.12"
31+
32+
- name: Install dependencies
33+
run: |
34+
python -m pip install --upgrade pip
35+
pip install mkdocs-material
36+
37+
- name: Build docs
38+
run: mkdocs build --strict
39+
40+
- name: Setup GitHub Pages
41+
uses: actions/configure-pages@v5
42+
43+
- name: Upload Pages artifact
44+
uses: actions/upload-pages-artifact@v3
45+
with:
46+
path: site
47+
48+
deploy:
49+
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
50+
needs: build
51+
runs-on: ubuntu-latest
52+
environment:
53+
name: github-pages
54+
url: ${{ steps.deployment.outputs.page_url }}
55+
56+
steps:
57+
- name: Deploy to GitHub Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,16 @@
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

6+
## Table of Contents
7+
8+
* [Overview](#overview)
9+
* [Key Features](#key-features)
10+
* [Technologies Used](#technologies-used)
11+
* [Installation and Usage](#installation-and-usage)
12+
* [Note](#note)
13+
* [Disclaimer](#disclaimer)
14+
* [Cite](#cite)
15+
616
## Overview
717

818
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]

‎docs/assets/dissertation.pdf‎

1.24 MB
Binary file not shown.

‎docs/dissertation.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Dissertation PDF
2+
3+
The dissertation is published with this documentation site.
4+
5+
- [Open or download the PDF](assets/dissertation.pdf)
6+
7+
## Embedded View
8+
9+
<object data="../assets/dissertation.pdf" type="application/pdf" width="100%" height="900px">
10+
<p>
11+
Your browser does not support embedded PDFs.
12+
<a href="../assets/dissertation.pdf">Open the dissertation PDF</a>.
13+
</p>
14+
</object>

‎docs/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# BSc Dissertation Project
2+
3+
This repository contains the implementation and dissertation artifacts for:
4+
5+
**Non-intrusive JVM agents for capturing the internal state of live production applications**
6+
7+
The work is split into multiple project components:
8+
9+
- A C/JVMTI/JNI agent that captures stack and heap data on exceptions.
10+
- A Scala API service for receiving, processing, and exposing captured data.
11+
- A FuelPHP dashboard for visualizing data and application health.
12+
- A MongoDB dataset export used by the API/dashboard.
13+
14+
Use the navigation menu to view each component and open the dissertation PDF.

‎docs/projects/c-jvm-agent-lib.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# C JVM Agent Library
2+
3+
Path: `c-jvm-agent-lib/`
4+
5+
## Purpose
6+
7+
Native JVM agent implementation that captures stack-trace context and recursively inspects object state from live JVM processes.
8+
9+
## Main Parts
10+
11+
- `c/agent/`: C/C++ agent implementation, CMake build files, and native dependencies.
12+
- `java/`: Java test application and build scripts for agent integration testing.
13+
- `build.sh`: Helper script that builds native code and Java parts in sequence.
14+
15+
## Typical Commands
16+
17+
Build both native agent and Java app:
18+
19+
```bash
20+
cd c-jvm-agent-lib
21+
sh build.sh
22+
```
23+
24+
Run Java app with native agent:
25+
26+
```bash
27+
java -agentpath:CodEvoAgent -jar app.jar
28+
```
29+
30+
Verbose mode with source path:
31+
32+
```bash
33+
java -agentpath:CodEvoAgent -DcodevoSources=../java/java_test/ -DcodevoVerbose=3 -jar app.jar
34+
```

‎docs/projects/fuelphp-dashboard-portal.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# FuelPHP Dashboard Portal
2+
3+
Path: `fuelphp-dashboard-portal/`
4+
5+
## Purpose
6+
7+
Web dashboard that visualizes application diagnostics, exceptions, and captured state produced by the agent and API stack.
8+
9+
## Stack
10+
11+
- FuelPHP `1.8`
12+
- PHP `>=5.3.3`
13+
- Composer-managed dependencies
14+
- Bootstrap/jQuery front-end assets
15+
16+
## Key Files
17+
18+
- `composer.json`: PHP framework and package dependencies.
19+
- `public_html/`: Front-end entrypoint and static assets.
20+
- `fuel/`: FuelPHP core/packages/app layers.
21+
22+
## Typical Commands
23+
24+
Install dependencies:
25+
26+
```bash
27+
cd fuelphp-dashboard-portal
28+
composer install
29+
```
30+
31+
Run through your PHP/FuelPHP setup (Apache/Nginx/PHP-FPM or local PHP server) using `public_html/` as web root.

‎docs/projects/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Projects Overview
2+
3+
This repository contains four main project directories:
4+
5+
| Project | Path | Purpose |
6+
|---|---|---|
7+
| C JVM Agent Library | `c-jvm-agent-lib/` | Native JVMTI/JNI agent and Java test app used to capture runtime state. |
8+
| Scala API | `scala-api/` | Backend API service that receives data from the agent and serves dashboard/API consumers. |
9+
| FuelPHP Dashboard Portal | `fuelphp-dashboard-portal/` | Web dashboard for viewing applications, errors, and captured diagnostics. |
10+
| Scala API DB | `scala-api-db/` | MongoDB BSON exports for logs, apps, and users. |
11+
12+
Each project has a dedicated page in this documentation section.

‎docs/projects/scala-api-db.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Scala API DB
2+
3+
Path: `scala-api-db/`
4+
5+
## Purpose
6+
7+
MongoDB export files used by the API/dashboard data layer.
8+
9+
## Contents
10+
11+
- `apps.bson` and `apps.metadata.json`
12+
- `logs.bson` and `logs.metadata.json`
13+
- `users.bson` and `users.metadata.json`
14+
15+
## Usage
16+
17+
Import data into MongoDB with `mongorestore` as needed for local development or reproducibility testing.
18+
19+
Example:
20+
21+
```bash
22+
mongorestore --db scala-api-db --collection apps scala-api-db/apps.bson
23+
```

‎docs/projects/scala-api.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Scala API
2+
3+
Path: `scala-api/`
4+
5+
## Purpose
6+
7+
Backend service that ingests/serves captured JVM diagnostic data and provides APIs consumed by the dashboard.
8+
9+
## Stack
10+
11+
- Scala `2.11.8`
12+
- Akka actor system
13+
- Spray (`spray-can`, `spray-routing`, `spray-json`)
14+
- ReactiveMongo
15+
16+
## Key Files
17+
18+
- `build.sbt`: Build definition and dependencies.
19+
- `start.sh`: Starts the API using `sbt run`.
20+
- `src/main/resources/application.conf.example`: Example runtime configuration.
21+
22+
## Typical Commands
23+
24+
```bash
25+
cd scala-api
26+
sbt run
27+
```
28+
29+
## Configuration Notes
30+
31+
The example config includes:
32+
33+
- MongoDB host/database settings
34+
- Spray server limits/timeouts
35+
- SMTP credentials for email-related flows

0 commit comments

Comments
 (0)