Add notes to setup guide

felixbarny · felixbarny · commit 1344dadbb745 · 2020-12-07T12:35:51.000+01:00
diff --git a/docs/tab-widgets/add-dependency.asciidoc b/docs/tab-widgets/add-dependency.asciidoc
@@ -13,9 +13,10 @@ Add a dependency to your application:
 </dependency>
 ----
 
-If you are not using a dependency management tool, like maven, you have to manually add both
+NOTE: If you are not using a dependency management tool, like maven, you have to manually add both
 `logback-ecs-encoder` and `ecs-logging-core` jars to the classpath.
 For example to the `$CATALINA_HOME/lib` directory.
+Other than that, there are no required dependencies.
 // end::logback[]
 
 // tag::log4j2[]
@@ -33,9 +34,10 @@ Add a dependency to your application:
 </dependency>
 ----
 
-If you are not using a dependency management tool, like maven, you have to manually add both
+NOTE: If you are not using a dependency management tool, like maven, you have to manually add both
 `log4j2-ecs-layout` and `ecs-logging-core` jars to the classpath.
 For example, to the `$CATALINA_HOME/lib` directory.
+Other than that, there are no required dependencies.
 // end::log4j2[]
 
 // tag::log4j[]
@@ -54,9 +56,10 @@ Add a dependency to your application:
 </dependency>
 ----
 
-If you are not using a dependency management tool, like maven, you have to manually add both
+NOTE: If you are not using a dependency management tool, like maven, you have to manually add both
 `log4j-ecs-layout` and `ecs-logging-core` jars to the classpath.
 For example, to the `$CATALINA_HOME/lib` directory.
+Other than that, there are no required dependencies.
 // end::log4j[]
 
 // tag::jul[]
@@ -75,9 +78,10 @@ Add a dependency to your application:
 </dependency>
 ----
 
-If you are not using a dependency management tool, like maven, you have to manually add both
+NOTE: If you are not using a dependency management tool, like maven, you have to manually add both
 `jul-ecs-formatter` and `ecs-logging-core` jars to the classpath.
 For example, to the `$CATALINA_HOME/lib` directory.
+Other than that, there are no required dependencies.
 
 // end::jul[]
 
@@ -97,7 +101,7 @@ Add a dependency to your application:
 </dependency>
 ----
 
-If you are not using a dependency management tool, like maven, you have to manually add both
+NOTE: If you are not using a dependency management tool, like maven, you have to manually add both
 `jboss-logmanager-ecs-formatter` and `ecs-logging-core` jars to the classpath.
-
+Other than that, there are no required dependencies.
 // end::jboss[]
diff --git a/docs/tab-widgets/ecs-encoder.asciidoc b/docs/tab-widgets/ecs-encoder.asciidoc
@@ -163,8 +163,8 @@ To include any custom field in the output, use following syntax:
 
 Custom fields are included in the order they are declared. The values support https://logging.apache.org/log4j/2.x/manual/lookups.html[lookups].
 
-
-
+NOTE: The log4j2 `EcsLayout` does not allocate any memory (unless the log event contains an `Exception`) to reduce GC pressure.
+This is achieved by manually serializing JSON so that no intermediate JSON or map representation of a log event is needed.
 // end::log4j2[]
 
 // tag::log4j[]
diff --git a/ecs-logging-core/src/test/java/co/elastic/logging/AbstractEcsLoggingTest.java b/ecs-logging-core/src/test/java/co/elastic/logging/AbstractEcsLoggingTest.java
@@ -96,6 +96,9 @@ void validateLog(JsonNode logLine) {
             validateRequiredField(logLine, specFieldName, specForField.get("required").booleanValue());
             if (fieldInLog != null) {
                 validateIndex(logLine, logFieldNames, specFieldName, specForField.get("index"));
+                if (specForField.has("nesting_allowed") && !specForField.get("nesting_allowed").asBoolean(true)) {
+                    assertThat(logLine.at(specFieldName)).isNull();
+                }
                 validateType(fieldInLog, specForField.get("type").textValue());
             }
         }
