You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by pk...@apache.org on 2024/05/12 12:01:37 UTC
(logging-log4j2) 05/05: Move scripts to a separate file
This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch doc/2.x/configuration
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 1d1a69cf25dc1d12ff078db6fb554d070466998e
Author: Piotr P. Karwasz <pi...@karwasz.org>
AuthorDate: Sun May 12 14:01:07 2024 +0200
Move scripts to a separate file
---
src/site/antora/modules/ROOT/nav.adoc | 19 +--
.../modules/ROOT/pages/manual/configuration.adoc | 117 +------------------
.../antora/modules/ROOT/pages/manual/scripts.adoc | 127 +++++++++++++++++++++
3 files changed, 139 insertions(+), 124 deletions(-)
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index 218fec5959..dc69a9c656 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -40,22 +40,23 @@
** xref:manual/thread-context.adoc[]
** xref:manual/scoped-context.adoc[]
** xref:manual/resource-logger.adoc[]
-* xref:manual/configuration.adoc[]
-** xref:manual/configuration.adoc#configuration-file[Configuration file]
-** xref:manual/customconfig.adoc[]
+* Backend Configuration
+** xref:manual/configuration.adoc[Configuration file]
+** xref:manual/appenders.adoc[]
+** xref:manual/layouts.adoc[]
+*** xref:manual/json-template-layout.adoc[]
+** xref:manual/lookups.adoc[]
+** xref:manual/customloglevels.adoc[]
+** xref:manual/filters.adoc[]
+** xref:manual/scripts.adoc[]
** xref:manual/systemproperties.adoc[]
* xref:manual/usage.adoc[]
* xref:manual/cloud.adoc[]
-* xref:manual/lookups.adoc[]
-* xref:manual/appenders.adoc[]
-* xref:manual/layouts.adoc[]
-** xref:manual/json-template-layout.adoc[]
-* xref:manual/filters.adoc[]
* xref:manual/async.adoc[]
* xref:manual/garbagefree.adoc[]
* xref:manual/extending.adoc[]
+** xref::manual/customconfig.adoc[]
* xref:manual/plugins.adoc[]
-* xref:manual/customloglevels.adoc[]
* xref:manual/jmx.adoc[]
* xref:manual/logsep.adoc[]
* xref:manual/performance.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index a3ed9b7899..3c8cca2676 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -16,7 +16,6 @@
////
[id=configuration]
= Configuration
-
Ralph Goers <rg...@apache.org>; Piotr Karwasz <pk...@apache.org>
Since logging is a common way to monitor the health of an application and diagnose problems that occur in it, even moderately sized applications can contain thousands of logging statements.
@@ -374,7 +373,7 @@ See <<property-substitution>> for details.
Scripts::
+
-See <<scripts>> for details.
+See xref:manual/scripts.adoc[Scripts configuration] for details.
[id=global-configuration-attributes]
=== Global configuration attributes
@@ -904,7 +903,7 @@ Duplicate properties replace those in previous configurations.
. xref:manual/filters.adoc[Filters] are aggregated under
xref:manual/filters.adoc#CompositeFilter[CompositeFilter], if more than one filter is defined.
-. <<scripts,Scripts>> are aggregated.
+. xref:manual/scripts.adoc[] are aggregated.
Duplicate definitions replace those in previous configurations.
. xref:manual/appenders.adoc[Appenders] are aggregated.
@@ -915,118 +914,6 @@ Logger attributes are individually merged with duplicates being replaced by thos
Appender references on a logger are aggregated with duplicates being replaced by those in later configurations.
The strategy merges filters on loggers using the rule above.
-[id=scripts]
-=== [[Scripts]] Scripts
-
-Log4j provides support for
-https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/[JSR
-223] scripting languages to be used in some of its components.
-
-[WARNING]
-====
-In order to enable a scripting language, its name must be included in the
-xref:manual/systemproperties.adoc#log4j2.scriptEnableLanguages[log4j2.scriptEnableLanguages]
-configuration property.
-====
-
-Each component that allows scripts can contain on of the following configuration elements:
-
-Script::
-+
-This element specifies the content of the script directly and has:
-+
---
-* a required `language` configuration attribute that specifies the name of the JSR 223 language to use,
-* a required `scriptText` configuration attribute that contains the text of the script.
-In the XML configuration format, the text of the script can also be written as content of the `<Script>` XML element.
-This allows the usage of a `CDATA` block.
---
-+
-The element can be assigned a name using the `name` configuration attribute.
-+
-See also
-xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-Script[Plugin reference].
-
-ScriptFile::
-+
-This element points to an external script file and has:
-+
---
-* a required `path` attribute that points to the path to a file name.
-* an optional `language` attribute that specifies the name of the JSR 223 language to use.
-If not provided, the language is deduced from the extension of the file.
-* an optional `isWatched` attribute.
-If set to `true` the script file will be monitored for changes.
---
-+
-The element can be assigned a name using the `name` configuration attribute.
-+
-See also
-xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptFile[Plugin reference].
-
-ScriptRef::
-+
-This element references a **named** script from the global
-xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin[Scripts]
-container plugin in the configuration file.
-+
-See also
-xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptRef[Plugin reference].
-
-The environment in which the script runs is different for each Log4j script-based component.
-
-[tabs]
-====
-XML::
-+
-[source,xml]
-----
-include::example$configuration/scripts.xml[]
-----
-
-JSON::
-+
-[source,json]
-----
-include::example$configuration/scripts.json[]
-----
-
-YAML::
-+
-[source,yaml]
-----
-include::example$configuration/scripts.yaml[]
-----
-
-Java properties::
-+
-[source,properties]
-----
-include::example$configuration/scripts.properties[]
-----
-====
-
-[id=a-special-note-on-beanshell]
-==== A special note on Beanshell
-
-JSR 223 scripting engines are supposed to identify that they support the
-https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/Compilable.html[Compilable]
-interface if they support compiling their scripts.
-
-Beanshell does extend the `Compilable` interface, but an attempt to compile a script ends up in an
-https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/Error.html[Error]
-being thrown.
-Log4j catches the throwable, but issues a warning in the status logger.
-
-----
-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)
-----
-
[id=format-specific-notes]
=== Format specific notes
diff --git a/src/site/antora/modules/ROOT/pages/manual/scripts.adoc b/src/site/antora/modules/ROOT/pages/manual/scripts.adoc
new file mode 100644
index 0000000000..cacedad1f6
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/manual/scripts.adoc
@@ -0,0 +1,127 @@
+////
+ 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.
+////
+[id=scripts]
+= Scripts
+
+Log4j provides support for
+https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/[JSR
+223] scripting languages to be used in some of its components.
+
+[WARNING]
+====
+In order to enable a scripting language, its name must be included in the
+xref:manual/systemproperties.adoc#log4j2.scriptEnableLanguages[log4j2.scriptEnableLanguages]
+configuration property.
+====
+
+Each component that allows scripts can contain on of the following configuration elements:
+
+Script::
++
+This element specifies the content of the script directly and has:
++
+--
+* a required `language` configuration attribute that specifies the name of the JSR 223 language to use,
+* a required `scriptText` configuration attribute that contains the text of the script.
+In the XML configuration format, the text of the script can also be written as content of the `<Script>` XML element.
+This allows the usage of a `CDATA` block.
+--
++
+The element can be assigned a name using the `name` configuration attribute.
++
+See also
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-Script[Plugin reference].
+
+ScriptFile::
++
+This element points to an external script file and has:
++
+--
+* a required `path` attribute that points to the path to a file name.
+* an optional `language` attribute that specifies the name of the JSR 223 language to use.
+If not provided, the language is deduced from the extension of the file.
+* an optional `isWatched` attribute.
+If set to `true` the script file will be monitored for changes.
+--
++
+The element can be assigned a name using the `name` configuration attribute.
++
+See also
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptFile[Plugin reference].
+
+ScriptRef::
++
+This element references a **named** script from the global
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin[Scripts]
+container plugin in the configuration file.
++
+See also
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptRef[Plugin reference].
+
+The environment in which the script runs is different for each Log4j script-based component.
+
+[tabs]
+====
+XML::
++
+[source,xml]
+----
+include::example$configuration/scripts.xml[]
+----
+
+JSON::
++
+[source,json]
+----
+include::example$configuration/scripts.json[]
+----
+
+YAML::
++
+[source,yaml]
+----
+include::example$configuration/scripts.yaml[]
+----
+
+Java properties::
++
+[source,properties]
+----
+include::example$configuration/scripts.properties[]
+----
+====
+
+[id=a-special-note-on-beanshell]
+== A special note on Beanshell
+
+JSR 223 scripting engines are supposed to identify that they support the
+https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/Compilable.html[Compilable]
+interface if they support compiling their scripts.
+
+Beanshell does extend the `Compilable` interface, but an attempt to compile a script ends up in an
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/Error.html[Error]
+being thrown.
+Log4j catches the throwable, but issues a warning in the status logger.
+
+----
+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)
+----
\ No newline at end of file