vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633740014
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -16,422 +16,479 @@
////
= JSON Template Layout
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
-generating layout. It encodes ``LogEvent``s according to the structure
described
-by the JSON template provided. In a nutshell, it shines with its
+JSON Template Layout is a customizable, xref:#performance[efficient], and
xref:#faq-garbage-free[garbage-free] JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON
template provided.
+In a nutshell, it shines with its
-* Customizable JSON structure (see `eventTemplate[Uri]` and
- `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration]
parameters)
+* Customizable JSON structure (see `eventTemplate[Uri]` and
`stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration]
parameters)
-* Customizable timestamp formatting (see
xref:#event-template-resolver-timestamp[]
- event template resolver)
+* Customizable timestamp formatting (see
xref:#event-template-resolver-timestamp[] event template resolver)
-* Feature rich exception formatting (see
xref:#event-template-resolver-exception[]
- and xref:#event-template-resolver-exceptionRootCause[] event template
resolvers)
+* Feature rich exception formatting (see
xref:#event-template-resolver-exception[] and
xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
* xref:manual/extending.adoc[Extensible plugin support]
* Customizable object xref:#recycling-strategy[recycling strategy]
+[TIP]
+====
+JSON Template Layout is intended for production deployments where the
generated logs are expected to be delivered to an external log ingestion system
such as Elasticsearch or Google Cloud Logging.
+While running tests or developing locally, you can use
xref:manual/pattern-layout.adoc[] for human-readable log output.
+====
+
[#usage]
== Usage
-Adding `log4j-layout-template-json` artifact to your list of dependencies is
-enough to enable access to `JsonTemplateLayout` in your Log4j configuration:
+Adding `log4j-layout-template-json` artifact to your list of dependencies is
enough to enable access to JSON Template Layout in your Log4j configuration:
+[tabs]
+====
+Maven::
++
[source,xml,subs="+attributes"]
----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-layout-template-json</artifactId>
- <version>{log4j-layout-template-json-version}</version>
-</dependency>
+<project>
+
+ <!-- Assuming `log4j-bom` is imported --><!--1-->
+
+ <dependency>
+
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <scope>runtime</scope><!--2-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
+dependencies {
+
+ // Assuming `log4j-bom` is imported <1>
-For instance, given the following JSON template modelling
-https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic
Common Schema (ECS) specification]
-(accessible via `classpath:EcsLayout.json`)
+ runtimeOnly // <2>
+ 'org.apache.logging.log4j:log4j-slf4j2-impl'
+
+}
+----
+====
+<1> Assuming you xref:manual/installation.adoc#bom[imported
`org.apache.logging.log4j:log4j-bom`]
+<2> For applications, logging implementation dependencies are required at
_runtime_.
+If you want to use JSON Template Layout for tests, you need to switch the
scope to _test_.
+See xref:manual/installation.adoc[] for details.
+
+JSON Template Layout is primarily configured through an *event template*
describing the structure log events should be JSON-encoded in.
+Event templates themselves are also JSON documents, where objects containing
`$resolver` members, such as,
+
+[source,json]
+----
+{
+ "$resolver": "message", // <1>
+ "stringified": true // <2>
+}
+----
+<1> Indicating that this object should be replaced with the output from the
xref:#event-template-resolver-message[`message` *event template resolver*]
+<2> Passing a configuration to the `message` event template resolver
+
+are interpreted by the JSON Template Layout compiler, and replaced with the
referenced event or stack trace *template resolver* rendering that particular
item.
+
+For instance, given the following event template stored in `MyLayout.json` in
your classpath:
[source,json]
----
{
- "@timestamp": {
+ "instant": { // <1>
"$resolver": "timestamp",
"pattern": {
"format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
"timeZone": "UTC"
}
},
- "ecs.version": "1.2.0",
- "log.level": {
- "$resolver": "level",
- "field": "name"
- },
- "message": {
+ "someConstant": 1, // <2>
+ "message": { // <3>
"$resolver": "message",
"stringified": true
- },
- "process.thread.name": {
- "$resolver": "thread",
- "field": "name"
- },
- "log.logger": {
- "$resolver": "logger",
- "field": "name"
- },
- "labels": {
- "$resolver": "mdc",
- "flatten": true,
- "stringified": true
- },
- "tags": {
- "$resolver": "ndc"
- },
- "error.type": {
- "$resolver": "exception",
- "field": "className"
- },
- "error.message": {
- "$resolver": "exception",
- "field": "message"
- },
- "error.stack_trace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "stackTrace": {
- "stringified": true
- }
}
}
----
+<1> Using xref:#event-template-resolver-timestamp[the `timestamp` event
template resolver] to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using xref:#event-template-resolver-message[the `message` event template
resolver] to populate the `message` field
-in combination with the below `log4j2.xml` configuration:
+in combination with the below layout configuration:
+[tabs]
+====
+XML::
++
+.Snippet from an example
{antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json"/>
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
----
-or with the below `log4j2.properties` configuration:
+JSON::
++
+.Snippet from an example
{antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
-[source,properties]
+YAML::
++
+.Snippet from an example
{antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
----
-appender.console.layout.type = JsonTemplateLayout
-appender.console.layout.eventTemplateUri = classpath:EcsLayout.json
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
----
-`JsonTemplateLayout` generates JSON as follows:
+Properties::
++
+.Snippet from an example
{antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+JSON Template Layout generates JSON as follows:
[source,json]
----
-{
- "@timestamp": "2017-05-25T19:56:23.370Z",
- "ecs.version": "1.2.0",
- "log.level": "ERROR",
- "message": "Hello, error!",
- "process.thread.name": "main",
- "log.logger": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
- "error.type": "java.lang.RuntimeException",
- "error.message": "test",
- "error.stack_trace": "java.lang.RuntimeException: test\n\tat
org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
-}
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello,
error!"} //<1>
----
+<1> JSON pretty-printing is not supported for performance reasons.
+
+Good news is *JSON Template Layout is perfectly production-ready without any
configuration!*
+The event template defaults to `EcsLayout.json`, bundled in the classpath,
modelling https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the
Elastic Common Schema (ECS) specification].
+JSON Template Layout bundles several more xref:#event-templates[predefined
event templates] modeling popular JSON-based log formats.
-[#layout-config]
-== Layout Configuration
+[#config]
+== Configuration
-`JsonTemplateLayout` is configured with the following parameters:
+This section explains how to configure JSON Template Layout plugin element in
a Log4j configuration file.
-.`JsonTemplateLayout` parameters
-[cols="1m,1m,4"]
+[TIP]
+====
+Are you trying to implement your own event (or stack trace) template and
looking for help on available resolvers?
+Please refer to xref:#template-config[] instead.
+====
+
+[#plugin-attrs]
+=== Plugin attributes
+
+JSON Template Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
|===
-| Parameter Name
-| Type
-| Description
-
-| charset
-| Charset
-| `Charset` used for `String` encoding
-
-| [[locationInfoEnabled]]locationInfoEnabled
-| boolean
-| toggles access to the `LogEvent` source; file name, line number, etc.
- (defaults to `false` set by `log4j.layout.jsonTemplate.locationInfoEnabled`
- property)
-
-| stackTraceEnabled
-| boolean
-| toggles access to the stack traces (defaults to `true` set by
- `log4j.layout.jsonTemplate.stackTraceEnabled` property)
-
-| eventTemplate
-| String
-| inline JSON template for rendering ``LogEvent``s (has priority over
- `eventTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplate` property)
-
-| eventTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``LogEvent``s (defaults to
- `classpath:EcsLayout.json` set by
`log4j.layout.jsonTemplate.eventTemplateUri`
- property)
-
-| eventTemplateRootObjectKey
-| String
-| if present, the event template is put into a JSON object composed of a single
- member with the provided key (defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplateRootObjectKey`
- property)
-
-| eventTemplateAdditionalField
-| EventTemplateAdditionalField[]
-| additional key-value pairs appended to the root of the event template
-
-| stackTraceElementTemplate
-| String
-| inline JSON template for rendering ``StackTraceElement``s (has priority over
- `stackTraceElementTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplate` property)
-
-| stackTraceElementTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``StackTraceElement``s
- (defaults to `classpath:StackTraceElementLayout.json` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` property)
-
-| eventDelimiter
-| String
-| delimiter used for separating rendered ``LogEvent``s (defaults to
- `System.lineSeparator()` set by `log4j.layout.jsonTemplate.eventDelimiter`
- property)
-
-| nullEventDelimiterEnabled
-| boolean
-| append `\0` (`null`) character to the end of every `eventDelimiter`
- separating rendered ``LogEvent``s (defaults to `false` set by
- `log4j.layout.jsonTemplate.nullEventDelimiterEnabled` property)
-
-| [[maxStringLength]] maxStringLength
-| int
-| truncate string values longer than the specified limit (defaults to 16384 set
- by `log4j.layout.jsonTemplate.maxStringLength` property)
-
-| truncatedStringSuffix
-| String
-| suffix to append to strings truncated due to exceeding `maxStringLength`
- (defaults to `…` set by `log4j.layout.jsonTemplate.truncatedStringSuffix`
- property)
-
-| recyclerFactory
-| RecyclerFactory
-| recycling strategy that can either be `dummy`, `threadLocal`, or `queue`
- (set by `log4j.layout.jsonTemplate.recyclerFactory` property)
+|Type |`Charset`
+|Default value |`UTF-8`
+|Configuration property |`log4j.layout.jsonTemplate.charset`
|===
-[#additional-event-template-fields]
-=== Additional event template fields
+`Charset` used for encoding the produced JSON into bytes
-Additional event template fields are a convenient short-cut to add custom
fields
-to a template or override the existing ones. Following configuration overrides
-the `host` field of the `GelfLayout.json` template and adds two new custom
-fields:
+[#plugin-attr-locationInfoEnabled]
+==== [[locationInfoEnabled]]`locationInfoEnabled`
-.XML configuration with additional fields
-[source,xml]
-----
-<JsonTemplateLayout eventTemplateUri="classpath:GelfLayout.json">
- <EventTemplateAdditionalField key="host" value="www.apache.org"/>
- <EventTemplateAdditionalField key="_serviceName" value="auth-service"/>
- <EventTemplateAdditionalField key="_containerId" value="6ede3f0ca7d9"/>
-</JsonTemplateLayout>
-----
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|Configuration property |`log4j.layout.jsonTemplate.locationInfoEnabled`
+|===
-The default `format` for the added new fields are `String`.
-One can also provide JSON-formatted additional fields:
+Toggles access to the `LogEvent` source; file name, line number, etc.
Review Comment:
Fixed in c5f012682d393ddb372a8b3cb0d2d184440a30f0.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@logging.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
