## Tag reference sheet Tag library reference for the following tag libraries: Log4j 2 Tag Library (log.tld) - uri:http://logging.apache.org/log4j/tld/log ## Log4j 2 Tag Library - version 1.0 The Log4j Log Tag Library creates the capability of inserting log statements in JSPs without the use of Java scripting. It uses the standard Log4j 2 API to log messages according to your Log4j configuration. You can learn more about Log4j 2 on the <a href="http://logging.apache.org/log4j/2.x/">Log4j 2</a> website. This tag library is based on the Jakarta Commons Log Taglib by Joseph Ottinger and James Strachan. For the most part, logging tags written against Jakarta Commons Log Taglib should work against this library as well. However, the "category" attribute from Jakarta has become the "logger" attribute in this library. In accordance with the org.apache.logging.log4j.Logger API, this tag library has tags to support the following logging calls: "catching", "entry", "exit", "log", "trace", "debug", "info", "warn", "error", and "fatal". The "trace" tag was not supported in Jakarta Commons Log Taglib. The "setLogger", "catching", "entry", and "trace" tags are new to this library. This tag library also supports the conditional tag "ifEnabled" (new) and troubleshooting tag "dump" (existed in Jakarta Commons Log Taglib). By default, this tag library uses a different Logger for each JSP named after the JSP ID. You can customize the Logger in any of the logging tags or the "ifEnabled" tag with the "logger" attribute. You can also use the "setLogger" tag to specify the Logger that should apply for the rest of a JSP's execution. If the "setLogger" tag comes before any other logging tags in a JSP, the default Logger for that JSP will not be created, but instead the specified logger is the only one that will be used. Every effort was made to optimize these tags and ensure decent performance, but users of this library should keep in mind that the creation and execution of JSP tags adds significant overhead to the standard Log4j method calls. While the "trace", "debug", and "info" options are available in this library, their uses are not nanosecond order of magnitude with logging off that users may be used to with standard Log4j method calls. Therefore, they should be used sparingly. Use of the "ifEnabled" tag does not improve this performance; this tag is available to conditionally evaluate other actions in addition to logging actions. Namespace definition: xmlns:log="http://logging.apache.org/log4j/tld/log" Tags catching Equivalent of org debug Equivalent of org dump Displays all variables bound to the specified scope entry Equivalent of org error Equivalent of org exit Equivalent of org fatal Equivalent of org ifEnabled Conditional tag that evaluates its body only if the specified log level and marker are enabled info Equivalent of org log Equivalent of org setLogger Sets the default Logger to use for the rest of this JSP's execution OR exports an org trace Equivalent of org warn Equivalent of org Required attributes are marked with a* ### <log:catching> Equivalent of org.apache.logging.log4j.Logger#catching(). Can contain:empty #### Example
    <c:catch var="myException">
        <%= 5 / 0 %>
    </c:catch>
    <c:if test="${myException != null}">
        <log:catching exception="${myException}" />
    </c:if>
#### Attributes
Name | Description | Type
--- | --- | ---
exception* | The exception that should be logged. | String
level | The name of any valid level (TRACE, DEBUG, INFO, etc.) or an actual Level instance to log this at. This value is case-insensitive and defaults to ERROR for this tag. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
### <log:debug> Equivalent of org.apache.logging.log4j.Logger#debug(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be substituted in the String message. The "message" must be a String for this to work correctly. See the Log4j 2 manual for more information about message parameters and substitution. Only attribute values are used; attribute names are ignored. Can contain:JSP #### Example
    <log:debug message="Log this message." />
    <log:debug logger="com.foo.bar" message="${objectToLog}" exception="${exception}"
               marker="${marker}" />
    <log:debug logger="com.foo.bar" exception="${exception}" marker="${marker}">
        Log this message
    </log:debug>
#### Attributes
Name | Description | Type
--- | --- | ---
exception | Optional exception that should be logged. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Optional marker data to include in this logging event. | org.apache.logging.log4j.Marker
message | The message that should be logged. May be a String, Object, or org.apache.logging.log4j.message.Message. Either this attribute or body content are required. | String
### <log:dump> Displays all variables bound to the specified scope. Can contain:empty #### Example
    <log:dump scope="page" />
    <log:dump scope="request" />
    <log:dump scope="session" />
    <log:dump scope="application" />
