This is an automated email from the ASF dual-hosted git repository.
chesnay pushed a commit to branch release-1.12
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/release-1.12 by this push:
new 6840153 [FLINK-20353][docs][logging] Update logging documentation
6840153 is described below
commit 6840153417fbb576977291460bcf441c5d4b1401
Author: Chesnay Schepler <[email protected]>
AuthorDate: Tue Dec 8 17:05:17 2020 +0100
[FLINK-20353][docs][logging] Update logging documentation
---
docs/deployment/advanced/logging.md | 94 ++++++++++++++++++++-----------------
1 file changed, 52 insertions(+), 42 deletions(-)
diff --git a/docs/deployment/advanced/logging.md
b/docs/deployment/advanced/logging.md
index f12ba87..50c5ebd 100644
--- a/docs/deployment/advanced/logging.md
+++ b/docs/deployment/advanced/logging.md
@@ -23,30 +23,42 @@ specific language governing permissions and limitations
under the License.
-->
-The logging in Flink is implemented using the slf4j logging interface. As
underlying logging framework, log4j2 is used. We also provide logback
configuration files and pass them to the JVM's as properties. Users willing to
use logback instead of log4j2 can just exclude log4j2 (or delete it from the
lib/ folder).
+All Flink processes create a log text file that contains messages for various
events happening in that process.
+These logs provide deep insights into the inner workings of Flink, and can be
used to detect problems (in the form of WARN/ERROR messages) and can help in
debugging them.
+
+The log files can be accessed via the Job-/TaskManager pages of the WebUI. The
used [Resource Provider]({% link deployment/resource-providers/index.md %})
(e.g., YARN) may provide additional means of accessing them.
+
+The logging in Flink uses the [SLF4J](http://www.slf4j.org/) logging interface.
+This allows you to use any logging framework that supports SLF4J, without
having to modify the Flink source code.
+
+By default, [Log4j 2](https://logging.apache.org/log4j/2.x/index.html) is used
as the underlying logging framework.
* This will be replaced by the TOC
{:toc}
-## Configuring Log4j2
+## Configuring Log4j 2
+
+Log4j 2 is controlled using property files.
-Log4j2 is controlled using property files. In Flink's case, the file is
usually called `log4j.properties`. We pass the filename and location of this
file using the `-Dlog4j.configurationFile=` parameter to the JVM.
+The Flink distribution ships with the following log4j properties files in the
`conf` directory, which are used automatically if Log4j 2 is enabled:
-Flink ships with the following default properties files:
+- `log4j-cli.properties`: used by the command line interface (e.g., `flink
run`)
+- `log4j-session.properties`: used by the command line interface when starting
a Kubernetes/Yarn session cluster (i.e.,
`kubernetes-session.sh`/`yarn-session.sh`)
+- `log4j-console.properties`: used for Job-/TaskManagers if they are run in
the foreground (e.g., Kubernetes)
+- `log4j.properties`: used for Job-/TaskManagers by default
-- `log4j-cli.properties`: Used by the Flink command line client (e.g. `flink
run`) (not code executed on the cluster)
-- `log4j-session.properties`: Used by the Flink command line client when
starting a YARN or Kubernetes session (`yarn-session.sh`,
`kubernetes-session.sh`)
-- `log4j.properties`: JobManager/Taskmanager logs (both standalone and YARN)
+Log4j periodically scans this file for changes and adjusts the logging
behavior if necessary.
+By default this check happens every 30 seconds and is controlled by the
`monitorInterval` setting in the Log4j properties files.
-### Compatibility with Log4j1
+### Compatibility with Log4j 1
Flink ships with the [Log4j API
bridge](https://logging.apache.org/log4j/log4j-2.2/log4j-1.2-api/index.html),
allowing existing applications that work against Log4j1 classes to continue
working.
-If you have custom Log4j1 properties files or code that relies on Log4j1,
please check out the official Log4j
[compatibility](https://logging.apache.org/log4j/2.x/manual/compatibility.html)
and [migration](https://logging.apache.org/log4j/2.x/manual/migration.html)
guides.
+If you have custom Log4j 1 properties files or code that relies on Log4j 1,
please check out the official Log4j
[compatibility](https://logging.apache.org/log4j/2.x/manual/compatibility.html)
and [migration](https://logging.apache.org/log4j/2.x/manual/migration.html)
guides.
## Configuring Log4j1
-To use Flink with Log4j1 you must ensure that:
+To use Flink with [Log4j 1](https://logging.apache.org/log4j/1.2/) you must
ensure that:
- `org.apache.logging.log4j:log4j-core`,
`org.apache.logging.log4j:log4j-slf4j-impl` and
`org.apache.logging.log4j:log4j-1.2-api` are not on the classpath,
- `log4j:log4j`, `org.slf4j:slf4j-log4j12`,
`org.apache.logging.log4j:log4j-to-slf4j` and
`org.apache.logging.log4j:log4j-api` are on the classpath.
@@ -59,49 +71,47 @@ For Flink distributions this means you have to
## Configuring logback
-For users and developers alike it is important to control the logging
framework.
-The configuration of the logging framework is exclusively done by
configuration files.
-The configuration file either has to be specified by setting the environment
property `-Dlogback.configurationFile=<file>` or by putting `logback.xml` in
the classpath.
-The `conf` directory contains a `logback.xml` file which can be modified and
is used if Flink is started outside of an IDE and with the provided starting
scripts.
-The provided `logback.xml` has the following form:
-
-{% highlight xml %}
-<configuration>
- <appender name="file" class="ch.qos.logback.core.FileAppender">
- <file>${log.file}</file>
- <append>false</append>
- <encoder>
- <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{60}
%X{sourceThread} - %msg%n</pattern>
- </encoder>
- </appender>
-
- <root level="INFO">
- <appender-ref ref="file"/>
- </root>
-</configuration>
-{% endhighlight %}
+To use Flink with [logback](https://logback.qos.ch/) you must ensure that:
+- `org.apache.logging.log4j:log4j-slf4j-impl` is not on the classpath,
+- `ch.qos.logback:logback-core` and `ch.qos.logback:logback-classic` are on
the classpath.
-In order to control the logging level of
`org.apache.flink.runtime.jobgraph.JobGraph`, for example, one would have to
add the following line to the configuration file.
+In the IDE this means you have to replace such dependencies defined in your
pom, and possibly add exclusions on dependencies that transitively depend on
them.
-{% highlight xml %}
-<logger name="org.apache.flink.runtime.jobgraph.JobGraph" level="DEBUG"/>
-{% endhighlight %}
+For Flink distributions this means you have to
+- remove the `log4j-slf4j-impl` jar from the `lib` directory,
+- add the `logback-core`, and `logback-classic` jars to the `lib` directory.
+
+The Flink distribution ships with the following logback configuration files in
the `conf` directory, which are used automatically if logback is enabled:
+- `logback-session.properties`: used by the command line interface when
starting a Kubernetes/Yarn session cluster (i.e.,
`kubernetes-session.sh`/`yarn-session.sh`)
+- `logback-console.properties`: used for Job-/TaskManagers if they are run in
the foreground (e.g., Kubernetes)
+- `logback.xml`: used for command line interface and Job-/TaskManagers by
default
-For further information on configuring logback see [LOGback's
manual](http://logback.qos.ch/manual/configuration.html).
+<div class="alert alert-info" markdown="span">
+ <strong>Note:</strong> Logback 1.3+ requires SLF4J 2, which is currently not
supported.
+</div>
## Best practices for developers
-The loggers using slf4j are created by calling
+You can create an SLF4J logger by calling
`org.slf4j.LoggerFactory#LoggerFactory.getLogger` with the `Class` of your
class as an argument.
+
+We highly recommend storing this logger in a `private static final` field.
{% highlight java %}
-import org.slf4j.LoggerFactory
-import org.slf4j.Logger
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
-Logger LOG = LoggerFactory.getLogger(Foobar.class)
+public class Foobar {
+ private static final Logger LOG = LoggerFactory.getLogger(Foobar.class);
+
+ public static void main(String[] args) {
+ LOG.info("Hello world!");
+ }
+}
{% endhighlight %}
-In order to benefit most from slf4j, it is recommended to use its placeholder
mechanism.
-Using placeholders allows to avoid unnecessary string constructions in case
that the logging level is set so high that the message would not be logged.
+In order to benefit most from SLF4J, it is recommended to use its placeholder
mechanism.
+Using placeholders allows avoiding unnecessary string constructions in case
that the logging level is set so high that the message would not be logged.
+
The syntax of placeholders is the following:
{% highlight java %}
