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 <[email protected]> Authored: Sun Sep 27 19:38:49 2015 -0700 Committer: Ralph Goers <[email protected]> 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>
