From 42da9f14b44fdfe91c60c95738480ce390749edd Mon Sep 17 00:00:00 2001 From: Matthias Andreas Benkard Date: Thu, 2 Sep 2021 18:47:28 +0200 Subject: Add missing Javadocs. Change-Id: I63f0086ed99a259391ef6094a5218744d4b2fc60 --- .../quarkus/googlecloud/jsonlogging/Formatter.java | 6 + .../GoogleCloudJsonLoggingRecorder.java | 10 ++ .../googlecloud/jsonlogging/KeyValueParameter.java | 93 ++++++++++- .../quarkus/googlecloud/jsonlogging/Label.java | 36 +++- .../googlecloud/jsonlogging/LabelProvider.java | 31 +++- .../jsonlogging/StructuredParameter.java | 6 +- .../jsonlogging/StructuredParameterProvider.java | 39 ++++- .../googlecloud/jsonlogging/package-info.java | 183 +++++++++++++++++++++ 8 files changed, 396 insertions(+), 8 deletions(-) diff --git a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Formatter.java b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Formatter.java index c8bb310..066f709 100644 --- a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Formatter.java +++ b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Formatter.java @@ -32,6 +32,12 @@ public class Formatter extends ExtFormatter { private final List parameterProviders; private final List labelProviders; + /** + * Constructs a {@link Formatter}. + * + * @param parameterProviders the {@link StructuredParameterProvider}s to apply to each log entry. + * @param labelProviders the {@link LabelProvider}s to apply to each log entry. + */ public Formatter( Collection parameterProviders, Collection labelProviders) { diff --git a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/GoogleCloudJsonLoggingRecorder.java b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/GoogleCloudJsonLoggingRecorder.java index a26f4da..7234a71 100644 --- a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/GoogleCloudJsonLoggingRecorder.java +++ b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/GoogleCloudJsonLoggingRecorder.java @@ -3,12 +3,22 @@ package eu.mulk.quarkus.googlecloud.jsonlogging; import io.quarkus.arc.Arc; import io.quarkus.runtime.RuntimeValue; import io.quarkus.runtime.annotations.Recorder; +import java.util.Collection; import java.util.Optional; import java.util.stream.Collectors; /** A Quarkus recorder that registers {@link Formatter} as a log formatter for the application. */ @Recorder public class GoogleCloudJsonLoggingRecorder { + + /** + * Registers {@link Formatter} as a log formatter for the application. + * + *

Collects all discoverable {@link StructuredParameterProvider}s and {@link LabelProvider}s + * and passes them to {@link Formatter#Formatter(Collection, Collection)}. + * + * @return the registered {@link Formatter}. + */ public RuntimeValue> initialize() { var parameterProviders = diff --git a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java index 173d9e2..a5924b4 100644 --- a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java +++ b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java @@ -8,18 +8,29 @@ import javax.json.JsonObjectBuilder; import javax.json.JsonValue; /** - * A simple single key--value pair forming a {@link StructuredParameter}. + * A simple single key–value pair forming a {@link StructuredParameter}. * - *

This class is suitable for the common case of logging a key—value pair as parameter to the + *

This class is suitable for the common case of logging a key–value pair as parameter to the * {@code *f} family of logging functions on {@link org.jboss.logging.Logger}. For advanced use * cases, provide your own implementation of {@link StructuredParameter}. * - *

Example: + *

Example: * * 

{@code
  * logger.infof("Application starting.", StructuredParameter.of("version", "1.0"));
  * }
* + * Result: + * + * 
{@code
+ * {
+ *   "jsonPayload": {
+ *     "message": "Application starting.",
+ *     "version": "1.0"
+ *   }
+ * }
+ * }
+ * * @see Label * @see StructuredParameter */ @@ -33,30 +44,93 @@ public final class KeyValueParameter implements StructuredParameter { this.value = value; } + /** + * Creates a {@link KeyValueParameter} from a {@link String} value. + * + *

The resulting JSON value is of type {@code string}. + * + * @param key the key part of the key–value pair. + * @param value the value part of the key–value pair. + * @return the newly constructed parameter, ready to be passed to a logging function. + */ public static KeyValueParameter of(String key, String value) { return new KeyValueParameter(key, Json.createValue(value)); } + /** + * Creates a {@link KeyValueParameter} from an {@code int} value. + * + *

The resulting JSON value is of type {@code number}. + * + * @param key the key part of the key–value pair. + * @param value the value part of the key–value pair. + * @return the newly constructed parameter, ready to be passed to a logging function. + */ public static KeyValueParameter of(String key, int value) { return new KeyValueParameter(key, Json.createValue(value)); } + /** + * Creates a {@link KeyValueParameter} from a {@code long} value. + * + *

The resulting JSON value is of type {@code number}. + * + * @param key the key part of the key–value pair. + * @param value the value part of the key–value pair. + * @return the newly constructed parameter, ready to be passed to a logging function. + */ public static KeyValueParameter of(String key, long value) { return new KeyValueParameter(key, Json.createValue(value)); } + /** + * Creates a {@link KeyValueParameter} from a {@code double} value. + * + *

The resulting JSON value is of type {@code number}. + * + * @param key the key part of the key–value pair. + * @param value the value part of the key–value pair. + * @return the newly constructed parameter, ready to be passed to a logging function. + */ public static KeyValueParameter of(String key, double value) { return new KeyValueParameter(key, Json.createValue(value)); } + /** + * Creates a {@link KeyValueParameter} from a {@link BigDecimal} value. + * + *

The resulting JSON value is of type {@code number}. + * + * @param key the key part of the key–value pair. + * @param value the value part of the key–value pair. + * @return the newly constructed parameter, ready to be passed to a logging function. + */ public static KeyValueParameter of(String key, BigDecimal value) { return new KeyValueParameter(key, Json.createValue(value)); } + /** + * Creates a {@link KeyValueParameter} from a {@link BigInteger} value. + * + *

The resulting JSON value is of type {@code number}. + * + * @param key the key part of the key–value pair. + * @param value the value part of the key–value pair. + * @return the newly constructed parameter, ready to be passed to a logging function. + */ public static KeyValueParameter of(String key, BigInteger value) { return new KeyValueParameter(key, Json.createValue(value)); } + /** + * Creates a {@link KeyValueParameter} from a {@code boolean} value. + * + *

The resulting JSON value is of type {@code boolean}. + * + * @param key the key part of the key–value pair. + * @param value the value part of the key–value pair. + * @return the newly constructed parameter, ready to be passed to a logging function. + */ public static KeyValueParameter of(String key, boolean value) { return new KeyValueParameter(key, value ? JsonValue.TRUE : JsonValue.FALSE); } @@ -66,10 +140,23 @@ public final class KeyValueParameter implements StructuredParameter { return Json.createObjectBuilder().add(key, value); } + /** + * The key part of the key–value pair. + * + * @return the key part of the key–value pair. + */ public String key() { return key; } + /** + * The value part of the key–value pair. + * + *

Can be of any non-composite JSON type (i.e. {@code string}, {@code number}, or {@code + * boolean}). + * + * @return the value pairt of the key–value pair. + */ public JsonValue value() { return value; } diff --git a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java index 72929f1..33664dd 100644 --- a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java +++ b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java @@ -8,12 +8,23 @@ import java.util.Objects; *

Instances of {@link Label} can be passed as log parameters to the {@code *f} family of logging * functions on {@link org.jboss.logging.Logger}. * - *

Example: + *

Example: * * 

{@code
  * logger.logf("Request rejected: unauthorized.", Label.of("requestId", "123"));
  * }
* + * Result: + * + * 
{@code
+ * {
+ *   "textPayload": "Request rejected: unauthorized.",
+ *   "labels": {
+ *     "requestId": "123"
+ *   }
+ * }
+ * }
+ * * @see KeyValueParameter * @see StructuredParameter */ @@ -27,14 +38,37 @@ public final class Label { this.value = value; } + /** + * Constructs a {@link Label} from a key (i.e. name) and a value. + * + *

It is often useful for the key to be a {@link String} constant that is shared by multiple + * parts of the program. + * + * @param key the key (name) of the label. + * @param value the value of the label. + * @return the newly constructed {@link Label}, ready to be passed to a logging function. + */ public static Label of(String key, String value) { return new Label(key, value); } + /** + * The name of the label. + * + *

It is often useful for this to be a {@link String} constant that is shared by multiple parts + * of the program. + * + * @return the name of the label. + */ public String key() { return key; } + /** + * The value of the label. + * + * @return the value of the label. + */ public String value() { return value; } diff --git a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java index ef31bcc..dbd035c 100644 --- a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java +++ b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java @@ -7,10 +7,39 @@ import java.util.Collection; * *

Any CDI beans registered under this class are applied to each log entry that is logged. * + *

Example: + * + * 

{@code
+ * @Singleton
+ * @Unremovable
+ * public final class RequestIdLabelProvider implements LabelProvider {
+ *
+ *   @Override
+ *   public Collection
+ * + * Result: + * + * 
{@code
+ * {
+ *   "textPayload": "Request rejected: unauthorized.",
+ *   "labels": {
+ *     "requestId": "123"
+ *   }
+ * }
+ * }
+ * * @see StructuredParameterProvider */ public interface LabelProvider { - /** Provides a collection of {@link Label}s to add to each log entry that is logged. */ + /** + * Provides a collection of {@link Label}s to add to each log entry that is logged. + * + * @return a collection of {@link Label}s to add to each log entry that is logged. + */ Collection