diff --git a/ecs-logging-core/src/test/resources/spec/spec.json b/ecs-logging-core/src/test/resources/spec/spec.json
@@ -15,6 +15,7 @@
       "type": "string",
       "required": true,
       "index": 1,
+      "nesting_allowed": false,
       "url": "https://www.elastic.co/guide/en/ecs/current/ecs-log.html"
     },
     "message": {
@@ -34,14 +35,94 @@
       "url": "https://www.elastic.co/guide/en/ecs/current/ecs-base.html",
       "sanitization": {
         "key": {
-          "replacements": [
-            ".",
-            "*",
-            "\\"
-          ],
+          "replacements": [".", "*", "\\"],
           "substitute": "_"
         }
       }
+    },
+    "trace.id": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-tracing.html",
+      "comment": "When APM agents add this field to the context, ecs loggers should pick it up and add it to the log event."
+    },
+    "transaction.id": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-tracing.html",
+      "comment": "When APM agents add this field to the context, ecs loggers should pick it up and add it to the log event."
+    },
+    "service.name": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-service.html",
+      "comment": [
+        "Configurable by users.",
+        "When an APM agent is active, they should auto-configure it if not already set."
+      ]
+    },
+    "event.dataset": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-event.html",
+      "default": "${service.name}.log OR ${service.name}.${appender.name}",
+      "comment": [
+        "Configurable by users.",
+        "If the user manually configures the service name,",
+        "the logging library should set `event.dataset=${service.name}.log` if not explicitly configured otherwise.",
+        "",
+        "When agents auto-configure the app to use an ECS logger,",
+        "they should set `event.dataset=${service.name}.${appender.name}` if the appender name is available in the logging library.",
+        "Otherwise, agents should also set `event.dataset=${service.name}.log`",
+        "",
+        "The field helps to filter for different log streams from the same pod, for example and is required for log anomaly detection."
+      ]
+    },
+    "process.thread.name": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-process.html"
+    },
+    "log.logger": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-log.html"
+    },
+    "log.origin.file.line": {
+      "type": "integer",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-log.html",
+      "comment": "Should be opt-in as it requires the logging library to capture a stack trace for each log event."
+    },
+    "log.origin.file.name": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-log.html",
+      "comment": "Should be opt-in as it requires the logging library to capture a stack trace for each log event."
+    },
+    "log.origin.function": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-log.html",
+      "comment": "Should be opt-in as it requires the logging library to capture a stack trace for each log event."
+    },
+    "error.type": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-error.html",
+      "comment": "The exception type or class, such as `java.lang.IllegalArgumentException`."
+    },
+    "error.message": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-error.html",
+      "comment": "The message of the exception."
+    },
+    "error.stack_trace": {
+      "type": "string",
+      "required": false,
+      "url": "https://www.elastic.co/guide/en/ecs/current/ecs-error.html",
+      "comment": "The stack trace of the exception as plain text."
     }
   }
 }

Original file line number	Diff line number	Diff line change
`@@ -96,6 +96,9 @@ void validateLog(JsonNode logLine) {`
`96`	`96`	`validateRequiredField(logLine, specFieldName, specForField.get("required").booleanValue());`
`97`	`97`	`if (fieldInLog != null) {`
`98`	`98`	`validateIndex(logLine, logFieldNames, specFieldName, specForField.get("index"));`
	`99`	`+ if (specForField.has("nesting_allowed") && !specForField.get("nesting_allowed").asBoolean(true)) {`
	`100`	`+ assertThat(logLine.at(specFieldName)).isNull();`
	`101`	`+ }`
`99`	`102`	`validateType(fieldInLog, specForField.get("type").textValue());`
`100`	`103`	`}`
`101`	`104`	`}`