You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rg...@apache.org on 2015/10/13 06:09:43 UTC
[47/50] logging-log4j2 git commit: LOG4J2-1136 Add documentation on
Scripts
LOG4J2-1136 Add documentation on Scripts
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/cda6fb61
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/cda6fb61
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/cda6fb61
Branch: refs/heads/master
Commit: cda6fb61f3429f05ee5bdc1e8607974849b8a8d0
Parents: 6cd06f8
Author: Ralph Goers <rg...@nextiva.com>
Authored: Sun Oct 11 12:30:33 2015 -0700
Committer: Ralph Goers <rg...@nextiva.com>
Committed: Sun Oct 11 12:44:19 2015 -0700
----------------------------------------------------------------------
src/site/site.xml | 2 +-
src/site/xdoc/manual/configuration.xml.vm | 79 +++++++++++++++++++++++---
src/site/xdoc/manual/filters.xml | 37 +++++++++++-
src/site/xdoc/manual/layouts.xml.vm | 55 +++++++++++++++++-
4 files changed, 159 insertions(+), 14 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cda6fb61/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 8c076fa..0618a01 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -72,7 +72,7 @@
<item name="Configuring Appenders" href="/manual/configuration.html#Appenders"/>
<item name="Configuring Filters" href="/manual/configuration.html#Filters"/>
<item name="Property Substitution" href="/manual/configuration.html#PropertySubstitution"/>
- <item name-"Scripts" href="/manual/configuration.html#Scripts"/>
+ <item name="Scripts" href="/manual/configuration.html#Scripts"/>
<item name="XInclude" href="/manual/configuration.html#XInclude"/>
<item name="Status Messages" href="/manual/configuration.html#StatusMessages"/>
<item name="Unit Testing in Maven" href="/manual/configuration.html#UnitTestingInMaven"/>
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cda6fb61/src/site/xdoc/manual/configuration.xml.vm
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/configuration.xml.vm b/src/site/xdoc/manual/configuration.xml.vm
index f9283ff..44d1491 100644
--- a/src/site/xdoc/manual/configuration.xml.vm
+++ b/src/site/xdoc/manual/configuration.xml.vm
@@ -1051,16 +1051,77 @@ rootLogger.appenderRef.stdout.ref = STDOUT
JSR 223 scripting framework and only require that the jars for that language be installed.
</p>
<p>
- The components that support using scripts do so by allowing a <script> element to be configured on
+ The components that support using scripts do so by allowing a <script>, <scriptFile>, or
+ <scriptRef> element to be configured on
them. The script element contains a name for the script, the language of the script, and the script text.
+ The scriptFile element contains the name of the script, its location, its language, its charset, and
+ whether the file should be watched for changes. The scriptRef element contains the name of the
+ script that is defined in the <scripts> configuration element.
The name of the script is used to store the script, along with its ScriptEngine, so it can quickly be
located each time the script needs to be run. While the name is not required, providing it will help in
- debugging problems when the script is running. The language must be provided and must specify one of
- the language names that appear in the Configuration status log as described in the next section.
+ debugging problems when the script is running. The language must be provided on the script element and must
+ specify one of the language names that appear in the Configuration status log as described in the next
+ section. If the language is not specified on the scriptFile element the language will be determined by
+ the file extension of the script path. If file monitoring is requested it will only be enabled if
+ a non-zero monitorInterval is specified on the configuration element. That interval will be used to
+ check for changes in the file.
</p>
+ <pre class="prettyprint linenums"><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="debug" name="RoutingTest">
+ <Scripts>
+ <Script name="selector" language="javascript"><![CDATA[
+ var result;
+ if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
+ result = "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ result = "Flow";
+ }
+ result;
+ ]]]]><![CDATA[></Script>
+ <ScriptFile name="groovy.filter" path="scripts/filter.groovy"/>
+ </Scripts>
+
+ <Appenders>
+ <Console name="STDOUT">
+ <ScriptPatternSelector defaultPattern="%d %p %m%n">
+ <ScriptRef ref="selector"/>
+ <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
+ <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
+ </ScriptPatternSelector>
+ <PatternLayout pattern="%m%n"/>
+ </Console>
+ </Appenders>
+
+ <Loggers>
+ <Logger name="EventLogger" level="info" additivity="false">
+ <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
+ <Script name="GroovyFilter" language="groovy"><![CDATA[
+ if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ return true;
+ } else if (logEvent.getContextMap().containsKey("UserId")) {
+ return true;
+ }
+ return false;
+ ]]]]><![CDATA[>
+ </Script>
+ </ScriptFilter>
+ <AppenderRef ref="STDOUT"/>
+ </Logger>
+
+ <Root level="error">
+ <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
+ <ScriptRef ref="groovy.filter"/>
+ </ScriptFilter>
+ <AppenderRef ref="STDOUT"/>
+ </Root>
+ </Loggers>
+
+</Configuration>]]>
+ </pre>
<p>
If the status attribute on the Configuration element is set to DEBUG the list of script engines currently
- installed and their attributes will be listed. Although some engines may say they are not thread safe
+ installed and their attributes will be listed. Although some engines may say they are not thread safe,
Log4j takes steps to insure that the scripts will run in a thread-safe manner if the engine advertises
that it is not thread safe.
</p>
@@ -1082,12 +1143,12 @@ rootLogger.appenderRef.stdout.ref = STDOUT
</p>
<p>
The components that support scripting expect a return value to be passed back to the calling Java code.
- This is not a problem for several of the scripting languages. However, Javascript does not allow a
+ This is not a problem for several of the scripting languages, but Javascript does not allow a
return statement unless it is within a function. However, Javascript will return the value of the last
statement executed in the script. As a consequence, code such as that shown below will result in the
desired behavior.
</p>
- <pre>
+ <pre><![CDATA[
var result;
if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
result = "NoLocation";
@@ -1095,7 +1156,7 @@ rootLogger.appenderRef.stdout.ref = STDOUT
result = "Flow";
}
result;
- </pre>
+ ]]></pre>
<h4>A special note on Beanshell</h4>
<p>
JSR 223 scripting engines are supposed to identify that they support the Compilable interface if they
@@ -1104,14 +1165,14 @@ rootLogger.appenderRef.stdout.ref = STDOUT
Beanshell script when it tries to compile them. All Beanshell scripts will then be interpreted on each
execution.
</p>
- <pre>
+ <pre><![CDATA[
2015-09-27 16:13:23,095 main DEBUG Script BeanShellSelector is compilable
2015-09-27 16:13:23,096 main WARN Error compiling script java.lang.Error: unimplemented
at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:175)
at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:154)
at org.apache.logging.log4j.core.script.ScriptManager$MainScriptRunner.<init>(ScriptManager.java:125)
at org.apache.logging.log4j.core.script.ScriptManager.addScript(ScriptManager.java:94)
- </pre>
+ ]]></pre>
</subsection>
<a name="XInclude"/>
<subsection name="XInclude">
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cda6fb61/src/site/xdoc/manual/filters.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/filters.xml b/src/site/xdoc/manual/filters.xml
index d5b1252..15db5f0 100644
--- a/src/site/xdoc/manual/filters.xml
+++ b/src/site/xdoc/manual/filters.xml
@@ -475,7 +475,7 @@
</tr>
<tr>
<td>script</td>
- <td>Script</td>
+ <td>Scriptm, ScriptFile or ScriptRef</td>
<td>The Script element that specifies the logic to be executed.
</td>
</tr>
@@ -548,6 +548,41 @@
<td>The StrSubstitutor used to replace lookup variables.</td>
</tr>
</table>
+ <p>
+ The sample below shows how to declare script fiels and then reference them in specific components.
+ </p>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="ERROR">
+ <Scripts>
+ <ScriptFile name="filter.js" language="JavaScript" path="src/test/resources/scripts/filter.js" charset="UTF-8" />
+ <ScriptFile name="filter.groovy" path="src/test/resources/scripts/filter.groovy" charset="UTF-8" />
+ </Scripts>
+ <Appenders>
+ <List name="List">
+ <PatternLayout pattern="[%-5level] %c{1.} %msg%n"/>
+ </List>
+ </Appenders>
+ <Loggers>
+ <Logger name="TestJavaScriptFilter" level="trace" additivity="false">
+ <AppenderRef ref="List">
+ <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
+ <ScriptRef ref="filter.js" />
+ </ScriptFilter>
+ </AppenderRef>
+ </Logger>
+ <Logger name="TestGroovyFilter" level="trace" additivity="false">
+ <AppenderRef ref="List">
+ <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
+ <ScriptRef ref="filter.groovy" />
+ </ScriptFilter>
+ </AppenderRef>
+ </Logger>
+ <Root level="trace">
+ <AppenderRef ref="List" />
+ </Root>
+ </Loggers>
+</Configuration>
+ ]]></pre>pre>
</subsection>
<a name="StructuredDataFilter"/>
<subsection name="StructuredDataFilter">
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cda6fb61/src/site/xdoc/manual/layouts.xml.vm
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/layouts.xml.vm b/src/site/xdoc/manual/layouts.xml.vm
index e29de73..47170ea 100644
--- a/src/site/xdoc/manual/layouts.xml.vm
+++ b/src/site/xdoc/manual/layouts.xml.vm
@@ -407,7 +407,14 @@ WARN [main]: Message 2</pre>
<tr>
<td>pattern</td>
<td>String</td>
- <td>A composite pattern string of one or more conversion patterns from the table below.</td>
+ <td>A composite pattern string of one or more conversion patterns from the table below. Cannot be
+ specified with a PatternSelector.</td>
+ </tr>
+ <tr>
+ <td>patternSelector</td>
+ <td>PatternSelector</td>
+ <td>A component that analyzes information in the LogEvent and determines which pattern should be
+ used to format the event. The pattern and patternSelector parameters are mutually exclusive.</td>
</tr>
<tr>
<td>replace</td>
@@ -557,7 +564,7 @@ WARN [main]: Message 2</pre>
</p>
<p>You can also use a set of braces containing a time zone id per
<a class="javadoc" href="${javadocRoot}/java/util/TimeZone.html${sharp}getTimeZone(java.lang.String)">
- java.util.TimeZone.getTimeZone</a>. If no date format specifier is given then the DEFAULT format is used.
+ java.util.TimeZone.getTimeZone</a>. If no date format specifier is given then ISO8601 format is assumed.
<table>
<tr>
<th>Pattern</th>
@@ -1472,7 +1479,49 @@ at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(Ext
<pre class="prettyprint linenums"><![CDATA[<PatternLayout>
<pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
</PatternLayout>]]></pre>
- </subsection>
+
+ <h4>Pattern Selectors</h4>
+ <p>
+ The PatternLayout can be configured with a PatternSelector to allow it to choose a pattern to use based on
+ attributes of the log event or other factors. A PatternSelector will normally be configured with a defaultPattern
+ attribute, which is used when other criteria don't match, and a set of PatternMatch elements that identify
+ the various patterns that can be selected.
+ </p>
+ <h5>MarkerPatternSelector</h5>
+ <p>
+ The MarkerPatternSelector selects patterns based on the Marker included in the log event. If the Marker in
+ the log event is equal to or is an ancestor of the name specified on the PatternMatch key attribute, then the
+ pattern specified on that PatternMatch element will be used.
+ </p>
+ <pre class="prettyprint linenums"><![CDATA[<PatternLayout>
+ <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
+ <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
+ </MarkerPatternSelector>
+</PatternLayout>]]></pre>
+ <h5>ScriptPatternSelector</h5>
+ <p>
+ The ScriptPatternSelector executes a script as descibed in the <a href="../configuration.html#Scripts">Scripts</a> section of the
+ Configuration chapter. The script is passed all the properties configured in the Properties section of the
+ configuration, the StrSubstitutor used by the Confguration in the "substitutor" vairables, and the
+ log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that
+ should be used, or null if the default pattern should be used.
+ </p>
+ <pre class="prettyprint linenums"><![CDATA[<PatternLayout>
+ <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
+ <Script name="BeanShellSelector" language="bsh"><![CDATA[
+ if (logEvent.getLoggerName().equals("NoLocation")) {
+ return "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ return "Flow";
+ } else {
+ return null;
+ }]]]]><![CDATA[>
+ </Script>
+ <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
+ <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
+ </ScriptPatternSelector>
+</PatternLayout>]]></pre>
+ </subsection>
<a name="RFC5424Layout"/>
<subsection name="RFC5424Layout">
<p>As the name implies, the RFC5424Layout formats LogEvents in accordance with