Creating guides for profiling.

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 "$@"

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);
 }

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

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

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