diff --git a/docs/assets/resources/yourkit/mvn-profiler.sh b/docs/assets/resources/yourkit/mvn-profiler.sh new file mode 100755 index 00000000..505365a2 --- /dev/null +++ b/docs/assets/resources/yourkit/mvn-profiler.sh @@ -0,0 +1,65 @@ +#!/bin/bash + +# +# You can set the env variables here instead of exporting them globally if you want. +# +#YOUMONITOR_HOME=$HOME/.youmonitor +#YOUMONITOR_REPOSITORIES=$YOUMONITOR_HOME/repositories + +# Fallback defaults for YOUMONITOR_HOME and YOUMONITOR_REPOSITORIES. +if [ -z "$YOUMONITOR_HOME" ]; then + YOUMONITOR_HOME=$HOME/.youmonitor +fi + +if [ -z "$YOUMONITOR_REPOSITORIES" ]; then + YOUMONITOR_REPOSITORIES=$YOUMONITOR_HOME/repositories +fi + +# Dependency check +if ! type dialog &> /dev/null || ! type jq &> /dev/null; then + echo "This script depends on dialog and jq." + echo "Please ensure you have both of them installed and available in your PATH!" + exit 1 +fi + +echo "Searching for projects in $YOUMONITOR_REPOSITORIES" + +declare -a PROJECTS + +for f in `find $YOUMONITOR_REPOSITORIES -type f -name repository.json -print `; do + PROJECT_ID=`jq -r '.guid' $f` + PROJECT_NAME=`jq -r '.displayName' $f` + echo " - Found project($PROJECT_ID): $PROJECT_NAME" + PROJECTS+=("$PROJECT_ID" "$PROJECT_NAME") +done + +if [[ ${#PROJECTS[@]} -eq "0" ]]; then + echo "No projects found in $YOUMONITOR_REPOSITORIES. Exiting!" + exit 1 +fi + +# Avoid redirection issues when running script in different terminal context. +TERMINAL=$(tty) +SELECTED_PROJECT=$(dialog --backtitle "Select YouMonitor project" --title "Select a project" --menu "" 15 80 4 "${PROJECTS[@]}" 2>&1 >$TERMINAL) + +clear + +echo "" +echo "YouMonitor installed at: $YOUMONITOR_HOME" +echo "YouMonitor repositories path: $YOUMONITOR_REPOSITORIES" +echo -n "YouMonitor selected project: " + +if [[ -z "$SELECTED_PROJECT" ]]; then + echo "No project selected" + echo "Nothing more to do - exiting." + echo "" + exit 0 +else + echo $YOUMONITOR_REPOSITORIES/$SELECTED_PROJECT +fi +echo "" + +set -x +LD_LIBRARY_PATH=$YOUMONITOR_HOME/current/32:$YOUMONITOR_HOME/current/64:$LD_LIBRARY_PATH +MAVEN_OPTS="$MAVEN_OPTS -agentlib:youmonitor=repository=$YOUMONITOR_REPOSITORIES/$SELECTED_PROJECT" +env LD_LIBRARY_PATH="$LD_LIBRARY_PATH" MAVEN_OPTS="$MAVEN_OPTS" MAVEN_DEBUG_OPTS="$MAVEN_DEBUG_OPTS" mvn "$@" diff --git a/docs/assets/screenshots/yourkit/01.png b/docs/assets/screenshots/yourkit/01.png new file mode 100644 index 00000000..f6dfb6fb Binary files /dev/null and b/docs/assets/screenshots/yourkit/01.png differ diff --git a/docs/assets/screenshots/yourkit/02.png b/docs/assets/screenshots/yourkit/02.png new file mode 100644 index 00000000..2cc5b516 Binary files /dev/null and b/docs/assets/screenshots/yourkit/02.png differ diff --git a/docs/assets/screenshots/yourkit/03.png b/docs/assets/screenshots/yourkit/03.png new file mode 100644 index 00000000..47644d0b Binary files /dev/null and b/docs/assets/screenshots/yourkit/03.png differ diff --git a/docs/assets/stylesheets/style.css b/docs/assets/stylesheets/style.css index 7501ba1b..8229ab48 100644 --- a/docs/assets/stylesheets/style.css +++ b/docs/assets/stylesheets/style.css @@ -127,11 +127,14 @@ body > .md-container { } .md-typeset code, .md-typeset pre { - /*background-color: hsl(199, 19%, 39%);*/ - background-color: hsl(207, 24%, 18%); + background-color: hsl(207, 24%, 17%); color: #f7f7f7; } +.md-typeset code { + padding: .25em .5em; +} + .md-typeset .codehilitetable .linenos, .md-typeset .highlighttable .linenos { background-color: rgb(35, 47, 57); } diff --git a/docs/developer-guide/yourkit/yourkit-java-profiler.md b/docs/developer-guide/yourkit/yourkit-java-profiler.md new file mode 100644 index 00000000..94df5eb8 --- /dev/null +++ b/docs/developer-guide/yourkit/yourkit-java-profiler.md @@ -0,0 +1,96 @@ +# YourKit Java Profiler + +## Intro + +Having a fast running application requires a lot of efforts to find the cause of memory leaks, high CPU +usage and do overall application profiling. We would like to thank [YourKit][yourkit-link] for sponsoring us and +making our lives much easier! + +[![][yourkit-logo]][yourkit-link] + +[YourKit][yourkit-link] supports open source projects with innovative and intelligent tools for monitoring and +profiling Java and .NET applications. YourKit is the creator of [YourKit Java Profiler][yourkit-profiler-link], +[YourKit .NET Profiler][yourkit-dotnet-profiler-link] and [YourKit YouMonitor][yourkit-monitor-link]. + + +## Pre-requisites + +* JDK 8 +* [Running Strongbox instance](../building-strongbox-using-strongbox-instance.md) +* [YourKit Java Profiler][yourkit-profiler-link] +* `YOURKIT_PROFILER` environment variable pointing to the installation path. +* `YOURKIT_PROFILER_AGENT` environment variable pointing to the correct agent + +## YourKit Java Profiler + +There are a two ways to start profiling: + +1. By automatically attaching profiler with an agent (preferred) +2. By manually attaching the profiler to a running JVM ([limitations][yourkit-profiler-manual-attach-limits]) + +### Agents + +All possible OS agents can be found at [YourKit Java Profiler Help page][yourkit-profiler-agnets]. + +OS | Platform | Agent +------- | ---------------- | ----- +Linux | x86, 64-bit Java | `-agentpath:$YOURKIT_PROFILER/bin/linux-x86-64/libyjpagent.so` +macOS | n/a | `-agentpath:$YOURKIT_PROFILER/bin/mac/libyjpagent.dylib` +Windows | x86, 64-bit Java | `-agentpath:%YOURKIT_PROFILER%\bin\win64\yjpagent.dll` + +### Start profiling + +1. Start [YourKit Java Profiler][yourkit-profiler-link] +1. Set an environment variable with the agent corresponding to your OS: + + === "Linux" + ``` + YOURKIT_PROFILER_AGENT=-agentpath:$YOURKIT_PROFILER/bin/linux-x86-64/libyjpagent.so + ``` + === "MacOS" + ``` + YOURKIT_PROFILER_AGENT=-agentpath:$YOURKIT_PROFILER/bin/mac/libyjpagent.dylib + ``` + === "Windows" + ``` + set YOURKIT_PROFILER_AGENT=-agentpath:%YOURKIT_PROFILER%\bin\win64\yjpagent.dll + ``` + +2. Start a Strongbox instance + + === "Linux/Mac" + ``` + For spring-boot:run: + JAVA_TOOL_OPTIONS=$YOURKIT_PROFILER_AGENT mvn spring-boot:run + + For strongbox-distribution: + JAVA_TOOL_OPTIONS=$YOURKIT_PROFILER_AGENT ./bin/strongbox start + ``` + + === "Windows" + ``` + For spring-boot:run: + set JAVA_TOOL_OPTIONS=%YOURKIT_PROFILER_AGENT% + mvn spring-boot:run + + For strongbox-distribution: + set JAVA_TOOL_OPTIONS=%YOURKIT_PROFILER_AGENT% + ./bin/strongbox start + ``` + +3. Select `StrongboxSpringBootApplication` in the profiler + +## See also + +* [YourKit Java Profiler: Help](https://www.yourkit.com/docs/java/help/) +* [YourKit Java Profiler: Local Profiling](https://www.yourkit.com/docs/java/help/local_profiling.jsp) +* [YourKit Java Profiler: Enabling profiling manually](https://www.yourkit.com/docs/java/help/agent.jsp) + + +[yourkit-logo]: https://www.yourkit.com/images/yk_logo.png +[yourkit-link]: https://www.yourkit.com +[yourkit-profiler-link]: https://www.yourkit.com/java/profiler +[yourkit-dotnet-profiler-link]: https://www.yourkit.com/.net/profiler +[yourkit-monitor-link]: https://www.yourkit.com/youmonitor/ +[yourkit-profiler-manual-attach-limits]: https://www.yourkit.com/docs/java/help/attach_agent.jsp#limitations +[yourkit-profiler-agnets]: https://www.yourkit.com/docs/java/help/agent.jsp diff --git a/docs/developer-guide/yourkit/yourkit-youmonitor.md b/docs/developer-guide/yourkit/yourkit-youmonitor.md new file mode 100644 index 00000000..cc68e8a1 --- /dev/null +++ b/docs/developer-guide/yourkit/yourkit-youmonitor.md @@ -0,0 +1,148 @@ +# YourKit YouMonitor + +## Intro + +Having a fast running application requires a lot of efforts to find the cause of memory leaks, high CPU +usage and do overall application profiling. In addition to [YourKit Java Profiler][yourkit-profiler-link] we are also +using [YourKit YouMonitor][yourkit-monitor-link] to keep our build times as fast as possible and pin-point slow tests. + +[![][yourkit-logo]][yourkit-link] + +[YourKit][yourkit-link] supports open source projects with innovative and intelligent tools for monitoring and +profiling Java and .NET applications. YourKit is the creator of [YourKit Java Profiler][yourkit-profiler-link], +[YourKit .NET Profiler][yourkit-dotnet-profiler-link] and [YourKit YouMonitor][yourkit-monitor-link]. + +## Pre-requisites + +* JDK 8 +* [Running Strongbox instance](../building-strongbox-using-strongbox-instance.md) +* `YOUMONITOR_HOME` environment variable pointing to the installation path. +* `YOUMONITOR_REPOSITORIES` environment variable pointing to a YouMonitor repositories path +* `dialog` and `jq` (if you use `mvn-profiler.sh`) + + !!! warning + The guide shows the setup process for Linux/Mac. + Most of us are not using Windows which is why this guide might lack some instructions specific to Windows. + Feel free to open up PRs and help us improve the docs. + +## YourKit YouMonitor + +### Installation + +Download [YouMonitor][yourkit-monitor-link] and then: + +=== "Linux" + ``` linenums="1" + unzip YourKit-YouMonitor-*.zip + + (Optional) Add environment variables to `.bashrc`, `/etc/profile` + or set them in the mvn-profiler.sh script: + + YOUMONITOR_HOME=\$HOME/.youmonitor + YOUMONITOR_REPOSITORIES=\$YOUMONITOR_HOME/repositories + ``` + +=== "MacOS" + ``` linenums="1" + Install the .dmg into Applications. + + (Optional) Add environment variables to `.bashrc`, `/etc/profile` + or set them in the mvn-profiler.sh script: + + YOUMONITOR_HOME=\$HOME/.youmonitor + YOUMONITOR_REPOSITORIES=\$YOUMONITOR_HOME/repositories + ``` + +=== "Windows" + + ``` linenums="1" + Install the `.exe` + ``` + +### Repository setup + +1. When you start [YouMonitor][yourkit-monitor-link] the `Get Started with YouMonitor` screen will have the following options: + + 1. Monitor Builds in IDE or Command line + 2. Monitor builds on continuous integration server + +2. Since we are using the free version, we can only be using `Monitor builds through IDE or command line`. +3. Select `Command Line` + + ![][yourkit-monitor-welcome-screen] + +4. You will be prompted to setup a "repository" - this is where [YouMonitor][yourkit-monitor-link] will +keep the build history. Enter a `(Project) Name` and leave the `Location` as it is. + + !!! note + The `Location` points to `$HOME/.youmonitor/repositories/[random-string]` by default. + The same pattern is used later in the [mvn-profiler] bash script. + +5. Click `Open Instructions` which will give you further instructions on how to `run` a maven build with +[YouMonitor][yourkit-monitor-link]. The instructions will ask you to create a script called `xmvn.sh` with some env vars +exported. Although this works fine, it becomes annoying and error-prone when you have to switch between multiple projects. +Continue to the next section for guidance on automating this. + +### mvn-profiler + +In order for [YouMonitor][yourkit-monitor-link] to record and keep track of build performance you need to export +`LD_LIBRARY_PATH` and `MAVEN_OPTS` pointing to the correct YouMonitor `repository` and `LD_LIBRARY`. This quickly becomes +annoying and error-prone when you need to switch between multiple project within Strongbox. + +In an attempt to ease this pain, we have created a [mvn-profiler] bash script which does this automatically and allows +you to select existing YouMonitor repositories from `$HOME/.youmonitor/repositories` before starting the maven build. +To install: + +1. Download `mvn-profiler.sh` + + ``` + curl -o mvn-profiler \ + {{resources}}/yourkit/mvn-profiler.sh + ``` + +2. Install into `/usr/local/bin` + ``` + sudo mv mvn-profiler /usr/local/bin/mvn-profiler + ``` + + !!! warning + Obviously, this script only works for Linux/MacOS and won't work on Windows. + Pull requests are more than welcome. + +## Build Profiling + +1. Start YouMonitor + +2. Execute + * If you are using `mvn-profiler.sh`: + ``` + mvn-profiler clean install + ``` + * If you are using the `xmvn.sh` or `xmvn.bat` (as suggested in the instructions): + ``` + xmvn.sh clean install + ``` + +3. Monitor the build in YouMonitor. + + ![][yourkit-monitor-monitor-02] + ![][yourkit-monitor-monitor-03] + +## See also + +* [YourKit YouMonitor: Help](https://www.yourkit.com/docs/youmonitor/help/) +* [YourKit YouMonitor: Build Insights](https://www.yourkit.com/docs/youmonitor/help/build_insights.jsp) +* [YourKit YouMonitor: JUnit](https://www.yourkit.com/docs/youmonitor/help/junit.jsp) +* [YourKit YouMonitor: Maven](https://www.yourkit.com/docs/youmonitor/help/maven.jsp) +* [YourKit YouMonitor: Event details](https://www.yourkit.com/docs/youmonitor/help/event_details.jsp) + +[yourkit-logo]: https://www.yourkit.com/images/yk_logo.png +[yourkit-link]: https://www.yourkit.com +[yourkit-profiler-link]: https://www.yourkit.com/java/profiler +[yourkit-dotnet-profiler-link]: https://www.yourkit.com/.net/profiler +[yourkit-monitor-link]: https://www.yourkit.com/youmonitor/ +[yourkit-monitor-welcome-screen]: ../../assets/screenshots/yourkit/01.png +[yourkit-monitor-monitor-02]: ../../assets/screenshots/yourkit/02.png +[yourkit-monitor-monitor-03]: ../../assets/screenshots/yourkit/03.png +[mvn-profiler]: #mvn-profiler +[mvn-profiler-link]: {{resources}}/yourkit/mvn-profiler.sh diff --git a/mkdocs.yml b/mkdocs.yml index bf9f4a12..68253fcb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -139,6 +139,9 @@ nav: - AssertJ: developer-guide/assertj-user-guide.md - Web Form Tests: developer-guide/writing-web-form-tests.md - Web Integration Tests: developer-guide/writing-web-integration-tests.md + - Performance: + - YourKit Java Profiler: developer-guide/yourkit/yourkit-java-profiler.md + - YourKit YouMonitor: developer-guide/yourkit/yourkit-youmonitor.md - Using Git: - Rebasing vs Merging: developer-guide/git/rebase-vs-merge.md - How To Gather Requirements: developer-guide/how-to-gather-requirements.md