Visitar URL original
Improve the documentation on how to use the java-profiler project (#196) · DataDog/java-profiler@6fa1618 · GitHub
Skip to content

Commit 6fa1618

Browse files
r1violletr1viollet
authored
Improve the documentation on how to use the java-profiler project (#196)
1 parent 0e0fd97 commit 6fa1618

1 file changed

Lines changed: 107 additions & 17 deletions

File tree

‎README.md‎

Lines changed: 107 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,129 @@ _Based on [async-profiler 2.8.3](https://github.com/jvm-profiling-tools/java-pro
55
This is not a fork of [async-profiler](https://github.com/jvm-profiling-tools/async-profiler). This is a work derived from __async-profiler__ but tailored very specifically for Datadog needs.
66
If you need a full-fledged Java profiler head back to [async-profiler](https://github.com/jvm-profiling-tools/async-profiler)
77

8-
## Usage
9-
**!TODO!**
10-
11-
128
## Build
139

1410
### Prerequisites
15-
1. This project contains Java code and is built by gradle, as such, you need to install a JDK in order to build it. Run `brew install openjdk` to install it on MacOS.
16-
If building and testing on Apple Silicon (M1+), be sure to install an aarch64 OpenJDK distribution, otherwise the architecture used for compilation and the JVM based test suite will not match, which means the tests will not be able to load the dynamic library at runtime.
17-
2. The build requires make, which is included in XCode, but can also be installed by running `brew install make`
18-
3. The build supports googletest for unit testing. To install it, run `brew install googletest` or `sudo apt install libgtest-dev` or `apk add gtest-dev` depending on your platform.
19-
4. The build is applying consistent formatting using 'spotless' Gradle plugin. For C/C++ files it will use `clang-format` version 11. To install it, run `brew install clang-format-11` or `sudo apt install clang-format-11` or `apk add clang-format-11` depending on your platform. If the installed version does not provide `/usr/bin/clang-format` executable create a link like `sudo ln -s /usr/bin/clang-format-11 /usr/bin/clang-format` in order for the 'spotles' pluging to function correctly.
11+
1. JDK 8 or later (required for building)
12+
2. Gradle (included in wrapper)
13+
3. C++ compiler (gcc/g++ or clang)
14+
4. Make (included in XCode on Macos)
15+
5. Google Test (for unit testing)
16+
- On Ubuntu/Debian: `sudo apt install libgtest-dev`
17+
- On macOS: `brew install googletest`
18+
- On Alpine: `apk add gtest-dev`
19+
6. clang-format 11 (for code formatting)
20+
- On Ubuntu/Debian: `sudo apt install clang-format-11`
21+
- On macOS: `brew install clang-format-11`
22+
- On Alpine: `apk add clang-format-11`
2023

24+
### Building the Project
25+
1. Clone the repository:
26+
```bash
27+
git clone https://github.com/DataDog/java-profiler.git
28+
cd java-profiler
29+
```
2130

22-
Once prerequisites have been installed simple as `./gradlew assembleAll`. The resulting artifact is located in `ddprof-lib/build/libs/ddprof-<version>.jar`
31+
2. Build a release version of the project:
32+
```bash
33+
./gradle buildRelease
34+
```
35+
36+
The resulting artifact will be in `ddprof-lib/build/libs/ddprof-<version>.jar`
2337

2438
## Testing
25-
The associated test cases can be run for each specific configuration:
26-
- `testRelase` - test the release artifacts
27-
- `testDebug` - test the debug artifacts
28-
- `testAsan` - test with ASan
29-
- `testTsan` - test with TSan
3039

31-
The tests that create a JFR recording for the purpose of asserting will delete this recording at the end, unless `-PkeepJFRs` is provided to gradle.
40+
### Unit Tests
41+
The project includes both Java and C++ unit tests. You can run them using:
42+
43+
```bash
44+
# Run all tests
45+
./gradlew test
46+
47+
# Run specific test configurations
48+
./gradlew testRelease # Run release build tests
49+
./gradlew testDebug # Run debug build tests
50+
./gradlew testAsan # Run tests with ASan
51+
./gradlew testTsan # Run tests with TSan
3252

33-
One can also completely skip all tests by adding `-Pskip-tests` gradle property.
53+
# Run C++ unit tests only
54+
./gradlew gtestDebug # Run C++ tests in debug mode
55+
./gradlew gtestRelease # Run C++ tests in release mode
56+
```
3457

58+
### Test Options
59+
- Skip all tests: `./gradlew build -Pskip-tests`
60+
- Keep JFR recordings: `./gradlew test -PkeepJFRs`
61+
- Skip native build: `./gradlew build -Pskip-native`
62+
- Skip C++ tests: `./gradlew build -Pskip-gtest`
63+
64+
## Development
65+
66+
### Code Quality
67+
The project uses several tools for code quality:
68+
69+
1. clang-format for C++ code formatting
70+
2. scan-build for static analysis
71+
3. cppcheck for additional C++ checks
72+
73+
Run code quality checks:
74+
```bash
75+
# Run scan-build (this will use the scan-build binary)
76+
./gradlew scanBuild
77+
78+
# Run cppcheck (if configured)
79+
./gradlew cppcheck
80+
81+
# Run spotless (including code formatting)
82+
./gradlew spotlessApply
83+
```
84+
85+
### Debugging
86+
**!TODO!**
87+
88+
### Stress Tests
89+
The project includes JMH-based stress tests:
90+
91+
```bash
92+
# Run all stress tests
93+
./gradlew :ddprof-stresstest:runStressTests
94+
95+
### Common Issues
96+
1. If you encounter strange crashes Asan:
97+
```bash
98+
sudo sysctl vm.mmap_rnd_bits=28
99+
```
100+
101+
2. For ASan/TSan issues, ensure you have the required libraries installed:
102+
- ASan: `libasan`
103+
- TSan: `libtsan`
104+
105+
## Contributing
106+
1. Fork the repository
107+
2. Create a feature branch
108+
3. Make your changes
109+
4. Run tests: `./gradlew test`
110+
5. Submit a pull request
111+
112+
## License
113+
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
114+
115+
## Usage
116+
117+
### Example
118+
119+
Download the latest version of dd-trace-java and add `-Ddd.profiling.ddprof.debug.lib`. Example of a command line:
120+
```bash
121+
DD_SERVICE=your-service DD_TRACE_DEBUG=true java -javaagent:./temp/dd-java-agent.jar -Ddd.profiling.enabled=true -Ddd.profiling.ddprof.enabled=true -Ddd.profiling.ddprof.liveheap.enabled=true -Ddd.profiling.upload.period=10 -Ddd.profiling.start-force-first=true -Ddd.profiling.ddprof.debug.lib=~/dd/java-profiler/ddprof-lib/build/lib/main/debug/linux/x64/libjavaProfiler.so -XX:ErrorFile=${PWD}/hs_err_pid%p.log -XX:OnError='java -jar temp/dd-java-agent.jar uploadCrash hs_err_pid%p.log' -jar ./temp/renaissance-gpl-0.15.0.jar akka-uct -r 5
122+
```
35123

36124
### Consuming the artifact
125+
37126
For dd-trace-java you just need to set the `ddprof.jar` project property.
38127
Eg. you can run the gradle build like this - ./gradlew clean -Pddprof.jar=file://<path-to-artifact.jar> :dd-java-agent:shadowJar` - which will result in a custom `dd-java-agent.jar` build containing your test version of Java profiler.
39128
40129
## Working with upstream
130+
41131
Although this project still shares the git history with the upstream the code structure is different. This makes it dificult to reliably
42132
cherry-pick the upstream changes. To make this easier we have a script that will prepare a filtered version of the upstream repository
43133
and add it as 'cherry' remote to this repository. This way you can cherry-pick the changes from the upstream repository with (relative) ease.

0 commit comments

Comments
 (0)