Improve structured logging docs

Author: felixbarny

log4j2-ecs-layout/README.md

@@ -58,6 +58,7 @@ To include any custom field in the output, use following syntax:
 ```
 
 Custom fields are included in the order they are declared. The values support [lookups](https://logging.apache.org/log4j/2.x/manual/lookups.html).
+
 ## Structured logging
 
 By leveraging log4j2's `MapMessage` or even by implementing your own `MultiformatMessage` with JSON support,
@@ -66,9 +67,19 @@ you can add additional fields to the resulting JSON.
 Example:
 
 ```java
-logger.info(new StringMapMessage().with("message", "foo").with("foo", "bar"));
+logger.info(new StringMapMessage()
+    .with("message", "Hello World!")
+    .with("foo", "bar"));
 ``` 
 
+### Tips
+It's recommended to use existing [ECS fields](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html).
+
+If there is no appropriate ECS field,
+consider prefixing your fields with `labels.`, as in `labels.foo`, for simple key/value pairs.
+For nested structures consider prefixing with `custom.` to make sure you won't get conflicts if ECS later adds the same fields but with a different mapping.
+
+
 ### Gotchas
 
 A common pitfall is how dots in field names are handled in Elasticsearch and how they affect the mapping.

log4j2-ecs-layout/src/test/java/co/elastic/logging/log4j2/AbstractLog4j2EcsLayoutTest.java

@@ -84,6 +84,13 @@ void testMapMessage() throws Exception {
         assertThat(log.get("foo").textValue()).isEqualTo("bar");
     }
 
+    @Test
+    void testParameterizedStructuredMessage() throws Exception {
+        root.info(ParameterizedStructuredMessage.of("hello {}", "world").with("foo", "bar"));
+        assertThat(getLastLogLine().get("message").textValue()).isEqualTo("hello world");
+        assertThat(getLastLogLine().get("foo").textValue()).isEqualTo("bar");
+    }
+
     @Test
     void testCustomPatternConverter() throws Exception {
         debug("test");

log4j2-ecs-layout/src/test/java/co/elastic/logging/log4j2/ParameterizedStructuredMessage.java

@@ -0,0 +1,48 @@
+package co.elastic.logging.log4j2;
+
+import org.apache.logging.log4j.message.MapMessage;
+import org.apache.logging.log4j.message.ParameterizedMessage;
+import org.apache.logging.log4j.util.TriConsumer;
+
+public class ParameterizedStructuredMessage extends MapMessage<ParameterizedStructuredMessage, Object> {
+
+    private static final String MESSAGE = "message";
+    private static final TriConsumer<String, Object, StringBuilder> ADD_KEY_VALUE_PAIR = new TriConsumer<>() {
+        @Override
+        public void accept(String key, Object value, StringBuilder builder) {
+            if (!MESSAGE.equals(key)) {
+                builder.append(' ').append(key).append('[').append(value).append(']');
+            }
+        }
+    };
+
+    private final String message;
+
+    private ParameterizedStructuredMessage(String message) {
+        this.message = message;
+        with(MESSAGE, message);
+    }
+
+    private ParameterizedStructuredMessage(String messagePattern, Object... arguments) {
+        this.message = ParameterizedMessage.format(messagePattern, arguments);
+        with(MESSAGE, message);
+    }
+
+    public static ParameterizedStructuredMessage of(String message) {
+        return new ParameterizedStructuredMessage(message);
+    }
+
+    public static ParameterizedStructuredMessage of(String messagePattern, Object... arguments) {
+        return new ParameterizedStructuredMessage(messagePattern, arguments);
+    }
+
+    @Override
+    protected void asJson(StringBuilder sb) {
+        super.asJson(sb);
+    }
+
+    protected void appendMap(final StringBuilder sb) {
+        sb.append(message);
+        forEach(ADD_KEY_VALUE_PAIR, sb);
+    }
+}