You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2012/01/25 00:26:24 UTC
svn commit: r803220 -
/websites/staging/jena/trunk/content/jena/documentation/query/logging.html
Author: buildbot
Date: Tue Jan 24 23:26:24 2012
New Revision: 803220
Log:
Staging update by buildbot for jena
Modified:
websites/staging/jena/trunk/content/jena/documentation/query/logging.html
Modified: websites/staging/jena/trunk/content/jena/documentation/query/logging.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/query/logging.html (original)
+++ websites/staging/jena/trunk/content/jena/documentation/query/logging.html Tue Jan 24 23:26:24 2012
@@ -166,14 +166,138 @@ logging set to an application at INFO wi
normal operation. Output below INFO can be very verbose and is
intended mainly to help debug ARQ. WARN and FATAL messages are only
used when something is wrong.</p>
-<p>The root of all the loggers is "com.hp.hpl.jena".
-"com.hp.hpl.jena.query" is the application API.Â
-"com.hp.hpl.jena.sparql" is the implementation and extensions
+<p>The root of all the loggers is <code>com.hp.hpl.jena</code>.
+<code>com.hp.hpl.jena.query</code> is the application API.Â
+<code>com.hp.hpl.jena.sparql</code> is the implementation and extensions
points.</p>
<p>If using in Tomcat, or other system that provides complex class
loading arrangements, be careful about loading from jars in both
the web application and the system directories as this can cause
separate logging systems to be created (this may not matter).</p>
+<p>The ARQ and RIOT command line utilities look for a file
+"log4j.properties" in the current directory to control logging during
+command execution.</p>
+<table>
+<thead>
+<tr>
+<th>Logger Names</th>
+<th>Name</th>
+<th>Constant</th>
+<th>Logger</th>
+<th>Use</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>com.hp.hpl.jena.arq.info</code></td>
+<td><code>ARQ.logInfoName</code></td>
+<td><code>ARQ.getLoggerInfo()</code></td>
+<td>General information</td>
+<td />
+</tr>
+<tr>
+<td><code>com.hp.hpl.jena.arq.exec</code></td>
+<td><code>ARQ.logExecName</code></td>
+<td><code>ARQ.getLoggerExec()</code></td>
+<td>Execution information</td>
+<td />
+</tr>
+</tbody>
+</table>
+<p>There is some code to cover simple situations. See the <a href="http://logging.apache.org/log4j/1.2/manual.html">log4j
+documentation</a>
+for full details of log4j.</p>
+<p>The reading of <code>log4j.properties</code> from the current directory is achieved
+by a call to <code>org.openjena.atlas.logging.Log.setlog4j()</code>.</p>
+<p>Example log4j.properties file:</p>
+<div class="codehilite"><pre><span class="n">log4j</span><span class="o">.</span><span class="n">rootLogger</span><span class="o">=</span><span class="n">INFO</span><span class="p">,</span> <span class="n">stdlog</span>
+
+<span class="n">log4j</span><span class="o">.</span><span class="n">appender</span><span class="o">.</span><span class="n">stdlog</span><span class="o">=</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">log4j</span><span class="o">.</span><span class="n">ConsoleAppender</span>
+<span class="c1">## log4j.appender.stdlog.target=System.err</span>
+<span class="n">log4j</span><span class="o">.</span><span class="n">appender</span><span class="o">.</span><span class="n">stdlog</span><span class="o">.</span><span class="n">layout</span><span class="o">=</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">log4j</span><span class="o">.</span><span class="n">PatternLayout</span>
+<span class="n">log4j</span><span class="o">.</span><span class="n">appender</span><span class="o">.</span><span class="n">stdlog</span><span class="o">.</span><span class="n">layout</span><span class="o">.</span><span class="n">ConversionPattern</span><span class="o">=</span><span class="nv">%d</span><span class="p">{</span><span class="n">HH:mm:ss</span><span class="p">}</span><span class="err">Â </span><span class="nv">%</span><span class="err">-</span><span class="nv">5p</span><span class="err">Â </span><span class="nv">%</span><span class="err">-</span><span class="nv">25c</span><span class="p">{</span><span class="mi">1</span><span class="p">}</span><span class="err">Â </span><span class="o">::</span><span class="err">Â </span><span class="nv">%m%n</span>
+
+<span class="c1"># Execution logging</span>
+<span class="n">log4j</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">com</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">hpl</span><span class="o">.</span><span class="n">jena</span><span class="o">.</span><span class="n">arq</span><span class="o">.</span><span class="n">info</span><span class="o">=</span><span class="n">INFO</span>
+<span class="n">log4j</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">com</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">hpl</span><span class="o">.</span><span class="n">jena</span><span class="o">.</span><span class="n">arq</span><span class="o">.</span><span class="nb">exec</span><span class="o">=</span><span class="n">INFO</span>
+
+<span class="c1"># Other</span>
+<span class="n">log4j</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">com</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">hpl</span><span class="o">.</span><span class="n">jena</span><span class="o">=</span><span class="n">WARN</span>
+<span class="n">log4j</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">org</span><span class="o">.</span><span class="n">openjena</span><span class="o">=</span><span class="n">WARN</span>
+</pre></div>
+
+
+<p><a href="http://joseki.org/" title="http://joseki.org/">Joseki</a> server output can
+include <a href="http://openjena.org/wiki/ARQ/Explain" title="ARQ/Explain">ARQ execution logging</a>.</p>
+<p>Note: ARQ performs some direct control of logging in the test suite and
+depends on log4j to compile.</p>
+<h2 id="execution_logging">Execution Logging</h2>
+<p>ARQ can log query and update execution details globally or for an
+individual operations. This adds another level of control on top of the
+logger level controls.</p>
+<p>Explanatory messages are controlled by the <code>Explain.InfoLevel</code> level in
+the execution context.</p>
+<p>The logger used is called <code>com.hp.hpl.jena.arq.exec</code>. Message are sent
+at level "info". So for log4j, the following can be set in the
+log4j.properties file:</p>
+<div class="codehilite"><pre><span class="n">log4j</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">com</span><span class="o">.</span><span class="n">hp</span><span class="o">.</span><span class="n">hpl</span><span class="o">.</span><span class="n">jena</span><span class="o">.</span><span class="n">arq</span><span class="o">.</span><span class="nb">exec</span><span class="o">=</span><span class="n">INFO</span>
+</pre></div>
+
+
+<p>The context setting is for key (Java constant) <code>ARQ.symLogExec</code>. To set
+globally:</p>
+<div class="codehilite"><pre><span class="n">ARQ</span><span class="o">.</span><span class="n">setExecutionLogging</span><span class="p">(</span><span class="n">Explain</span><span class="o">.</span><span class="n">InfoLevel</span><span class="o">.</span><span class="n">ALL</span><span class="p">)</span><span class="err">Â </span><span class="p">;</span>
+</pre></div>
+
+
+<p>and it may also be set on an individual query execution using its local
+context.</p>
+<div class="codehilite"><pre> <span class="n">QueryExecutiuon</span> <span class="n">qExec</span> <span class="o">=</span> <span class="n">QueryExecutionFactory</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="o">...</span><span class="p">)</span><span class="err">Â </span><span class="p">;</span>
+ <span class="n">qExec</span><span class="o">.</span><span class="n">getContext</span><span class="p">()</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">ARQ</span><span class="o">.</span><span class="n">symLogExec</span><span class="p">,</span> <span class="n">Explain</span><span class="o">.</span><span class="n">InfoLevel</span><span class="o">.</span><span class="n">ALL</span><span class="p">)</span><span class="err">Â </span><span class="p">;</span>
+</pre></div>
+
+
+<p>On the command line:</p>
+<div class="codehilite"><pre> <span class="n">arq</span><span class="o">.</span><span class="n">query</span> <span class="o">--</span><span class="n">explain</span> <span class="o">--</span><span class="n">data</span> <span class="n">data</span> <span class="n">file</span> <span class="o">--</span><span class="n">query</span><span class="o">=</span><span class="n">queryfile</span>
+</pre></div>
+
+
+<p>The command <code>tdbquery</code> takes the same <code>--explain</code> argument.</p>
+<p><strong>Information levels</strong></p>
+<table>
+<thead>
+<tr>
+<th>Level</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>INFO</td>
+<td>Log each query</td>
+</tr>
+<tr>
+<td>FINE</td>
+<td>Log each query and its algebra form after optimization</td>
+</tr>
+<tr>
+<td>ALL</td>
+<td>Log query, algebra and every dataset access (can be expensive)</td>
+</tr>
+<tr>
+<td>NONE</td>
+<td>No information logged</td>
+</tr>
+</tbody>
+</table>
+<p>These can be specified as string, to the command line tools, or using
+the constants in <code>Explain.InfoLevel</code>.</p>
+<div class="codehilite"><pre> <span class="n">qExec</span><span class="o">.</span><span class="n">getContext</span><span class="p">()</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">ARQ</span><span class="o">.</span><span class="n">symLogExec</span><span class="p">,</span> <span class="n">Explain</span><span class="o">.</span><span class="n">InfoLevel</span><span class="o">.</span><span class="n">FINE</span><span class="p">)</span><span class="err">Â </span><span class="p">;</span>
+
+ <span class="n">arq</span><span class="o">.</span><span class="n">query</span> <span class="o">--</span><span class="n">set:logExec</span><span class="o">=</span><span class="n">FINE</span> <span class="o">--</span><span class="n">data</span> <span class="n">data</span> <span class="n">file</span> <span class="o">--</span><span class="n">query</span><span class="o">=</span><span class="n">queryfile</span>
+</pre></div>
+
+
<p><a href="index.html">ARQ documentation index</a></p>
</div>