1 files changed, 38 insertions, 1 deletions
diff --git a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java
index d8ab39b..cacfea6 100644
--- a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java
+++ b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java
@@ -5,10 +5,47 @@ package eu.mulk.quarkus.googlecloud.jsonlogging;
  *
  * <p>Any CDI beans registered under this class are applied to each log entry that is logged.
  *
+ * <p><strong>Example:</strong>
+ *
+ * <pre>{@code
+ * @Singleton
+ * @Unremovable
+ * public final class TraceLogParameterProvider implements StructuredParameterProvider {
+ *
+ *   @Override
+ *   public StructuredParameter getParameter() {
+ *     var b = Json.createObjectBuilder();
+ *     b.add("traceId", Span.current().getSpanContext().getTraceId());
+ *     b.add("spanId", Span.current().getSpanContext().getSpanId());
+ *     return () -> b;
+ *   }
+ * }
+ * }</pre>
+ *
+ * Result:
+ *
+ * <pre>{@code
+ * {
+ *   "jsonPayload": {
+ *     "message": "Request rejected: unauthorized.",
+ *     "traceId": "39f9a49a9567a8bd7087b708f8932550",
+ *     "spanId": "c7431b14630b633d"
+ *   }
+ * }
+ * }</pre>
+ *
  * @see LabelProvider
  */
 public interface StructuredParameterProvider {
 
-  /** Provides a {@link StructuredParameter} to add to each log entry that is logged. */
+  /**
+   * Provides a {@link StructuredParameter} to add to each log entry that is logged.
+   *
+   * <p>It is often useful to return a custom {@link StructuredParameter} rather than a {@link
+   * KeyValueParameter} from this method. This way multiple key–value pairs can be generated by a
+   * single invocation.
+   *
+   * @return a {@link StructuredParameter} to add to each log entry that is logged.
+   */
   StructuredParameter getParameter();
 }