From 33116268807596effae58e727eba9a76b4477da5 Mon Sep 17 00:00:00 2001 From: Lucas Pedroza Date: Wed, 6 Nov 2024 14:53:57 +0100 Subject: [PATCH] Add javadocs for query stats classes --- .../com/fauna/client/QueryStatsSummary.java | 59 +++-- .../com/fauna/client/StatsCollectorImpl.java | 18 +- .../java/com/fauna/client/package-info.java | 5 + .../java/com/fauna/response/QueryStats.java | 206 +++++++++++++----- .../java/com/fauna/response/package-info.java | 4 + .../fauna/exception/TestServiceException.java | 2 +- .../java/com/fauna/perf/PerformanceTest.java | 8 +- 7 files changed, 213 insertions(+), 89 deletions(-) create mode 100644 src/main/java/com/fauna/client/package-info.java create mode 100644 src/main/java/com/fauna/response/package-info.java diff --git a/src/main/java/com/fauna/client/QueryStatsSummary.java b/src/main/java/com/fauna/client/QueryStatsSummary.java index 9f520a87..af767ff0 100644 --- a/src/main/java/com/fauna/client/QueryStatsSummary.java +++ b/src/main/java/com/fauna/client/QueryStatsSummary.java @@ -21,19 +21,39 @@ public final class QueryStatsSummary { private final int rateLimitedComputeQueryCount; private final int rateLimitedWriteQueryCount; + /** + * @param readOps the read ops + * @param computeOps the compute ops + * @param writeOps the write ops + * @param queryTimeMs the query time in milliseconds + * @param contentionRetries the number of retries due to + * contention + * @param storageBytesRead the number of storage bytes read + * @param storageBytesWrite the number of storage bytes written + * @param processingTimeMs the event processing time in + * milliseconds + * @param queryCount the number of queries included in the + * summary + * @param rateLimitedReadQueryCount the count of queries limited + * by read ops + * @param rateLimitedComputeQueryCount the count of queries limited + * by compute ops + * @param rateLimitedWriteQueryCount the count of queries limited + * by write ops + */ public QueryStatsSummary( - long readOps, - long computeOps, - long writeOps, - long queryTimeMs, - int contentionRetries, - long storageBytesRead, - long storageBytesWrite, - long processingTimeMs, - int queryCount, - int rateLimitedReadQueryCount, - int rateLimitedComputeQueryCount, - int rateLimitedWriteQueryCount + final long readOps, + final long computeOps, + final long writeOps, + final long queryTimeMs, + final int contentionRetries, + final long storageBytesRead, + final long storageBytesWrite, + final long processingTimeMs, + final int queryCount, + final int rateLimitedReadQueryCount, + final int rateLimitedComputeQueryCount, + final int rateLimitedWriteQueryCount ) { this.readOps = readOps; this.computeOps = computeOps; @@ -50,7 +70,7 @@ public QueryStatsSummary( } /** - * Gets the aggregate read ops. + * Gets the aggregate Transactional Read Operations (TROs) recorded. * * @return A long representing the aggregate read ops */ @@ -59,7 +79,7 @@ public long getReadOps() { } /** - * Gets the aggregate compute ops. + * Gets the aggregate Transactional Compute Operations (TCOs) recorded. * * @return A long representing the aggregate compute ops */ @@ -68,7 +88,7 @@ public long getComputeOps() { } /** - * Gets the aggregate write ops. + * Gets the aggregate Transactional Write Operations (TWOs) recorded. * * @return A long representing the aggregate write ops */ @@ -106,16 +126,19 @@ public long getStorageBytesRead() { /** * Gets the aggregate storage bytes written. * - * @return A long representing the aggregate number of storage bytes written. + * @return A long representing the aggregate number of storage bytes + * written. */ public long getStorageBytesWrite() { return storageBytesWrite; } /** - * Gets the aggregate processing time in milliseconds. + * Gets the aggregate event processing time in milliseconds. + * Applies to Streams and Feeds only. * - * @return A long representing the aggregate processing time in milliseconds. + * @return A long representing the aggregate processing time in + * milliseconds. */ public long getProcessingTimeMs() { return processingTimeMs; diff --git a/src/main/java/com/fauna/client/StatsCollectorImpl.java b/src/main/java/com/fauna/client/StatsCollectorImpl.java index fd03f1d4..490ea890 100644 --- a/src/main/java/com/fauna/client/StatsCollectorImpl.java +++ b/src/main/java/com/fauna/client/StatsCollectorImpl.java @@ -29,16 +29,16 @@ public class StatsCollectorImpl implements StatsCollector { @Override public void add(QueryStats stats) { - readOps.addAndGet(stats.readOps); - computeOps.addAndGet(stats.computeOps); - writeOps.addAndGet(stats.writeOps); - queryTimeMs.addAndGet(stats.queryTimeMs); - contentionRetries.addAndGet(stats.contentionRetries); - storageBytesRead.addAndGet(stats.storageBytesRead); - storageBytesWrite.addAndGet(stats.storageBytesWrite); - processingTimeMs.addAndGet(stats.processingTimeMs); + readOps.addAndGet(stats.getReadOps()); + computeOps.addAndGet(stats.getComputeOps()); + writeOps.addAndGet(stats.getWriteOps()); + queryTimeMs.addAndGet(stats.getQueryTimeMs()); + contentionRetries.addAndGet(stats.getContentionRetries()); + storageBytesRead.addAndGet(stats.getStorageBytesRead()); + storageBytesWrite.addAndGet(stats.getStorageBytesWrite()); + processingTimeMs.addAndGet(stats.getProcessingTimeMs()); - List rateLimitsHit = stats.rateLimitsHit; + List rateLimitsHit = stats.getRateLimitsHit(); rateLimitsHit.forEach(limitHit -> { switch (limitHit) { case RATE_LIMIT_READ_OPS: diff --git a/src/main/java/com/fauna/client/package-info.java b/src/main/java/com/fauna/client/package-info.java new file mode 100644 index 00000000..17531599 --- /dev/null +++ b/src/main/java/com/fauna/client/package-info.java @@ -0,0 +1,5 @@ +/** + * Classes related initializing, configuring, and using a client to interact + * with Fauna. + */ +package com.fauna.client; diff --git a/src/main/java/com/fauna/response/QueryStats.java b/src/main/java/com/fauna/response/QueryStats.java index d29110b2..894f48f7 100644 --- a/src/main/java/com/fauna/response/QueryStats.java +++ b/src/main/java/com/fauna/response/QueryStats.java @@ -16,30 +16,35 @@ public final class QueryStats { - public final int computeOps; - - public final int readOps; - - public final int writeOps; - - public final int queryTimeMs; - - public final int processingTimeMs; - - public final int contentionRetries; - - public final int storageBytesRead; - - public final int storageBytesWrite; - - public final List rateLimitsHit; + private final int computeOps; + private final int readOps; + private final int writeOps; + private final int queryTimeMs; + private final int processingTimeMs; + private final int contentionRetries; + private final int storageBytesRead; + private final int storageBytesWrite; + private final List rateLimitsHit; private String stringValue = null; - public QueryStats(int computeOps, int readOps, int writeOps, - int queryTimeMs, int contentionRetries, - int storageBytesRead, int storageBytesWrite, - int processingTimeMs, List rateLimitsHit) { + /** + * @param computeOps the compute ops + * @param readOps the read ops + * @param writeOps the write ops + * @param queryTimeMs the query time in milliseconds + * @param contentionRetries the number of retries due to contention + * @param storageBytesRead the number of storage bytes read + * @param storageBytesWrite the number of storage bytes written + * @param processingTimeMs the event processing time in milliseconds + * @param rateLimitsHit the rate limits hit + */ + public QueryStats(final int computeOps, final int readOps, + final int writeOps, + final int queryTimeMs, final int contentionRetries, + final int storageBytesRead, final int storageBytesWrite, + final int processingTimeMs, + final List rateLimitsHit) { this.computeOps = computeOps; this.readOps = readOps; this.writeOps = writeOps; @@ -51,59 +56,141 @@ public QueryStats(int computeOps, int readOps, int writeOps, this.rateLimitsHit = rateLimitsHit != null ? rateLimitsHit : List.of(); } + /** + * Gets the Transactional Compute Operations (TCOs) recorded. + * + * @return An int representing the compute ops. + */ + public int getComputeOps() { + return computeOps; + } + + /** + * Gets the Transactional Read Operations (TROs) recorded. + * + * @return An int representing the read ops. + */ + public int getReadOps() { + return readOps; + } + + /** + * Gets the Transactional Write Operations (TWOs) recorded. + * + * @return An int representing the write ops. + */ + public int getWriteOps() { + return writeOps; + } + + /** + * Gets the query time in milliseconds. + * + * @return An int representing the query time in milliseconds. + */ + public int getQueryTimeMs() { + return queryTimeMs; + } + + /** + * Gets the event processing time in milliseconds. + * Applies to Streams and Feeds only. + * + * @return An int representing the processing time in milliseconds. + */ + public int getProcessingTimeMs() { + return processingTimeMs; + } + + /** + * Gets the number of retries due to transaction contention. + * + * @return An int representing the number of transaction contention retries. + */ + public int getContentionRetries() { + return contentionRetries; + } + + /** + * Gets the amount of data read from storage in bytes. + * + * @return An int representing the number of bytes read. + */ + public int getStorageBytesRead() { + return storageBytesRead; + } + + /** + * Gets the amount of data written to storage in bytes. + * + * @return An int representing the number of bytes written. + */ + public int getStorageBytesWrite() { + return storageBytesWrite; + } + + /** + * Gets a list of operations that exceeded their rate limit. + * + * @return A list of operations that exceeded their rate limit. + */ + public List getRateLimitsHit() { + return rateLimitsHit; + } + static class Builder { - int computeOps; - int readOps; - int writeOps; - int queryTimeMs; - int contentionRetries; - int storageBytesRead; - int storageBytesWrite; - int processingTimeMs; - List rateLimitsHit; - - Builder computeOps(int computeOps) { - this.computeOps = computeOps; + private int computeOps; + private int readOps; + private int writeOps; + private int queryTimeMs; + private int contentionRetries; + private int storageBytesRead; + private int storageBytesWrite; + private int processingTimeMs; + private List rateLimitsHit; + + Builder computeOps(final int value) { + this.computeOps = value; return this; } - Builder readOps(int readOps) { - this.readOps = readOps; + Builder readOps(final int value) { + this.readOps = value; return this; } - Builder writeOps(int writeOps) { - this.writeOps = writeOps; + Builder writeOps(final int value) { + this.writeOps = value; return this; } - Builder queryTimeMs(int queryTimeMs) { - this.queryTimeMs = queryTimeMs; + Builder queryTimeMs(final int value) { + this.queryTimeMs = value; return this; } - Builder contentionRetries(int contentionRetries) { - this.contentionRetries = contentionRetries; + Builder contentionRetries(final int value) { + this.contentionRetries = value; return this; } - Builder storageBytesRead(int storageBytesRead) { - this.storageBytesRead = storageBytesRead; + Builder storageBytesRead(final int value) { + this.storageBytesRead = value; return this; } - Builder storageBytesWrite(int storageBytesWrite) { - this.storageBytesWrite = storageBytesWrite; + Builder storageBytesWrite(final int value) { + this.storageBytesWrite = value; return this; } - Builder processingTimeMs(int processingTimeMs) { - this.processingTimeMs = processingTimeMs; + Builder processingTimeMs(final int value) { + this.processingTimeMs = value; return this; } - Builder rateLimitsHit(List rateLimitsHit) { - this.rateLimitsHit = rateLimitsHit; + Builder rateLimitsHit(final List value) { + this.rateLimitsHit = value; return this; } @@ -112,14 +199,13 @@ QueryStats build() { contentionRetries, storageBytesRead, storageBytesWrite, processingTimeMs, rateLimitsHit); } - } static Builder builder() { return new Builder(); } - static Builder parseField(Builder builder, JsonParser parser) + static Builder parseField(final Builder builder, final JsonParser parser) throws IOException { String fieldName = parser.getValueAsString(); switch (fieldName) { @@ -152,8 +238,15 @@ static Builder parseField(Builder builder, JsonParser parser) } } - - public static QueryStats parseStats(JsonParser parser) throws IOException { + /** + * Parse QueryStats from a JsonParser. + * + * @param parser the JsonParser to consume + * @return a QueryStats object containing the parsed stats + * @throws IOException thrown from the JsonParser + */ + public static QueryStats parseStats(final JsonParser parser) + throws IOException { if (parser.nextToken() == START_OBJECT) { Builder builder = builder(); while (parser.nextToken() == FIELD_NAME) { @@ -164,14 +257,13 @@ public static QueryStats parseStats(JsonParser parser) throws IOException { return null; } else { throw new ClientResponseException( - "Query stats should be an object or null, not " + - parser.getCurrentToken()); + "Query stats should be an object or null, not " + + parser.getCurrentToken()); } } - private static String statString(String name, Object value) { + private static String statString(final String name, final Object value) { return String.join(": ", name, String.valueOf(value)); - } @Override diff --git a/src/main/java/com/fauna/response/package-info.java b/src/main/java/com/fauna/response/package-info.java new file mode 100644 index 00000000..ef472810 --- /dev/null +++ b/src/main/java/com/fauna/response/package-info.java @@ -0,0 +1,4 @@ +/** + * Classes for modeling and handling query responses from Fauna. + */ +package com.fauna.response; diff --git a/src/test/java/com/fauna/exception/TestServiceException.java b/src/test/java/com/fauna/exception/TestServiceException.java index 998eb65a..40b03165 100644 --- a/src/test/java/com/fauna/exception/TestServiceException.java +++ b/src/test/java/com/fauna/exception/TestServiceException.java @@ -45,7 +45,7 @@ public void testGetters() throws IOException { assertEquals("500 (bad_thing): message in a bottle\n---\nsummarized", exc.getMessage()); assertEquals("summarized", exc.getSummary()); - assertEquals(100, exc.getStats().computeOps); + assertEquals(100, exc.getStats().getComputeOps()); assertEquals(10, exc.getSchemaVersion()); assertEquals(Optional.of(Long.MAX_VALUE / 4), exc.getTxnTs()); assertEquals(Map.of("foo", "bar"), exc.getQueryTags()); diff --git a/src/test/java/com/fauna/perf/PerformanceTest.java b/src/test/java/com/fauna/perf/PerformanceTest.java index a16dabe9..f040b497 100644 --- a/src/test/java/com/fauna/perf/PerformanceTest.java +++ b/src/test/java/com/fauna/perf/PerformanceTest.java @@ -65,7 +65,7 @@ public void executeQueryAndCollectStats(String name, var result = client.asyncQuery(query, pageOf(Product.class)).get(); int queryCount = 1; - int queryTimeAgg = result.getStats().queryTimeMs; + int queryTimeAgg = result.getStats().getQueryTimeMs(); while (result.getData().getAfter().isPresent()) { AfterToken after = result.getData().getAfter().get(); @@ -74,7 +74,7 @@ public void executeQueryAndCollectStats(String name, Map.of("after", after.getToken())), pageOf(Product.class)).get(); queryCount++; - queryTimeAgg += result.getStats().queryTimeMs; + queryTimeAgg += result.getStats().getQueryTimeMs(); } long endTime = System.currentTimeMillis(); @@ -86,12 +86,12 @@ public void executeQueryAndCollectStats(String name, } else if (typed) { future = client.asyncQuery(query, Product.class) .thenAccept(result -> { - queryTime.set(result.getStats().queryTimeMs); + queryTime.set(result.getStats().getQueryTimeMs()); }); } else { future = client.asyncQuery(query) .thenAccept(result -> { - queryTime.set(result.getStats().queryTimeMs); + queryTime.set(result.getStats().getQueryTimeMs()); }); }