Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Steeven9/Jung
Bachelor Project at USI, Lugano. A tool for Instrumentation and Performance Analysis of Distributed Systems based on Freud and gRPC
https://github.com/Steeven9/Jung
Last synced: about 2 months ago
JSON representation
Bachelor Project at USI, Lugano. A tool for Instrumentation and Performance Analysis of Distributed Systems based on Freud and gRPC
- Host: GitHub
- URL: https://github.com/Steeven9/Jung
- Owner: Steeven9
- License: apache-2.0
- Archived: true
- Created: 2021-02-19T11:15:33.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-06-25T21:59:40.000Z (over 3 years ago)
- Last Synced: 2024-08-03T19:09:21.430Z (5 months ago)
- Language: C++
- Homepage:
- Size: 6.62 MB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Jung
[](/LICENSE)
[](https://github.com/Steeven9/Jung/actions/workflows/c-cpp.yml)
[](https://hub.docker.com/repository/docker/steeven9/jung)
[](https://hub.docker.com/repository/docker/steeven9/jung)
Bachelor Project at USI, Lugano.
A tool for Instrumentation and Performance Analysis of Distributed Systems based on [Freud](https://github.com/usi-systems/freud) and [gRPC](https://grpc.io).
## Install dependencies
An automated installation script for both Jung and Freud, `install.sh`, is included in the repo.
Detailed instructions are provided below for manual setup.
### Linux
`apt install build-essential pkg-config protobuf-compiler-grpc libgrpc-dev libgrpc++-dev`
### macOS
`brew install grpc`
`export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig:/usr/local/opt/grpc/lib/pkgconfig:$PKG_CONFIG_PATH`
### Windows
Get a Linux VM then see above.
## Compile and run the example
`make`
`./jung_server`
Then, in another terminal, run the client
`./jung_client`
This will produce two files, `client_log.txt` and `server_log.txt`, that can be merged in a unique trace by running `./trace_merge`. If your server is running on another machine, be sure to retrieve the log file before merging!
This will in turn produce a human-readable file (`trace_log.txt`) and a `symbols` folder that contains the unified costs
encoded in binary format. These can then be read by `freud-statistics` (see the [original repo](https://github.com/usi-systems/freud) for instructions).
Alternatively, by running `./trace_merge --simple`, a simple merged log (`merged_log.txt`) can be obtained instead.
_Note_: all the file names are customizable in `custom_instr.h`.
_Disclaimer_: the memory usage counter is not keeping track of the variations due to `realloc` calls.
While the library provides a warning for potential memory leaks, this might be inaccurate due to the complexity of memory management in C.
If you get any warnings, consider running your application through a dedicated tool like [Valgrind](https://valgrind.org/).
If you don't get any, consider doing it anyway, don't trust me.
## Testing
As someone once said, _"Tests don't prove correctness"_, therefore this project has no coverage whatsoever. You can however still run some
basic tests with `make test`.
## Docker
A Docker image of the example server is available on [Docker Hub](https://hub.docker.com/repository/docker/steeven9/jung), which you can spin up with `docker-compose up`.
You can also build it yourself with `docker build -t jung ./`.
## Running on another machine
If your server is running on another machine (which is probably the case), simply pass its address/hostname
to the client as parameter (port is `50051` by default, editable in `jung_server.cc`):
`./jung_client --target=HOSTNAME[:PORT]`
## Using the library
If you want to measure your own application, simply include `custom_instr.h`, which provides all the necessary
functions to manage the instrumentation. Make sure to also include the corresponding `.cc` file in your compilation unit.
The instrumentation is manual, so you will need to replace by hand all the functions like `malloc` with the library version
(e.g. `custom_malloc`) that are defined in `custom_instr.h`.
To merge the obtained traces, compile and run `trace_merge.cc` (which requires `custom_instr.h` as well).
## Contributions
This project includes some code from the [gRPC examples](https://github.com/grpc/grpc/tree/master/examples/cpp) and
[Freud](https://github.com/usi-systems/freud). Thank you to the original authors!