#### Attributes
Name | Description | Type
--- | --- | ---
scope* | Either "page," "request," "session," or "application," the scope whose bound variables should be dumped onto the page inline. | String
### <log:entry> Equivalent of org.apache.logging.log4j.Logger#entry(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be logged with this entry (TRACE) statement. The attribute names will be ignored. Can contain:empty #### Example
    <log:entry />
    <log:entry logger="com.foo.bar" />
    <log:entry arg1="${value1}" arg2="${value2}" />
    <log:entry logger="${myLogger}" argA="${value1}" argB="${value2}" />
#### Attributes
Name | Description | Type
--- | --- | ---
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
### <log:error> Equivalent of org.apache.logging.log4j.Logger#error(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be substituted in the String message. The "message" must be a String for this to work correctly. See the Log4j 2 manual for more information about message parameters and substitution. Only attribute values are used; attribute names are ignored. Can contain:JSP #### Example
    <log:error message="Log this message." />
    <log:error logger="com.foo.bar" message="${objectToLog}" exception="${exception}"
               marker="${marker}" />
    <log:error logger="com.foo.bar" exception="${exception}" marker="${marker}">
        Log this message
    </log:error>
#### Attributes
Name | Description | Type
--- | --- | ---
exception | Optional exception that should be logged. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Optional marker data to include in this logging event. | org.apache.logging.log4j.Marker
message | The message that should be logged. May be a String, Object, or org.apache.logging.log4j.message.Message. Either this attribute or body content are required. | String
### <log:exit> Equivalent of org.apache.logging.log4j.Logger#exit(). Can contain:empty #### Example
    <log:exit />
    <log:exit logger="com.foo.bar" />
    <log:exit result="${value}" />
    <log:exit logger="${myLogger}" result="${value}" />
#### Attributes
Name | Description | Type
--- | --- | ---
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
result | An optional object to log with the exit (TRACE) statement. | String
### <log:fatal> Equivalent of org.apache.logging.log4j.Logger#fatal(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be substituted in the String message. The "message" must be a String for this to work correctly. See the Log4j 2 manual for more information about message parameters and substitution. Only attribute values are used; attribute names are ignored. Can contain:JSP #### Example
    <log:fatal message="Log this message." />
    <log:fatal logger="com.foo.bar" message="${objectToLog}" exception="${exception}"
               marker="${marker}" />
    <log:fatal logger="com.foo.bar" exception="${exception}" marker="${marker}">
        Log this message
    </log:fatal>
#### Attributes
Name | Description | Type
--- | --- | ---
exception | Optional exception that should be logged. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Optional marker data to include in this logging event. | org.apache.logging.log4j.Marker
message | The message that should be logged. May be a String, Object, or org.apache.logging.log4j.message.Message. Either this attribute or body content are required. | String
### <log:ifEnabled> Conditional tag that evaluates its body only if the specified log level and marker are enabled. Can contain:JSP #### Example
    <log:ifEnabled level="info">
        Evaluate this content
    </log:ifEnabled>

    <log:ifEnabled logger="com.foo.bar" level="INFO" marker="${marker}">
        Evaluate this content
    </log:ifEnabled>
#### Attributes
Name | Description | Type
--- | --- | ---
level* | The name of any valid Level (TRACE, DEBUG, INFO, etc.) or an actual Level instance to check whether it is enabled. This value is case-insensitive. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Marker data to include in the enabled check. | org.apache.logging.log4j.Marker
### <log:info> Equivalent of org.apache.logging.log4j.Logger#info(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be substituted in the String message. The "message" must be a String for this to work correctly. See the Log4j 2 manual for more information about message parameters and substitution. Only attribute values are used; attribute names are ignored. Can contain:JSP #### Example
    <log:info message="Log this message." />
    <log:info logger="com.foo.bar" message="${objectToLog}" exception="${exception}"
              marker="${marker}" />
    <log:info logger="com.foo.bar" exception="${exception}" marker="${marker}">
        Log this message
    </log:info>
