To configure Log4j 2 with JSON, create a log4j2.json file whose objects and arrays describe Log4j plugins, then add JsonTemplateLayout to an appender when you want log events written as structured JSON. For new JSON logging, use JsonTemplateLayout; Apache marks the older JsonLayout deprecated.
How JSON configuration maps to Log4j 2
A Log4j JSON configuration is a tree of plugin components. The top-level configuration object contains components such as appenders and loggers. Within a plugin, scalar values become attributes, while nested objects and arrays become child components. A type property can specify a plugin explicitly; otherwise, the object or array key identifies the plugin. Use arrays when a configuration needs multiple plugins of the same type.
The configuration file is distinct from the JSON log event template: log4j2.json tells Log4j how to configure appenders and loggers, while an event template controls the fields written for each event.
Set up a JSON console appender
Add the template-layout module as a runtime dependency. For Gradle, use:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesruntimeOnly 'org.apache.logging.log4j:log4j-layout-template-json'Then create log4j2.json with a console appender and a root logger that refers to it:
{
"configuration": {
"status": "WARN",
"appenders": {
"Console": {
"name": "Console",
"JsonTemplateLayout": {
"eventTemplateUri": "classpath:EcsLayout.json"
}
}
},
"loggers": {
"Root": {
"level": "INFO",
"appender-ref": { "ref": "Console" }
}
}
}
}This uses the bundled EcsLayout.json event template, which models Elastic Common Schema (ECS). The Console appender sends the output to the console; the root logger sets the logging threshold and references that appender.
Rank #2
Choose the event template
Use the bundled ECS template when its field schema suits the system that will ingest your logs. If your downstream tools require a different schema or field set, provide a custom template file through eventTemplateUri, or put the JSON directly in the configuration with eventTemplate. Before choosing, compare the required schema, field selection, timestamp and exception formats, and the maintenance cost of keeping a custom template aligned with your logging needs.
A template is a JSON document. Objects containing $resolver identify the event data to render. For example:
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match{
"timestamp": { "$resolver": "timestamp" },
"message": { "$resolver": "message", "stringified": true },
"level": { "$resolver": "level" },
"logger": { "$resolver": "logger" }
}Resolvers are available for event data including timestamps, messages, levels, logger names, markers, threads, maps, patterns, and exception data. Select the fields and representation your log consumers expect; the template determines the output shape.
JsonTemplateLayout or JsonLayout?
| Layout | Status and use | Customization | Dependency |
|---|---|---|---|
JsonTemplateLayout |
Apache’s documented successor for structured JSON logging; added in Log4j 2.14.0. | Uses event templates and resolvers to control fields and their representation. | Requires the log4j-layout-template-json runtime module. |
JsonLayout |
Deprecated by Apache; avoid choosing it for a new configuration. | Does not provide the template-based resolver approach described here. | Not stated in the cited layout guidance. |
Apache describes JsonTemplateLayout as customizable, efficient, and garbage-free. The cited documentation does not provide a numeric performance benchmark, so those terms should not be read as a specific measured improvement.
Rank #4
Use environment values and lookups carefully
Log4j supports lookups such as ${java:version} and ${env:NAME:-default}. Substitution depends on context: configuration-time substitution is different from event-time substitution, and doubled dollar signs ($$) can prevent expansion where necessary.
In an external event-template file, substitutions apply to string literals; a lookup string inside a resolver configuration object is not substituted in the documented example. Inline templates are substituted by the configuration mechanism when read. Treat environment variables and system properties as untrusted configuration input: an injected value that is not sanitized can produce invalid JSON or alter the intended event schema.
Quick Recap
Best Value
Check the configuration and output
- Confirm the application includes
log4j-layout-template-jsonat runtime. - Check that the appender’s
JsonTemplateLayoutpoints to the intended template, and that the logger references the appender by its configured name. - Validate the rendered event JSON against the schema expected by the log consumer, especially after adding substitutions or changing fields.
- For a custom template, verify timestamp and exception representations as well as ordinary message and level fields.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
