docs/0.9/internals/logging.html - flink-web - Git at Google

 <!--
 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.
 -->
 <!DOCTYPE html>

 <html lang="en">
   <head>
     <meta charset="utf-8">
     <meta http-equiv="X-UA-Compatible" content="IE=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->

     <title>Apache Flink 0.9.0 Documentation: How to use logging</title>

     <link rel="shortcut icon" href="http://flink.apache.org/docs/0.9/page/favicon.ico" type="image/x-icon">
     <link rel="icon" href="http://flink.apache.org/docs/0.9/page/favicon.ico" type="image/x-icon">

     <!-- Bootstrap -->
     <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css">
     <link rel="stylesheet" href="http://flink.apache.org/docs/0.9/page/css/flink.css">
     <link rel="stylesheet" href="http://flink.apache.org/docs/0.9/page/css/syntax.css">
     <link rel="stylesheet" href="http://flink.apache.org/docs/0.9/page/css/codetabs.css">

     <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
     <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
     <!--[if lt IE 9]>
       <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
       <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
     <![endif]-->
   </head>
   <body>


     <!-- Top navbar. -->
     <nav class="navbar navbar-default navbar-fixed-top">
       <div class="container">
         <!-- The logo. -->
         <div class="navbar-header">
           <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
           </button>
           <div class="navbar-logo">
             <a href="http://flink.apache.org"><img alt="Apache Flink" src="http://flink.apache.org/docs/0.9/page/img/navbar-brand-logo.jpg"></a>
           </div>
         </div><!-- /.navbar-header -->

         <!-- The navigation links. -->
         <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
           <ul class="nav navbar-nav">
             <li><a href="http://flink.apache.org/docs/0.9/index.html">Overview<span class="hidden-sm hidden-xs"> 0.9.0</span></a></li>

             <!-- Setup -->
             <li class="dropdown">
               <a href="http://flink.apache.org/docs/0.9/setup" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Setup <span class="caret"></span></a>
               <ul class="dropdown-menu" role="menu">
                 <li><a href="http://flink.apache.org/docs/0.9/setup/building.html">Get Flink 0.9-SNAPSHOT</a></li>

                 <li class="divider"></li>
                 <li role="presentation" class="dropdown-header"><strong>Deployment</strong></li>
                 <li><a href="http://flink.apache.org/docs/0.9/setup/local_setup.html" class="active">Local</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/setup/cluster_setup.html">Cluster (Standalone)</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/setup/yarn_setup.html">YARN</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/setup/gce_setup.html">GCloud</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/setup/flink_on_tez.html">Flink on Tez <span class="badge">Beta</span></a></li>

                 <li class="divider"></li>
                 <li><a href="http://flink.apache.org/docs/0.9/setup/config.html">Configuration</a></li>
               </ul>
             </li>

             <!-- Programming Guides -->
             <li class="dropdown">
               <a href="http://flink.apache.org/docs/0.9/apis" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Programming Guides <span class="caret"></span></a>
               <ul class="dropdown-menu" role="menu">
                 <li><a href="http://flink.apache.org/docs/0.9/apis/programming_guide.html"><strong>Batch: DataSet API</strong></a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/streaming_guide.html"><strong>Streaming: DataStream API</strong> <span class="badge">Beta</span></a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/python.html">Python API <span class="badge">Beta</span></a></li>

                 <li class="divider"></li>
                 <li><a href="scala_shell.html">Interactive Scala Shell</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/dataset_transformations.html">Dataset Transformations</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/best_practices.html">Best Practices</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/example_connectors.html">Connectors</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/examples.html">Examples</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/local_execution.html">Local Execution</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/cluster_execution.html">Cluster Execution</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/cli.html">Command Line Interface</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/web_client.html">Web Client</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/iterations.html">Iterations</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/java8.html">Java 8</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/apis/hadoop_compatibility.html">Hadoop Compatability <span class="badge">Beta</span></a></li>
               </ul>
             </li>

             <!-- Libraries -->
             <li class="dropdown">
               <a href="http://flink.apache.org/docs/0.9/libs" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Libraries <span class="caret"></span></a>
                 <ul class="dropdown-menu" role="menu">
                   <li><a href="http://flink.apache.org/docs/0.9/libs/spargel_guide.html">Graphs: Spargel</a></li>
                   <li><a href="http://flink.apache.org/docs/0.9/libs/gelly_guide.html">Graphs: Gelly <span class="badge">Beta</span></a></li>
                   <li><a href="http://flink.apache.org/docs/0.9/libs/ml/">Machine Learning <span class="badge">Beta</span></a></li>
                   <li><a href="http://flink.apache.org/docs/0.9/libs/table.html">Relational: Table <span class="badge">Beta</span></a></li>
               </ul>
             </li>

             <!-- Internals -->
             <li class="dropdown">
               <a href="http://flink.apache.org/docs/0.9/internals" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Internals <span class="caret"></span></a>
               <ul class="dropdown-menu" role="menu">
                 <li role="presentation" class="dropdown-header"><strong>Contribute</strong></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/how_to_contribute.html">How to Contribute</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/coding_guidelines.html">Coding Guidelines</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/ide_setup.html">IDE Setup</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/logging.html">Logging</a></li>
                 <li class="divider"></li>
                 <li role="presentation" class="dropdown-header"><strong>Internals</strong></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/general_arch.html">Architecture &amp; Process Model</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/types_serialization.html">Type Extraction &amp; Serialization</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/job_scheduling.html">Jobs &amp; Scheduling</a></li>
                 <li><a href="http://flink.apache.org/docs/0.9/internals/add_operator.html">How-To: Add an Operator</a></li>
               </ul>
             </li>
           </ul>
           <form class="navbar-form navbar-right hidden-sm hidden-md" role="search" action="http://flink.apache.org/docs/0.9/search-results.html">
             <div class="form-group">
               <input type="text" class="form-control" name="q" placeholder="Search all pages">
             </div>
             <button type="submit" class="btn btn-default">Search</button>
           </form>
         </div><!-- /.navbar-collapse -->
       </div><!-- /.container -->
     </nav>


     <!-- Main content. -->
     <div class="container">


 <div class="row">
   <div class="col-sm-10 col-sm-offset-1">
     <h1>How to use logging</h1>


 <p>The logging in Flink is implemented using the slf4j logging interface. As underlying logging framework, log4j is used. We also provide logback configuration files and pass them to the JVM’s as properties. Users willing to use logback instead of log4j can just exclude log4j (or delete it from the lib/ folder).</p>

 <ul id="markdown-toc">
   <li><a href="#configuring-log4j" id="markdown-toc-configuring-log4j">Configuring Log4j</a></li>
   <li><a href="#configuring-logback" id="markdown-toc-configuring-logback">Configuring logback</a></li>
   <li><a href="#best-practices-for-developers" id="markdown-toc-best-practices-for-developers">Best practices for developers</a></li>
 </ul>

 <h2 id="configuring-log4j">Configuring Log4j</h2>

 <p>Log4j is controlled using property files. In Flink’s case, the file is usually called <code>log4j.properties</code>. We pass the filename and location of this file using the <code>-Dlog4j.configuration=</code> parameter to the JVM.</p>

 <h2 id="configuring-logback">Configuring logback</h2>

 <p>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 <code>-Dlogback.configurationFile=&lt;file&gt;</code> or by putting <code>logback.xml</code> in the classpath.
 The <code>conf</code> directory contains a <code>logback.xml</code> file which can be modified and is used if Flink is started outside of an IDE and with the provided starting scripts.
 The provided <code>logback.xml</code> has the following form:</p>

 <div class="highlight"><pre><code class="language-xml"><span class="nt">&lt;configuration&gt;</span>
     <span class="nt">&lt;appender</span> <span class="na">name=</span><span class="s">&quot;file&quot;</span> <span class="na">class=</span><span class="s">&quot;ch.qos.logback.core.FileAppender&quot;</span><span class="nt">&gt;</span>
         <span class="nt">&lt;file&gt;</span>${log.file}<span class="nt">&lt;/file&gt;</span>
         <span class="nt">&lt;append&gt;</span>false<span class="nt">&lt;/append&gt;</span>
         <span class="nt">&lt;encoder&gt;</span>
             <span class="nt">&lt;pattern&gt;</span>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{60} %X{sourceThread} - %msg%n<span class="nt">&lt;/pattern&gt;</span>
         <span class="nt">&lt;/encoder&gt;</span>
     <span class="nt">&lt;/appender&gt;</span>

     <span class="nt">&lt;root</span> <span class="na">level=</span><span class="s">&quot;INFO&quot;</span><span class="nt">&gt;</span>
         <span class="nt">&lt;appender-ref</span> <span class="na">ref=</span><span class="s">&quot;file&quot;</span><span class="nt">/&gt;</span>
     <span class="nt">&lt;/root&gt;</span>
 <span class="nt">&lt;/configuration&gt;</span></code></pre></div>

 <p>In order to control the logging level of <code>org.apache.flink.runtime.jobgraph.JobGraph</code>, for example, one would have to add the following line to the configuration file.</p>

 <div class="highlight"><pre><code class="language-xml"><span class="nt">&lt;logger</span> <span class="na">name=</span><span class="s">&quot;org.apache.flink.runtime.jobgraph.JobGraph&quot;</span> <span class="na">level=</span><span class="s">&quot;DEBUG&quot;</span><span class="nt">/&gt;</span></code></pre></div>

 <p>For further information on configuring logback see <a href="http://logback.qos.ch/manual/configuration.html">LOGback’s manual</a>.</p>

 <h2 id="best-practices-for-developers">Best practices for developers</h2>

 <p>The loggers using slf4j are created by calling</p>

 <div class="highlight"><pre><code class="language-java"><span class="kn">import</span> <span class="nn">org.slf4j.LoggerFactory</span>
 <span class="kn">import</span> <span class="nn">org.slf4j.Logger</span>

 <span class="n">Logger</span> <span class="n">LOG</span> <span class="o">=</span> <span class="n">LoggerFactory</span><span class="o">.</span><span class="na">getLogger</span><span class="o">(</span><span class="n">Foobar</span><span class="o">.</span><span class="na">class</span><span class="o">)</span></code></pre></div>

 <p>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.
 The syntax of placeholders is the following:</p>

 <div class="highlight"><pre><code class="language-java"><span class="n">LOG</span><span class="o">.</span><span class="na">info</span><span class="o">(</span><span class="s">&quot;This message contains {} placeholders. {}&quot;</span><span class="o">,</span> <span class="mi">2</span><span class="o">,</span> <span class="s">&quot;Yippie&quot;</span><span class="o">);</span></code></pre></div>

 <p>Placeholders can also be used in conjunction with exceptions which shall be logged.</p>

 <div class="highlight"><pre><code class="language-java"><span class="k">catch</span><span class="o">(</span><span class="n">Exception</span> <span class="n">exception</span><span class="o">){</span>
 	<span class="n">LOG</span><span class="o">.</span><span class="na">error</span><span class="o">(</span><span class="s">&quot;An {} occurred.&quot;</span><span class="o">,</span> <span class="s">&quot;error&quot;</span><span class="o">,</span> <span class="n">exception</span><span class="o">);</span>
 <span class="o">}</span></code></pre></div>

 <hr />

 <p><em>This documentation is maintained by the contributors of the individual components.
 We kindly ask anyone that adds and changes components to eventually provide a patch
 or pull request that updates these documents as well.</em></p>


   </div>

   <div class="col-sm-10 col-sm-offset-1">
     <!-- Disqus thread and some vertical offset -->
     <div style="margin-top: 75px; margin-bottom: 50px" id="disqus_thread"></div>
   </div>
 </div>

     </div><!-- /.container -->

     <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
     <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
     <!-- Include all compiled plugins (below), or include individual files as needed -->
     <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
     <script src="http://flink.apache.org/docs/0.9/page/js/codetabs.js"></script>

     <!-- Google Analytics -->
     <script>
       (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
       (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
       m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
       })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

       ga('create', 'UA-52545728-1', 'auto');
       ga('send', 'pageview');
     </script>

     <!-- Disqus -->
     <script type="text/javascript">
     var disqus_shortname = 'stratosphere-eu';
     (function() {
         var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
         dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
         (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
     })();
 </script>
   </body>
 </html>
	<!--
	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.
	-->
	<!DOCTYPE html>

	<html lang="en">
	<head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<!-- The above 3 meta tags must come first in the head; any other head content must come after these tags -->

	<title>Apache Flink 0.9.0 Documentation: How to use logging</title>

	<link rel="shortcut icon" href="http://flink.apache.org/docs/0.9/page/favicon.ico" type="image/x-icon">
	<link rel="icon" href="http://flink.apache.org/docs/0.9/page/favicon.ico" type="image/x-icon">

	<!-- Bootstrap -->
	<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css">
	<link rel="stylesheet" href="http://flink.apache.org/docs/0.9/page/css/flink.css">
	<link rel="stylesheet" href="http://flink.apache.org/docs/0.9/page/css/syntax.css">
	<link rel="stylesheet" href="http://flink.apache.org/docs/0.9/page/css/codetabs.css">

	<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
	<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
	<!--[if lt IE 9]>
	<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
	<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
	<![endif]-->
	</head>
	<body>






	<!-- Top navbar. -->
	<nav class="navbar navbar-default navbar-fixed-top">
	<div class="container">
	<!-- The logo. -->
	<div class="navbar-header">
	<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<div class="navbar-logo">
	<a href="http://flink.apache.org"><img alt="Apache Flink" src="http://flink.apache.org/docs/0.9/page/img/navbar-brand-logo.jpg"></a>
	</div>
	</div><!-- /.navbar-header -->

	<!-- The navigation links. -->
	<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
	<ul class="nav navbar-nav">
	<li><a href="http://flink.apache.org/docs/0.9/index.html">Overview<span class="hidden-sm hidden-xs"> 0.9.0</span></a></li>

	<!-- Setup -->
	<li class="dropdown">
	<a href="http://flink.apache.org/docs/0.9/setup" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Setup <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="http://flink.apache.org/docs/0.9/setup/building.html">Get Flink 0.9-SNAPSHOT</a></li>

	<li class="divider"></li>
	<li role="presentation" class="dropdown-header"><strong>Deployment</strong></li>
	<li><a href="http://flink.apache.org/docs/0.9/setup/local_setup.html" class="active">Local</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/setup/cluster_setup.html">Cluster (Standalone)</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/setup/yarn_setup.html">YARN</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/setup/gce_setup.html">GCloud</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/setup/flink_on_tez.html">Flink on Tez <span class="badge">Beta</span></a></li>

	<li class="divider"></li>
	<li><a href="http://flink.apache.org/docs/0.9/setup/config.html">Configuration</a></li>
	</ul>
	</li>

	<!-- Programming Guides -->
	<li class="dropdown">
	<a href="http://flink.apache.org/docs/0.9/apis" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Programming Guides <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="http://flink.apache.org/docs/0.9/apis/programming_guide.html"><strong>Batch: DataSet API</strong></a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/streaming_guide.html"><strong>Streaming: DataStream API</strong> <span class="badge">Beta</span></a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/python.html">Python API <span class="badge">Beta</span></a></li>

	<li class="divider"></li>
	<li><a href="scala_shell.html">Interactive Scala Shell</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/dataset_transformations.html">Dataset Transformations</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/best_practices.html">Best Practices</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/example_connectors.html">Connectors</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/examples.html">Examples</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/local_execution.html">Local Execution</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/cluster_execution.html">Cluster Execution</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/cli.html">Command Line Interface</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/web_client.html">Web Client</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/iterations.html">Iterations</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/java8.html">Java 8</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/apis/hadoop_compatibility.html">Hadoop Compatability <span class="badge">Beta</span></a></li>
	</ul>
	</li>

	<!-- Libraries -->
	<li class="dropdown">
	<a href="http://flink.apache.org/docs/0.9/libs" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Libraries <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="http://flink.apache.org/docs/0.9/libs/spargel_guide.html">Graphs: Spargel</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/libs/gelly_guide.html">Graphs: Gelly <span class="badge">Beta</span></a></li>
	<li><a href="http://flink.apache.org/docs/0.9/libs/ml/">Machine Learning <span class="badge">Beta</span></a></li>
	<li><a href="http://flink.apache.org/docs/0.9/libs/table.html">Relational: Table <span class="badge">Beta</span></a></li>
	</ul>
	</li>

	<!-- Internals -->
	<li class="dropdown">
	<a href="http://flink.apache.org/docs/0.9/internals" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Internals <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li role="presentation" class="dropdown-header"><strong>Contribute</strong></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/how_to_contribute.html">How to Contribute</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/coding_guidelines.html">Coding Guidelines</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/ide_setup.html">IDE Setup</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/logging.html">Logging</a></li>
	<li class="divider"></li>
	<li role="presentation" class="dropdown-header"><strong>Internals</strong></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/general_arch.html">Architecture & Process Model</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/types_serialization.html">Type Extraction & Serialization</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/job_scheduling.html">Jobs & Scheduling</a></li>
	<li><a href="http://flink.apache.org/docs/0.9/internals/add_operator.html">How-To: Add an Operator</a></li>
	</ul>
	</li>
	</ul>
	<form class="navbar-form navbar-right hidden-sm hidden-md" role="search" action="http://flink.apache.org/docs/0.9/search-results.html">
	<div class="form-group">
	<input type="text" class="form-control" name="q" placeholder="Search all pages">
	</div>
	<button type="submit" class="btn btn-default">Search</button>
	</form>
	</div><!-- /.navbar-collapse -->
	</div><!-- /.container -->
	</nav>




	<!-- Main content. -->
	<div class="container">


	<div class="row">
	<div class="col-sm-10 col-sm-offset-1">
	<h1>How to use logging</h1>



	<p>The logging in Flink is implemented using the slf4j logging interface. As underlying logging framework, log4j is used. We also provide logback configuration files and pass them to the JVM’s as properties. Users willing to use logback instead of log4j can just exclude log4j (or delete it from the lib/ folder).</p>

	<ul id="markdown-toc">
	<li><a href="#configuring-log4j" id="markdown-toc-configuring-log4j">Configuring Log4j</a></li>
	<li><a href="#configuring-logback" id="markdown-toc-configuring-logback">Configuring logback</a></li>
	<li><a href="#best-practices-for-developers" id="markdown-toc-best-practices-for-developers">Best practices for developers</a></li>
	</ul>

	<h2 id="configuring-log4j">Configuring Log4j</h2>

	<p>Log4j is controlled using property files. In Flink’s case, the file is usually called <code>log4j.properties</code>. We pass the filename and location of this file using the <code>-Dlog4j.configuration=</code> parameter to the JVM.</p>

	<h2 id="configuring-logback">Configuring logback</h2>

	<p>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 <code>-Dlogback.configurationFile=<file></code> or by putting <code>logback.xml</code> in the classpath.
	The <code>conf</code> directory contains a <code>logback.xml</code> file which can be modified and is used if Flink is started outside of an IDE and with the provided starting scripts.
	The provided <code>logback.xml</code> has the following form:</p>

	<div class="highlight"><pre><code class="language-xml"><span class="nt"><configuration></span>
	<span class="nt"><appender</span> <span class="na">name=</span><span class="s">"file"</span> <span class="na">class=</span><span class="s">"ch.qos.logback.core.FileAppender"</span><span class="nt">></span>
	<span class="nt"><file></span>${log.file}<span class="nt"></file></span>
	<span class="nt"><append></span>false<span class="nt"></append></span>
	<span class="nt"><encoder></span>
	<span class="nt"><pattern></span>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{60} %X{sourceThread} - %msg%n<span class="nt"></pattern></span>
	<span class="nt"></encoder></span>
	<span class="nt"></appender></span>

	<span class="nt"><root</span> <span class="na">level=</span><span class="s">"INFO"</span><span class="nt">></span>
	<span class="nt"><appender-ref</span> <span class="na">ref=</span><span class="s">"file"</span><span class="nt">/></span>
	<span class="nt"></root></span>
	<span class="nt"></configuration></span></code></pre></div>

	<p>In order to control the logging level of <code>org.apache.flink.runtime.jobgraph.JobGraph</code>, for example, one would have to add the following line to the configuration file.</p>

	<div class="highlight"><pre><code class="language-xml"><span class="nt"><logger</span> <span class="na">name=</span><span class="s">"org.apache.flink.runtime.jobgraph.JobGraph"</span> <span class="na">level=</span><span class="s">"DEBUG"</span><span class="nt">/></span></code></pre></div>

	<p>For further information on configuring logback see <a href="http://logback.qos.ch/manual/configuration.html">LOGback’s manual</a>.</p>

	<h2 id="best-practices-for-developers">Best practices for developers</h2>

	<p>The loggers using slf4j are created by calling</p>

	<div class="highlight"><pre><code class="language-java"><span class="kn">import</span> <span class="nn">org.slf4j.LoggerFactory</span>
	<span class="kn">import</span> <span class="nn">org.slf4j.Logger</span>

	<span class="n">Logger</span> <span class="n">LOG</span> <span class="o">=</span> <span class="n">LoggerFactory</span><span class="o">.</span><span class="na">getLogger</span><span class="o">(</span><span class="n">Foobar</span><span class="o">.</span><span class="na">class</span><span class="o">)</span></code></pre></div>

	<p>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.
	The syntax of placeholders is the following:</p>

	<div class="highlight"><pre><code class="language-java"><span class="n">LOG</span><span class="o">.</span><span class="na">info</span><span class="o">(</span><span class="s">"This message contains {} placeholders. {}"</span><span class="o">,</span> <span class="mi">2</span><span class="o">,</span> <span class="s">"Yippie"</span><span class="o">);</span></code></pre></div>

	<p>Placeholders can also be used in conjunction with exceptions which shall be logged.</p>

	<div class="highlight"><pre><code class="language-java"><span class="k">catch</span><span class="o">(</span><span class="n">Exception</span> <span class="n">exception</span><span class="o">){</span>
	<span class="n">LOG</span><span class="o">.</span><span class="na">error</span><span class="o">(</span><span class="s">"An {} occurred."</span><span class="o">,</span> <span class="s">"error"</span><span class="o">,</span> <span class="n">exception</span><span class="o">);</span>
	<span class="o">}</span></code></pre></div>

	<hr />

	<p><em>This documentation is maintained by the contributors of the individual components.
	We kindly ask anyone that adds and changes components to eventually provide a patch
	or pull request that updates these documents as well.</em></p>


	</div>

	<div class="col-sm-10 col-sm-offset-1">
	<!-- Disqus thread and some vertical offset -->
	<div style="margin-top: 75px; margin-bottom: 50px" id="disqus_thread"></div>
	</div>
	</div>

	</div><!-- /.container -->

	<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
	<!-- Include all compiled plugins (below), or include individual files as needed -->
	<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
	<script src="http://flink.apache.org/docs/0.9/page/js/codetabs.js"></script>

	<!-- Google Analytics -->
	<script>
	(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]\|\|function(){
	(i[r].q=i[r].q\|\|[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
	m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
	})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

	ga('create', 'UA-52545728-1', 'auto');
	ga('send', 'pageview');
	</script>

	<!-- Disqus -->
	<script type="text/javascript">
	var disqus_shortname = 'stratosphere-eu';
	(function() {
	var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
	dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
	(document.getElementsByTagName('head')[0] \|\| document.getElementsByTagName('body')[0]).appendChild(dsq);
	})();
	</script>
	</body>
	</html>