HOW TO INTEGRATE MICROMETRICS TO CI/CD PIPELINE

In this article, we will walk you through the steps involved in integrating micrometrics to your CI/CD pipeline. Micrometrics are powerful lead indicators to forecast production performance problems. It also ensures developers commit high quality to the source code repository. Here is a good article that outlines the micrometrics and the benefits of monitoring them in CI/CD pipeline. We encourage you to read the article mentioned in the previous sentence before moving forward. It should take <5 minutes.

Prerequisite-1: API Registration

Please register here to get the API Key. This API key is required to invoke REST API which computes micrometrics from the Garbage Collection logs, thread dumps, and heap dumps.

 Prerequisite-2: Test Suite

Garbage collection logs, thread dumps and heap dumps that are captured when the application is taking real transactions are more meaningful. We believe the most organization would run some form of tests (unit tests, regression tests, stress tests) as part of their CI/CD pipeline. Ideally, you might want to capture these dumps when stress tests are executed.  If stress tests aren’t part of your CI/CD pipeline, then no worries, you may capture these dumps when other tests are run. In case if your CI/CD pipeline doesn’t have any test suite, then we highly encourage you create/integrate one. For effective CI/CD pipeline, you need to have thorough tests to be in place.

1.Capture all dumps

To get micrometrics, you should capture following dumps when tests are executed during CI/CD pipeline.

(a).Garbage Collection logs

(b).Thread Dumps

(c).Heap Dumps

In this section, let’s see how to capture these dumps.

(a). Enable GC logs

When the application is started, pass below mentioned arguments:

Until Java 8:

Pass below arguments when you start your application if you are using java version less than or equal to Java 8.

-XX:+PrintGCDetails -Xloggc:

Example:

-XX:+PrintGCDetails -Xloggc:/opt/tmp/myapp-gc.log

From Java 9:

Pass below arguments when you start your application, if you are using Java 9 and above.

-Xlog:gc*:file=

Example:

-Xlog:gc*:file=/opt/tmp/myapp-gc.

“BEST PRACTISE: It’s best practice enable GC logs across all your production JVMs at all the times. GC logs add no noticeable (very negligible) overhead. It helps you to troubleshoot several production problems”.

(b). Capture thread dumps

You can capture thread dumps during the middle of the test run. It’s highly recommended to capture 3 threads in a gap of 10 seconds between them. You can use the “jstack” tool which is present in JAVA_HOME/bin folder to capture the thread dumps. Here is the command to use jstack tool:

jstack -l  {pid} > {file-path}

Example:

jstack -l 37320 > /opt/tmp/threadDump.txt

where

pid: is the Process Id of the application, whose thread dump should be captured

file-path: is the file path where thread dump will be written in to.

If you are looking for other options to capture thread dumps besides jstack tool, you can refer to this article

(c). Capture heap dumps

It’s recommended to capture heap dump after test run is completed. You can use the “jmap” tool which is present in JAVA_HOME/bin folder to capture the heap dumps.

jmap -dump:format=b,file={file-path} {pid}

Example:

jmap -dump:format=b,file=/opt/tmp/heapdump.bin 37320

where

pid: is the Java Process Id, whose heap dump should be captured

file-path: is the file path where heap dump will be written in to.

If you are looking for other options to capture heap dumps besides jmap tool, you can refer to this article.

2. Invoke Micrometric Analysis APIs

Once you have captured necessary dumps, next step is to invoke the micrometrics analysis APIs.

(a).Invoke GC log analysis API

GCeasy REST API provides simple yet powerful mechanism to analyze GC logs. Assume your GC log file is in “./my-app-gc.log,” then here is the CURL command to invoke the API:

curl -X POST --data-binary @./my-app-gc.log http://api.gceasy.io/analyzeGC? apiKey={YOUR_API_KEY} --header "Content-Type:text"

Example: 

curl -X POST --data-binary @./my-app-gc.log http://api.gceasy.io/analyzeGC?apiKey= ea9za34e-43eb-4c9a-8254-fodd1o7b45cc --header "Content-Type:text"

(b). Invoke thread dump analysis API

FastThread REST API provides simple yet powerful mechanism to analyze thread dumps. Assume your Thread dump file is located in “./my-thread-dump.txt,” then here is the CURL command to invoke the API:

curl -X POST --data-binary @./my-thread-dump.txt http://api.fastthread.io/fastthread-api?apiKey={YOUR_API_KEY} --header "Content-Type:text"

Example: 

curl -X POST --data-binary @./my-thread-dump.txt http://api.fastthread.io/fastthread-api?apiKey= ea9za34e-43eb-4c9a-8254-fodd1o7b45cc --header "Content-Type:text"

(c).Invoke heap dump analysis API

HeapHero REST API provides simple yet powerful mechanism to analyze heap dumps. Assume your Heap Dump file is located in ./my-heap-dump.hprof, then here is a simple CURL command to invoke the API:

Curl –X POST  --data-binary @./my-heap-dump.hprof http://api.heaphero.io/analyze-hd-api?apiKey={YOUR_API_KEY} --header "Content-Type:text"

Example:

Curl –X POST  --data-binary @./my-heap-dump.hprof http:// api.heaphero.io/analyze-hd-api?apiKey= ea9za34e-43eb-4c9a-8254-fodd1o7b45cc --header "Content-Type:text"

Note: Heap dumps are typically very large files, for fast processing you might want to compress the heap dump file and invoke the API. To learn how to invoke API with compressed heap dump file, refer to this section.

3. Trigger warnings, build failures

Micrometrics analysis APIS contains rich set of information (i.e. lot of elements). In the below articles we have highlighted key elements in the API response, JSON paths for those key elements and acceptable thresholds for those elements. If the values of those key elements go above or below certain threshold, you should fail the build or generate warnings.

1. GC micrometrics thresholds are given can be found here.
2. Thread micrometrics thresholds are given can be found here.
3. Heap micrometrics thresholds are given can be found here.

Conclusion

We hope and wish by integrating micrometrics to your CI/CD pipeline, your quality of source code, quality of releases to production improves significantly.