#### Attributes
Name | Description | Type
--- | --- | ---
exception | Optional exception that should be logged. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Optional marker data to include in this logging event. | org.apache.logging.log4j.Marker
message | The message that should be logged. May be a String, Object, or org.apache.logging.log4j.message.Message. Either this attribute or body content are required. | String
### <log:log> Equivalent of org.apache.logging.log4j.Logger#log(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be substituted in the String message. The "message" must be a String for this to work correctly. See the Log4j 2 manual for more information about message parameters and substitution. Only attribute values are used; attribute names are ignored. Can contain:JSP #### Example
    <log:log level="warn" message="Log this message." />
    <log:log logger="com.foo.bar" level="ERROR" message="${objectToLog}"
             exception="${exception}" marker="${marker}" />
    <log:log logger="com.foo.bar" level="info" exception="${exception}" marker="${marker}">
        Log this message
    </log:log>
#### Attributes
Name | Description | Type
--- | --- | ---
exception | Optional exception that should be logged. | String
level* | The name of any valid level (TRACE, DEBUG, INFO, etc.) or an actual Level instance to log this at. This value is case-insensitive. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Optional marker data to include in this logging event. | org.apache.logging.log4j.Marker
message | The message that should be logged. May be a String, Object, or org.apache.logging.log4j.message.Message. Either this attribute or body content are required. | String
### <log:setLogger> Sets the default Logger to use for the rest of this JSP's execution OR exports an org.apache.logging.log4j.Logger instance as the specified EL variable. The "value" attribute specifies either the String name of a Logger to create or an actual Logger instance. By default, Loggers are constructed and assigned the standard org.apache.logging.log4j.message.ParameterizedMessageFactory. The optional "factory" attribute can be used to override the default message factory. Can contain:empty #### Example
    <log:logger value="com.foo.bar" />
    <log:logger value="com.bar.foo" var="myLogger" />
    <log:debug message="This should log with com.foo.bar." />
    <log:debug logger="${myLogger}" message="This should log with com.bar.foo." />
#### Attributes
Name | Description | Type
--- | --- | ---
factory | Specify this optional tag to provide a message factory other than the default ParameterizedMessageFactory message factory to use for the Logger. If the Logger has already been created with a different message factory, this will be ignored. Using this attribute makes no sense if the "value" attribute's value is an actual Logger instance, since its message factory cannot be changed. | org.apache.logging.log4j.message.MessageFactory
logger* | The name or instance of the Logger to set as the JSP's default Logger or the name of the Logger to export as the specified EL variable. | String
scope | Either "page," "request," "session," or "application," the optional scope that the EL variable should be exported to (defaults to "page"). | String
var | The optional name of the EL variable to export this Logger as. Using this attribute makes no sense if the "value" attribute's value is an actual Logger instance. That would result in an existing Logger on the scope being re-added to the scope. | String
### <log:trace> Equivalent of org.apache.logging.log4j.Logger#trace(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be substituted in the String message. The "message" must be a String for this to work correctly. See the Log4j 2 manual for more information about message parameters and substitution. Only attribute values are used; attribute names are ignored. Can contain:JSP #### Example
    <log:trace message="Log this message." />
    <log:trace logger="com.foo.bar" message="${objectToLog}" exception="${exception}"
               marker="${marker}" />
    <log:trace logger="com.foo.bar" exception="${exception}" marker="${marker}">
        Log this message
    </log:trace>
#### Attributes
Name | Description | Type
--- | --- | ---
exception | Optional exception that should be logged. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Optional marker data to include in this logging event. | org.apache.logging.log4j.Marker
message | The message that should be logged. May be a String, Object, or org.apache.logging.log4j.message.Message. Either this attribute or body content are required. | String
### <log:warn> Equivalent of org.apache.logging.log4j.Logger#warn(). This tag has dynamic attributes enabled. You may specify any number of arbitrary attributes whose values will be substituted in the String message. The "message" must be a String for this to work correctly. See the Log4j 2 manual for more information about message parameters and substitution. Only attribute values are used; attribute names are ignored. Can contain:JSP #### Example
    <log:warn message="Log this message." />
    <log:warn logger="com.foo.bar" message="${objectToLog}" exception="${exception}"
              marker="${marker}" />
    <log:warn logger="com.foo.bar" exception="${exception}" marker="${marker}">
        Log this message
    </log:warn>
#### Attributes
Name | Description | Type
--- | --- | ---
exception | Optional exception that should be logged. | String
logger | The name or instance of the Logger to use to override the default Logger for this JSP. | String
marker | Optional marker data to include in this logging event. | org.apache.logging.log4j.Marker
message | The message that should be logged. May be a String, Object, or org.apache.logging.log4j.message.Message. Either this attribute or body content are required. | String