QuickPerf is a test library for Java to quickly evaluate and improve the performance of your application.<\/p>\n
The great interest of Quickperf lies in the fact that this is done via unit tests, which allows, after detecting and correcting a performance problem, to have non-regression tests so that it never comes back! You can then continuously evaluate the performance of your application via your continuous integration environment!<\/p>\n
Quickperf can be used to simply measure performance characteristics, or to assert on it via the definition of expectation<\/em>.<\/p>\n Quickperf requires Java 7 minimum and works with JUnit 4 or 5 and TestNG. The examples in this article are done in Java 11 via JUnit 5.<\/p>\n To use Quickperf you need to add the corresponding library to your test framework, here is an example with Maven for JUnit 5.<\/p>\n Before going into detail about the features of Quickperf, a small example :<\/p>\n Running these tests will give you the following result:<\/p>\n Build Success! Great!\nBy the way, you could notice Quickperf’s measurement of the memory allocation of the test Let’s now modify the code to add an expectation<\/em> for the test Running these modified tests will give you :<\/p>\n Build Failure :(<\/p>\n But with a human readable explanation of the cause.<\/p>\n One of the specificities of Quickperf is to give you as much information as possible about the reason of the failure of the test, through sentences understandable by a human being.<\/p>\n Core annotations are available within Quickperf’s main library, they offer the following features:<\/p>\n There are also a number of annotations to configure Quickperf, more information here<\/a>.<\/p>\n Most JVM annotations are included in the main Quickperf library except the annotations related to JFR – JDK Flight Recorder<\/a> which require the addition of the library Warning: the use of JVM annotation causes a JVM to be started for each test method.<\/strong><\/p>\n JVM annotations provide the following features :<\/p>\n Small zoom on the profiling of your application via JFR. The annotation @ProfileJvm<\/code>code>@ProfileJvm<\/code<\/a> will launch a JFR record for the execution of your method that you can then open with JMC – JDK Mission Control<\/a>. This annotation will also display some global JFR metrics in the console.<\/p>\n It is possible to define expectations<\/em> for this profile via the annotation @ExpectNoJvmIssue<\/code>code>@ExpectNoJvmIssue<\/code<\/a> which will be based on the JMC rules<\/a> to fail the test.<\/p>\n More information on JVM annotations here<\/a><\/p>\n To use SQL annotations, you need to add the library Quickperf has a lot of annotations to check the execution of SQL queries, and to detect the most common problems: duplicate queries, n+1 select, batch, …<\/p>\n Here are some of the most used annotations:<\/p>\n Small zoom on a particular annotation : @DisableSameSelectTypesWithDifferentParamValues<\/code>code>@DisableSameSelectTypesWithDifferentParamValues<\/code<\/a>, this one allows to detect problems with n+1 select<\/strong> with JPA \/ Hibernate..<\/p>\n This well known problem happens when two entities have a parent-child relationship, and loading the parent entity involves a select query to load it, plus n select to load its children. It is a well-known anti-pattern that is usually solved by performing a JPA JOIN FETCH<\/strong>.<\/p>\n Quickperf can detect this with the annotation @DisableSameSelectTypesWithDifferentParamValues<\/code>code>@DisableSameSelectTypesWithDifferentParamValues<\/code<\/a> which will cause your test to fail if several identical selects are executed with different parameters. And if it detects the presence of Hibernate, Quickperf will even give you advice on how to solve the problem!<\/p>\n Let’s imagine the following And the following test:<\/p>\n Loading the class As mentioned in the previous section, Quickperf requires a proxy from your DataSource to be able to detect SQL problems. Depending on the frameworks you use, you will need to set up this proxy.<\/p>\n This consists of a few lines of code that will define a wrapper on top of your DataSource:<\/p>\n The repository quickperf-examples<\/a> contains many examples of implementation of this proxy for the most common frameworks (Spring, Hibernate, Micronaut, …).<\/p>\n If you use Spring, the configuration is simplified, you don’t need to add the library \n\n \n \n org.junit\n junit-bom\n 5.7.0\n pom\n import\n \n \n org.quickperf\n quick-perf-bom\n 1.0.1\n pom\n import\n \n \n \n\n \n \n org.junit.jupiter\n junit-jupiter-engine\n test\n \n \n org.junit.platform\n junit-platform-launcher\n test\n \n \n<\/pre>\n
First example<\/h2>\n
@QuickPerfTest\npublic class JvmAnnotationsJunit5Test {\n\n @MeasureHeapAllocation\n @Test\n public void test_method_measuring_heap_allocation() {\n \/\/ java.util.ArrayList: 24 bytes + Object[]: 16 + 100 x 4 = 416 => 440 bytes\n ArrayList data = new ArrayList(100);\n }\n\n @ExpectNoHeapAllocation\n @Test\n public void should_not_allocate() {\n }\n}<\/pre>\n@QuickPerfTest<\/code>: is used to initialize the Quickperf JUnit5 extension (optional)<\/li>\n\n@MeasureHeapAllocation<\/code>: will measure the memory allocations made by the test<\/li>\n\n@ExpectNoHeapAllocation<\/code>: will create an expectation<\/em> so that the test should not perform memory allocation. If this is false, the test will fail (assertion failure)<\/li>\n<\/ul>\n[INFO] -------------------------------------------------------\n[INFO] T E S T S\n[INFO] -------------------------------------------------------\n[INFO] Running org.quickperf.jvm.JvmAnnotationsJunit5Test\n[QUICK PERF] Measured heap allocation (test method thread): 440 bytes\n[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.203 s - in org.quickperf.jvm.JvmAnnotationsJunit5Test\n[INFO] \n[INFO] Results:\n[INFO] \n[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0\n[INFO] \n[INFO] ------------------------------------------------------------------------\n[INFO] BUILD SUCCESS\n[INFO] ------------------------------------------------------------------------\n<\/pre>\n
test_method_measuring_heap_allocation<\/code>:<\/p>\n[QUICK PERF] Measured heap allocation (test method thread): 440 bytes\n<\/pre>\n
test_method_measuring_heap_allocation<\/code> so that it must allocate less than 400 bytes of memory.<\/p>\n\n@MeasureHeapAllocation\n@ExpectMaxHeapAllocation(value = 400, unit = AllocationUnit.BYTE)\n@Test\npublic void test_method_measuring_heap_allocation() {\n \/\/ java.util.ArrayList: 24 bytes + Object[]: 16 + 100 x 4 = 416 => 440 bytes\n ArrayList data = new ArrayList(100);\n}\n<\/pre>\n[INFO] -------------------------------------------------------\n[INFO] T E S T S\n[INFO] -------------------------------------------------------\n[INFO] Running org.quickperf.jvm.JvmAnnotationsJunit5Test\n[QUICK PERF] Measured heap allocation (test method thread): 440 bytes\n[ERROR] Tests run: 2, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 2.258 s <<< FAILURE! - in org.quickperf.jvm.JvmAnnotationsJunit5Test\n[ERROR] test_method_measuring_heap_allocation Time elapsed: 1.106 s <<< FAILURE!\njava.lang.AssertionError: \na performance property is not respected\n\n[PERF] Expected heap allocation (test method thread) to be less than 400 bytes but is 440 bytes.\n\n[INFO] \n[INFO] Results:\n[INFO] \n[ERROR] Failures: \n[ERROR] JvmAnnotationsJunit5Test.test_method_measuring_heap_allocation a performance property is not respected\n\n[PERF] Expected heap allocation (test method thread) to be less than 400 bytes but is 440 bytes.\n\n[INFO] \n[ERROR] Tests run: 2, Failures: 1, Errors: 0, Skipped: 0\n[INFO] \n[INFO] ------------------------------------------------------------------------\n[INFO] BUILD FAILURE\n[INFO] ------------------------------------------------------------------------\n<\/pre>\n
[PERF] Expected heap allocation (test method thread) to be less than 400 bytes but is 440 bytes.\n<\/pre>\n
Core annotations<\/h2>\n
@MeasureExecutionTime<\/code> : measures the execution time of the test method.<\/li>\n\n@ExpectMaxExecutionTime<\/code> : create an expectation<\/em> that the test should not run for more than a certain amount of time.<\/li>\n<\/ul>\nJVM annotations<\/h2>\n
org.quickperf:quick-perf-jfr-annotations<\/code>.<\/p>\n@HeapSize<\/code> (to configure Xmx and Xms), @Xms<\/code>, @Xmx<\/code>, @UseGC<\/code>, @EnableGcLogging<\/code> and @JvmOptions<\/code>.<\/li>\n\n@MeasureHeapAllocation<\/code>, @ExpectMaxHeapAllocation<\/code> and @ExpectNoHeapAllocation<\/code>. Uses the library ByteWatcher<\/a>.<\/li>\n\n@MeasureRSS<\/code> and @ExpectMaxRSS<\/code>.<\/li>\n\n------------------------------------------------------------------------------\n ALLOCATION (estimations) | GARBAGE COLLECTION | THROWABLE\n Total : 20,1 MiB | Total pause : 21,434 ms | Exception: 0\n Inside TLAB : 16,2 MiB | Longest GC pause: 21,434 ms | Error : 0\n Outside TLAB: 3,95 MiB | Young: 1 | Throwable: 0\n Allocation rate: 255 MiB\/s | Old : 0 |\n------------------------------------------------------------------------------\n COMPILATION | CODE CACHE\n Number : 0 | The number of full code cache events: 0\n Longest: 0 | \n------------------------------------------------------------------------------\n<\/pre>\n
Rule: Primitive To Object Conversion\nSeverity: INFO\nScore: 73\nMessage: 78 % of the total allocation (15,1 MiB) is caused by conversion from primitive \ntypes to object types.\n\nThe most common object type that primitives are converted into is \n'java.lang.Integer', which causes 15,1 MiB to be allocated. The most common \ncall site is 'org.quickperf.jvm.IntegerAccumulator.accumulateInteger(int):26'.\n\n[...]\n<\/pre>\n
SQL annotations<\/h2>\n
org.quickperf:quick-perf-sql-annotations<\/code> (unless you use Spring which has dedicated support). Depending on your application, you then need to configure its DataSource to add a proxy that will allow Quickperf to trace SQL queries. More information about this in the next section.<\/p>\n@ExpectJdbcQueryExecution<\/code> and @ExpectMaxQueryExecutionTime<\/code>: expectation<\/em> as for the execution time of a SQL query, the first one expect the exact time, the second one will fail if the measured time is greater (most SQL annotations come in pairs according to this same scheme).<\/li>\n\n@ExpectSelectedColumn<\/code> etand@ExpectMaxSelectedColumn<\/code> : expectation<\/em> as to the number of selected columns<\/li>\n\n@ExpectSelect<\/code> and @ExpectMaxSelect<\/code> : expectation<\/em> as to the number of selects generated\/li>\n <\/li>\n@ExpectJdbcBatching<\/code> : expectation<\/em> as to the usage of JDBC batching<\/li>\n<\/ul>\nPlayer<\/code> and Team<\/code> entities:<\/p>\n@Entity\npublic class Player implements Serializable {\n\n @Id\n @GeneratedValue(strategy = GenerationType.SEQUENCE)\n private Long id;\n\n private String firstName;\n\n private String lastName;\n\n @ManyToOne(targetEntity = Team.class)\n @JoinColumn(name = \"team_id\")\n private Team team;\n\n \/\/ getter and setters ...\n}\n\n@Entity\npublic class Team implements Serializable {\n\n @Id\n @GeneratedValue(strategy = GenerationType.SEQUENCE)\n private Long id;\n\n private String name;\n\n \/\/ getter and setters ...\n}\n<\/pre>\n\n@DisableSameSelectTypesWithDifferentParamValues\n@Test\npublic void should_find_all_players() {\n TypedQuery fromPlayer = entityManager.createQuery(\"FROM Player\", Player.class);\n List players = fromPlayer.getResultList();\n assertThat(players).hasSize(2);\n}\n<\/pre>\nPlayer<\/code> will result in n+1 SQL queries which will be detected by Quickperf which will then give you the following error message suggesting a problem with n+1 select and possible solutions :<\/p>\nERROR] Failures: \n[ERROR] HibernateJUnit5Test.should_find_all_players a performance property is not respected\n\n[PERF] Same SELECT types with different parameter values\n\n\ud83d\udca3 You may have even more select statements with production data.\nBe careful with the cost of JDBC server roundtrips: https:\/\/blog.jooq.org\/2017\/12\/18\/the-cost-of-jdbc-server-roundtrips\/\n\n\ud83d\udca1 Perhaps you are facing an N+1 select issue\n * With Hibernate, you may fix it by using JOIN FETCH\n or LEFT JOIN FETCH\n or FetchType.LAZY\n or ...\n Some examples: https:\/\/stackoverflow.com\/questions\/32453989\/what-is-the-solution-for-the-n1-issue-in-jpa-and-hibernate\";\n https:\/\/stackoverflow.com\/questions\/52850442\/how-to-get-rid-of-n1-with-jpa-criteria-api-in-hibernate\/52945771?stw=2#52945771\n https:\/\/thoughts-on-java.org\/jpa-21-entity-graph-part-1-named-entity\/\n\n[...]\n<\/pre>\n
Frameworks integration<\/h2>\n
\npublic DataSource wrapDatasource(DataSource dataSource){\n ProxyDataSource proxyDataSource = QuickPerfSqlDataSourceBuilder.aDataSourceBuilder()\n .buildProxy(dataSource);\n return proxyDataSource;\n}\n<\/pre>\norg.quickperf:quick-perf-sql-annotations<\/code>, instead you have to add a dedicated library and everything is done automatically. For example, for Spring Boot 2, you have to add the starter quick-perf-springboot2-sql-starter<\/code>.<\/p>\n\n\n org.quickperf\n quick-perf-springboot2-sql-starter\n test\n\n<\/pre>\n