Document and fix topLevelLabels

Author: felixbarny

ecs-logging-core/src/test/java/co/elastic/logging/AbstractEcsLoggingTest.java

@@ -76,9 +76,11 @@ void testThreadContextStack() throws Exception {
     @Test
     void testTopLevelLabels() throws Exception {
         putMdc("transaction.id", "0af7651916cd43dd8448eb211c80319c");
+        putMdc("span.id", "foo");
         debug("test");
         assertThat(getLastLogLine().get("labels.transaction.id")).isNull();
         assertThat(getLastLogLine().get("transaction.id").textValue()).isEqualTo("0af7651916cd43dd8448eb211c80319c");
+        assertThat(getLastLogLine().get("span.id").textValue()).isEqualTo("foo");
     }
 
     @Test

log4j2-ecs-layout/README.md

@@ -45,6 +45,7 @@ Instead of the usual `<PatternLayout/>`, use `<EcsLayout serviceName="my-app"/>`
 |Parameter name   |Type   |Default|Description|
 |-----------------|-------|-------|-----------|
 |serviceName      |String |       |Sets the `service.name` field so you can filter your logs by a particular service |
+|topLevelLabels   |String |`trace.id, transaction.id, span.id, error.id, service.name`|Usually, MDC keys are nested under `labels`[https://www.elastic.co/guide/en/ecs/current/ecs-base.html]. You can specify a comma-separated list of properties which should be on the top level. |
 |includeMarkers   |boolean|`false`|Log [Markers](https://logging.apache.org/log4j/2.0/manual/markers.html) as `tags` |
 |stackTraceAsArray|boolean|`false`|Serializes the `error.stack_trace` as a JSON array where each element is in a new line to improve readability. Note that this requires a slightly more complex [Filebeat configuration](../README.md#when-stacktraceasarray-is-enabled).|
 |includeOrigin    |boolean|`false`|If `true`, adds the `log.origin.file`, `log.origin.function` and `log.origin.line` fields. Note that you also have to set `includeLocation="true"` on your loggers and appenders if you are using the async ones. |

log4j2-ecs-layout/src/main/java/co/elastic/logging/log4j2/EcsLayout.java

@@ -50,9 +50,8 @@
 import org.apache.logging.log4j.util.TriConsumer;
 
 import java.nio.charset.Charset;
-import java.util.Arrays;
+import java.util.ArrayList;
 import java.util.Collection;
-import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
@@ -93,10 +92,9 @@ private EcsLayout(Configuration config, String serviceName, boolean includeMarke
         this.serviceName = serviceName;
         this.includeMarkers = includeMarkers;
         this.topLevelLabels = new HashSet<String>(topLevelLabels);
+        this.topLevelLabels.addAll(EcsJsonSerializer.DEFAULT_TOP_LEVEL_LABELS);
         this.includeOrigin = includeOrigin;
         this.stackTraceAsArray = stackTraceAsArray;
-        this.topLevelLabels.add("trace.id");
-        this.topLevelLabels.add("transaction.id");
         this.additionalFields = additionalFields;
         fieldValuePatternFormatter = new PatternFormatter[additionalFields.length][];
         for (int i = 0; i < additionalFields.length; i++) {
@@ -313,8 +311,8 @@ public static class Builder extends AbstractStringLayout.Builder<EcsLayout.Build
         private boolean stackTraceAsArray = false;
         @PluginElement("AdditionalField")
         private KeyValuePair[] additionalFields;
-        @PluginElement("TopLevelLabels")
-        private String[] topLevelLabels;
+        @PluginBuilderAttribute("topLevelLabels")
+        private String topLevelLabels;
         @PluginBuilderAttribute("includeOrigin")
         private boolean includeOrigin;
 
@@ -339,11 +337,11 @@ public boolean isIncludeOrigin() {
             return includeOrigin;
         }
 
-        public String[] getTopLevelLabels() {
+        public String getTopLevelLabels() {
             return topLevelLabels;
         }
 
-        public EcsLayout.Builder setTopLevelLabels(final String[] topLevelLabels) {
+        public EcsLayout.Builder setTopLevelLabels(final String topLevelLabels) {
             this.topLevelLabels = topLevelLabels;
             return asBuilder();
         }
@@ -380,7 +378,13 @@ public EcsLayout.Builder setStackTraceAsArray(boolean stackTraceAsArray) {
 
         @Override
         public EcsLayout build() {
-            return new EcsLayout(getConfiguration(), serviceName, includeMarkers, additionalFields, topLevelLabels == null ? Collections.<String>emptyList() : Arrays.<String>asList(topLevelLabels), includeOrigin, stackTraceAsArray);
+            List<String> topLevelLabelsList = new ArrayList<String>();
+            if (topLevelLabels != null) {
+                for (String label : topLevelLabels.split(",")) {
+                    topLevelLabelsList.add(label.trim());
+                }
+            }
+            return new EcsLayout(getConfiguration(), serviceName, includeMarkers, additionalFields, topLevelLabelsList, includeOrigin, stackTraceAsArray);
         }
 
         public boolean isStackTraceAsArray() {

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

@@ -50,13 +50,17 @@ void tearDown() throws Exception {
     @Test
     void globalLabels() throws Exception {
         putMdc("trace.id", "foo");
+        putMdc("top_level", "foo");
+        putMdc("nested_under_labels", "foo");
         debug("test");
         assertThat(getLastLogLine().get("cluster.uuid").textValue()).isEqualTo("9fe9134b-20b0-465e-acf9-8cc09ac9053b");
         assertThat(getLastLogLine().get("node.id").textValue()).isEqualTo("foo");
         assertThat(getLastLogLine().get("empty")).isNull();
         assertThat(getLastLogLine().get("emptyPattern")).isNull();
         assertThat(getLastLogLine().get("clazz").textValue()).startsWith(getClass().getPackageName());
         assertThat(getLastLogLine().get("404")).isNull();
+        assertThat(getLastLogLine().get("top_level").textValue()).isEqualTo("foo");
+        assertThat(getLastLogLine().get("labels.nested_under_labels").textValue()).isEqualTo("foo");
     }
 
     @Test

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

@@ -70,6 +70,7 @@ void setUp() {
                 .setIncludeMarkers(true)
                 .setIncludeOrigin(true)
                 .setStackTraceAsArray(true)
+                .setTopLevelLabels("top_level")
                 .setAdditionalFields(new KeyValuePair[]{
                         new KeyValuePair("cluster.uuid", "9fe9134b-20b0-465e-acf9-8cc09ac9053b"),
                         new KeyValuePair("node.id", "${node.id}"),

log4j2-ecs-layout/src/test/resources/log4j2-test.xml

@@ -5,7 +5,7 @@
     </Properties>
     <Appenders>
         <List name="TestAppender">
-            <EcsLayout serviceName="test" includeMarkers="true" includeOrigin="true" stackTraceAsArray="true">
+            <EcsLayout serviceName="test" includeMarkers="true" includeOrigin="true" stackTraceAsArray="true" topLevelLabels="top_level">
                 <KeyValuePair key="cluster.uuid" value="9fe9134b-20b0-465e-acf9-8cc09ac9053b"/>
                 <KeyValuePair key="node.id" value="${node.id}"/>
                 <KeyValuePair key="empty" value="${empty}"/>