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/09/28 04:39:00 UTC
[1/2] logging-log4j2 git commit: Add bindings for all keys even when
null
Repository: logging-log4j2
Updated Branches:
refs/heads/LOG4J2-1136 49342732e -> c309ba01b
Add bindings for all keys even when null
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/e6f719b1
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/e6f719b1
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/e6f719b1
Branch: refs/heads/LOG4J2-1136
Commit: e6f719b112706c295dac3dedf8fe8e03d7276074
Parents: 4934273
Author: Ralph Goers <rg...@nextiva.com>
Authored: Sun Sep 27 17:35:22 2015 -0700
Committer: Ralph Goers <rg...@nextiva.com>
Committed: Sun Sep 27 17:35:22 2015 -0700
----------------------------------------------------------------------
.../java/org/apache/logging/log4j/core/filter/ScriptFilter.java | 3 +++
1 file changed, 3 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/e6f719b1/log4j-core/src/main/java/org/apache/logging/log4j/core/filter/ScriptFilter.java
----------------------------------------------------------------------
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/filter/ScriptFilter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/filter/ScriptFilter.java
index 0e9698a..ea23364 100644
--- a/log4j-core/src/main/java/org/apache/logging/log4j/core/filter/ScriptFilter.java
+++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/filter/ScriptFilter.java
@@ -63,6 +63,7 @@ public final class ScriptFilter extends AbstractFilter {
bindings.put("marker", marker);
bindings.put("message", new SimpleMessage(msg));
bindings.put("parameters", params);
+ bindings.put("throwable", null);
bindings.putAll(configuration.getProperties());
bindings.put("substitutor", configuration.getStrSubstitutor());
Object object = configuration.getScriptManager().execute(script.getName(), bindings);
@@ -77,6 +78,7 @@ public final class ScriptFilter extends AbstractFilter {
bindings.put("level", level);
bindings.put("marker", marker);
bindings.put("message", msg instanceof String ? new SimpleMessage((String)msg) : new ObjectMessage(msg));
+ bindings.put("parameters", null);
bindings.put("throwable", t);
bindings.putAll(configuration.getProperties());
bindings.put("substitutor", configuration.getStrSubstitutor());
@@ -92,6 +94,7 @@ public final class ScriptFilter extends AbstractFilter {
bindings.put("level", level);
bindings.put("marker", marker);
bindings.put("message", msg);
+ bindings.put("parameters", null);
bindings.put("throwable", t);
bindings.putAll(configuration.getProperties());
bindings.put("substitutor", configuration.getStrSubstitutor());
[2/2] logging-log4j2 git commit: LOG4J2-1136 - First part of
documentation
Posted by rg...@apache.org.
LOG4J2-1136 - First part of documentation
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/c309ba01
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/c309ba01
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/c309ba01
Branch: refs/heads/LOG4J2-1136
Commit: c309ba01bce7d3debcaa07529fa1d43f4dcd95c1
Parents: e6f719b
Author: Ralph Goers <rg...@nextiva.com>
Authored: Sun Sep 27 19:38:49 2015 -0700
Committer: Ralph Goers <rg...@nextiva.com>
Committed: Sun Sep 27 19:38:49 2015 -0700
----------------------------------------------------------------------
src/site/site.xml | 2 +
src/site/xdoc/manual/configuration.xml.vm | 73 +++++++++++++++++++++
src/site/xdoc/manual/filters.xml | 88 ++++++++++++++++++++++++++
3 files changed, 163 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c309ba01/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 6b69789..8c076fa 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -72,6 +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="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"/>
@@ -155,6 +156,7 @@
<item name="Map" href="/manual/filters.html#MapFilter"/>
<item name="Marker" href="/manual/filters.html#MarkerFilter"/>
<item name="Regex" href="/manual/filters.html#RegexFilter"/>
+ <item name="Script" href="/manual/filters.html#Script"/>
<item name="Structured Data" href="/manual/filters.html#StructuredDataFilter"/>
<item name="Thread Context Map" href="/manual/filters.html#ThreadContextMapFilter"/>
<item name="Threshold" href="/manual/filters.html#ThresholdFilter"/>
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c309ba01/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 054dcd3..e831ba5 100644
--- a/src/site/xdoc/manual/configuration.xml.vm
+++ b/src/site/xdoc/manual/configuration.xml.vm
@@ -1040,6 +1040,79 @@ rootLogger.appenderRef.stdout.ref = STDOUT
See <a href="appenders.html#RoutingAppender">RoutingAppender</a> for more information.</i>
</p>
</subsection>
+ <a name="Scripts"/>
+ <subsection name="Scripts">
+ <p>
+ Log4j provides support for <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/scripting/">JSR 223</a>
+ scripting languages to be used in some of its components. Any language that provides support for the JSR
+ 223 scripting engine may be used. A list of the languages and bindings for them can be found at the
+ <a href="https://java.net/projects/scripting/sources/svn/show/trunk/engines">Scripting Engine</a> web site.
+ However, some of the languages listed there, such as JavaScript, Groovy and Beanshel, directly support the
+ 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
+ them. The script element contains a name for the script, the language of the script, and the script text.
+ 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 log as described in the next section.
+ </p>
+ <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
+ 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>
+ <pre>
+2015-09-27 16:13:22,925 main DEBUG Installed script engines
+2015-09-27 16:13:22,963 main DEBUG AppleScriptEngine Version: 1.1, Language: AppleScript, Threading: Not Thread Safe,
+ Compile: false, Names: {AppleScriptEngine, AppleScript, OSA}
+2015-09-27 16:13:22,983 main DEBUG Groovy Scripting Engine Version: 2.0, Language: Groovy, Threading: MULTITHREADED,
+ Compile: true, Names: {groovy, Groovy}
+2015-09-27 16:13:23,030 main DEBUG BeanShell Engine Version: 1.0, Language: BeanShell, Threading: MULTITHREADED,
+ Compile: true, Names: {beanshell, bsh, java}
+2015-09-27 16:13:23,039 main DEBUG Mozilla Rhino Version: 1.7 release 3 PRERELEASE, Language: ECMAScript, Threading: MULTITHREADED,
+ Compile: true, Names: {js, rhino, JavaScript, javascript, ECMAScript, ecmascript}
+ </pre>
+ <p>
+ When the scripts are executed they will be provided with a set of variables that should allow them to
+ accomplish whatever task they are expected to perform. See the documentation for the individual components
+ for the list of variables that are available to the script.
+ </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
+ 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>
+ var result;
+ if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
+ result = "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ result = "Flow";
+ }
+ result;
+ </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
+ support compiling their scripts. Beanshell does this. However, whenever the compile method is called it
+ throws an Error (not an Exception). Log4j catches this but will log the warning shown below for each
+ Beanshell script when it tries to compile them. All Beanshell scripts will then be interpreted on each
+ execution.
+ </p>
+ <pre>
+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>
+ </subsection>
<a name="XInclude"/>
<subsection name="XInclude">
<p>
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c309ba01/src/site/xdoc/manual/filters.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/filters.xml b/src/site/xdoc/manual/filters.xml
index edfb386..d5b1252 100644
--- a/src/site/xdoc/manual/filters.xml
+++ b/src/site/xdoc/manual/filters.xml
@@ -461,6 +461,94 @@
</Loggers>
</Configuration>]]></pre>
</subsection>
+ <a name="Script"/>
+ <subsection name="Script">
+ <p>
+ The ScriptFilter executes a script that returns true or false.
+ </p>
+ <table>
+ <caption align="top">Script Filter Parameters</caption>
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>script</td>
+ <td>Script</td>
+ <td>The Script element that specifies the logic to be executed.
+ </td>
+ </tr>
+ <tr>
+ <td>onMatch</td>
+ <td>String</td>
+ <td>Action to take when the script returns true. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
+ </tr>
+ <tr>
+ <td>onMismatch</td>
+ <td>String</td>
+ <td>Action to take when the filter returns false. May be ACCEPT, DENY or NEUTRAL. The default value is
+ DENY.</td>
+ </tr>
+ </table>
+ <table>
+ <caption align="top">Script Parameters</caption>
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>configuration</td>
+ <td>Configuration</td>
+ <td>The Configuration that owns this ScriptFilter.</td>
+ </tr>
+ <tr>
+ <td>level</td>
+ <td>Level</td>
+ <td>The logging Level associated with the event. Only present when configured as a global filter.</td>
+ </tr>
+ <tr>
+ <td>loggerName</td>
+ <td>String</td>
+ <td>The name of the logger. Only present when configured as a global filter.</td>
+ </tr>
+ <tr>
+ <td>logEvent</td>
+ <td>LogEvent</td>
+ <td>The LogEvent being processed. Not present when configured as a global filter.</td>
+ </tr>
+ <tr>
+ <td>marker</td>
+ <td>Marker</td>
+ <td>The Marker passed on the logging call, if any. Only present when configured as a global filter.</td>
+ </tr>
+ <tr>
+ <td>message</td>
+ <td>Message</td>
+ <td>The Message associated with the logging call. Only present when configured as a global filter.</td>
+ </tr>
+ <tr>
+ <td>parameters</td>
+ <td>Object[]</td>
+ <td>The parameters passed to the logging call. Only present when configured as a global filter.
+ Some Messages include the parameters as part of the Message.
+ </td>
+ </tr>
+ <tr>
+ <td>throwable</td>
+ <td>Throwable</td>
+ <td>The Throwable passed to the logging call, if any. Only present when configured as a global filter.
+ Som Messages include Throwable as part of the Message.
+ </td>
+ </tr>
+ <tr>
+ <td>substitutor</td>
+ <td>StrSubstitutor</td>
+ <td>The StrSubstitutor used to replace lookup variables.</td>
+ </tr>
+ </table>
+ </subsection>
<a name="StructuredDataFilter"/>
<subsection name="StructuredDataFilter">
<p>