////
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
////

[IMPORTANT]
=====
*Log messages* are often used interchangeably with *log events*.
While this simplification holds for several cases, it is not technically correct.
A log event, capturing the logging context (level, logger name, instant, etc.) along with the log message, is generated by the logging implementation (e.g., Log4j Core) when a user issues a log using a xref:manual/api.adoc#loggers[logger], e.g., `LOGGER.info("Hello, world!")`.
Hence, *log events are compound objects containing log messages*.

.Click for an introduction to log event fields
[%collapsible]
====
Log events contain fields that can be classified into three categories:

. Some fields are provided explicitly, in a link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] method call.
The most important are the log level and the log message, which is a description of what happened, and it is addressed to humans.

. Some fields are contextual (e.g., xref:manual/thread-context.adoc[]) and are either provided explicitly by developers of other parts of the application, or is injected by Java instrumentation.

. The last category of fields is those that are computed automatically by the logging implementation employed.

For clarity's sake let us look at a log event formatted as JSON:

[source,json]
----
include::example$manual/messages/log-event.json[]
----

<1> Explicitly supplied fields:
`log.level`:: The xref:manual/customloglevels.adoc[level] of the event, either explicitly provided as an argument to the logger call, or implied by the name of the logger method
`message`:: The **log message** that describes what happened
`error.*`:: An _optional_ `Throwable` explicitly passed as an argument to the logger call
`marker`:: An _optional_ xref:manual/markers.adoc[marker] explicitly passed as an argument to the logger call
`log.logger`:: The xref:manual/api.adoc#logger-names[logger name] provided explicitly to `LogManager.getLogger()` or inferred by Log4j API

<2> Contextual fields:
`tags`:: The xref:manual/thread-context.adoc[] stack
`labels`:: The xref:manual/thread-context.adoc[] map

<3> Logging backend specific fields.
In case you are using Log4j Core, the following fields can be automatically generated:
`@timestamp`:: The instant of the logger call
`log.origin.*`:: The xref:manual/layouts.adoc#LocationInformation[location] of the logger call in the source code
`process.thread.*`:: The name of the Java thread, where the logger is called
====
=====
