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 <[email protected]> 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 <[email protected]>; Piotr Karwasz <[email protected]> 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
