wrapper.filter.<x>.<n> Property Overview

Filters are a very powerful feature that makes it possible to add new behavior to existing applications without any coding. It works by monitoring the console output of a JVM for sequences of text. When they are found, any number of actions can then be taken.

One example is initiating a JVM restart whenever a specific error occurs. Some applications have known bugs where they stop working once getting into a certain state. This feature makes it possible to work around such problems immediately until they can be resolved in the application.

Properties used to configure filters are described below:

At the very least, a filter must define the wrapper.filter.trigger.<n> and wrapper.filter.action.<n> properties. Others are optional.

<n> component:

In each filter, the "<n>" component of the property name is an integer number counting up from "1". By default, there can be no missing numbers. The wrapper.ignore_sequence_gaps property can optionally be set to allow gaps in the sequence.

The Wrapper will scan the defined filters in incremental order using their <n> number. As soon as a filter is matched, the process will stop for that line of output.

A number of Usage Examples can be found below:

wrapper.filter.trigger.<n>
Compatibility :3.0.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

The trigger can be any string, and the following property is required for its configuration.

Example: 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=RESTART

Spaces In Trigger:

The string being filtered can contain spaces. But due to the way the configuration properties are loaded in general, any leading or trailing spaces will be trimmed when the property is loaded.

Example: 
wrapper.filter.trigger.1=  Restart me now.
wrapper.filter.action.1=RESTART

Wildcards:

Starting with Wrapper version 3.5.5, it is now possible to include wildcards ('*' or '?') in the trigger text if the wrapper.filter.allow_wildcards.<n> property is also set to TRUE.

Valid wildcard characters are:

  • A '*' character will match "0" (zero) or more characters.
  • A '?' character will match exactly one character.

NOTE

Trigger values will be located someplace within a single line of output, so it is not necessary to precede or trail a value with a "*" wildcard. Please be aware that doing so will actually hurt the logging performance a bit, as it makes it much more difficult for the pattern matching to determine that a given trigger is NOT found in a line of log output.

wrapper.filter.action.<n>
Compatibility :3.0.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

Specifying an action requires the following property to be configured. If an action is omitted, it will default to RESTART.

Example: 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=RESTART

Possible actions are:

  • DEBUG (Since ver. 3.5.0):

    will cause a debug message to be logged. This is only really useful in helping to understand when the action is fired.

  • STATS (Since ver. 3.5.52, Standard /Professional Edition):

    will print performance statistics.

  • DUMP (Since ver. 3.3.6):

    will invoke a thread dump.

  • GC (Since ver. 3.5.7):

    will invoke a full garbage collection sweep in the JVM. Be aware that doing this frequently can affect the performance of the JVM, as a full sweep will often cause all threads to freeze for the duration of the GC.

  • RESTART:

    will stop the current JVM and then restart a new invocation.

  • SHUTDOWN:

    will stop the JVM as well as the Wrapper.

  • USER_<n> (Since ver. 3.5.0, Professional Edition):

    will cause a user defined event to be fired. This can be either the sending of an email, or the execution of an external system command. The command could be anything from performing clean up operations to raising an SNMP trap.

  • PAUSE (Since ver. 3.5.0):

    will pause the Java application if pausing is enabled and the JVM is running. See the wrapper.pausable property for details.

  • RESUME (Since ver. 3.5.0):

    will resume the Java application if it is in a paused state. This could be used if the JVM is not stopped when paused. See the wrapper.pausable property for details.

  • SUSPEND_TIMEOUTS_<n> (Since ver. 3.5.40, Standard /Professional Edition):

    Tells the Wrapper to suspend all timeouts used when the JVM is not responding. <n> specifies the number of seconds to suspend timeouts, and should be in the range 1-3600 (1h). This could be used if the Java application needs to perform a long blocking task and avoid having the Wrapper considering the application as unresponsive.

    Timeouts can also be suspended via other action properties, the command file or the Java WrapperManager.suspendTimeouts() method.

    If several requests to suspend timeouts are made, the number of seconds specified by each request will not be summed. Instead, the newly specified time will replace the remaining suspension time if it is longer, and will be ignored otherwise.

  • RESUME_TIMEOUTS (Since ver. 3.5.40, Standard /Professional Edition):

    Tells the Wrapper to resume all timeouts previously suspended.

    Timeouts can also be resumed via other action properties, the command file or the Java WrapperManager.resumeTimeouts() method.

  • NONE:

    is useful because it will prevent any triggers with a higher number from being triggered.

Chaining Multiple Actions:

Starting with Wrapper version 3.5.0, it is possible to specify more than one action by separating them with a space or comma. When more than one action is specified, they will be executed in rapid succession in the order specified.

Matching with the trigger, the following example will perform a thread dump and then restart the JVM.

Example: 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=DUMP,RESTART

wrapper.filter.allow_wildcards.<n>
Compatibility :3.5.5
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

If set to TRUE, this property tells the Wrapper to process any wildcards found in wrapper.filter.trigger.<n> for the filter. See: Usage Example below for details

Example: 
wrapper.filter.allow_wildcards.1=TRUE

NOTE

It is not that bad, but searching for a trigger containing a wildcard can be a bit more CPU intensive. This is especially true with long lines of output when the trigger's wildcards are towards the beginning of the trigger. Multiple wildcards in the same trigger will also slow things down, as the Wrapper needs to try all possible combinations to see if the pattern is matched.

wrapper.filter.message.<n>
Compatibility :3.5.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/OSIBM z/Linux

The wrapper.filter.message.<n> property can be used to control the message which is displayed to the user when a trigger is fired. This can be very useful to explain the user what is happening. The default value is "Filter trigger matched."

Example: 
wrapper.filter.trigger.1=java.lang.OutOfMemoryError
wrapper.filter.action.1=RESTART
wrapper.filter.message.1=The JVM has run out of memory.

Usage Examples:

In this section, we will show you several examples of how to make use of triggers. Filters work by monitoring the console output of the JVM. In order for a trigger to be fired by an exception, the Java application must print the message being filtered to the console.

Simple Match

In many cases, you may want to trigger an action in response to an existing message in the output of your application.

In this example, we want to trigger on all instances of the word "Error" and cause a restart of the JVM.

Example: 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=RESTART
Example Wrapper Output: 
jvm 1    | The next line should cause the Wrapper to restart the JVM:
jvm 1    |   Error
wrapper  | Filter trigger matched.  Restarting JVM.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...

Wildcards

In some cases, you do not know the exact string that you will be matching against, so it is often very useful to be able to set up a trigger containing wildcards that can be used to make the match.

Example: 
wrapper.filter.trigger.1=Head*Tail-?
wrapper.filter.allow_wildcards.1=TRUE
wrapper.filter.action.1=RESTART
Example Wrapper Output: 
jvm 1    | The next line should cause the Wrapper to restart the JVM:
jvm 1    |   Head a bunch of stuff, then Tail-1 and some more stuff.
wrapper  | Filter trigger matched.  Restarting JVM.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...

Chaining Multiple Actions

Starting with Wrapper version 3.5.0, it is possible to specify more than one action by separating them with a space or comma. When more than one action is specified, they will be executed in rapid succession in the order specified.

The following example will perform a thread dump and then restart the JVM in response to a "user error" message being detected in the console output.

Example: 
wrapper.filter.trigger.1=User Error
wrapper.filter.action.1=DUMP,RESTART
Example Wrapper Output: 
jvm 1    | The next line should cause the Wrapper to restart the JVM:
jvm 1    |   User Error
wrapper  | Filter trigger matched.  Requesting thread dump.
wrapper  | Dumping JVM state.
wrapper  | Filter trigger matched.  Restarting JVM.
jvm 1    | Full thread dump Java HotSpot(TM) Client VM (1.5.0_24-149 mixed mode, sharing):
jvm 1    | 
jvm 1    | "WrapperSimpleAppMain" prio=5 tid=0x0100f400 nid=0x86c600 waiting on condition [0xb0e8e000..0xb0e8ed90]
jvm 1    | 	at java.lang.Thread.sleep(Native Method)
jvm 1    | ...
jvm 1    | "Exception Catcher Thread" prio=10 tid=0x01001910 nid=0x80ac00 runnable 
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...

Match With Exceptions

In many cases, you will want to write some logic to trigger off of a piece of text, but then discover that in certain contexts, you want to ignore them. The trigger will be processed in order of "<n>". Once a match is found, all others will be ignored. This makes it possible to setup up match exceptions.

In this example, we want to trigger on all instances of the word "Error" and to restart JVM except when it is found in "IgnoreError".

Example: 
wrapper.filter.trigger.1=IgnoreError
wrapper.filter.action.1=NONE
wrapper.filter.trigger.2=Error
wrapper.filter.action.2=RESTART
Example Wrapper Output: 
jvm 1    | The next line should be ignored:
jvm 1    |   IgnoreError
jvm 1    | 
jvm 1    | The next line should cause the Wrapper to restart the JVM:
jvm 1    |   Error
wrapper  | Filter trigger matched.  Restarting JVM.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...

OutOfMemoryError Detection

NOTE

Starting with Wrapper version 3.5.16, the default Wrapper configuration file template was updated so that a restart due to a matched OutOfMemoryError filter will no longer be triggered by default if the user enables -verbose:class output.

Putting all of this together, we can create a filter to detect whenever an OutOfMemoryError is thrown in a stack trace.

The simplest way to do this is as follows:

Example: 
wrapper.filter.trigger.1=java.lang.OutOfMemoryError
wrapper.filter.action.1=RESTART

This can have the problem that if the class name is displayed in any other unexpected location, an unintended restart could be triggered. One example of this is when the -XX:+PrintClassHistogram argument has been passed to the JVM, Java will output a very useful histogram of all loaded classes, showing how many instances are currently in memory. When the Java outputs the count for the OutOfMemoryError class, the above trigger will cause the JVM to restart.

Example: 
jvm 1    |  186:             6            384  sun.reflect.generics.repository.MethodRepository
jvm 1    |  187:             8            384  java.lang.OutOfMemoryError
wrapper  | The JVM has run out of memory.  Restarting JVM.
jvm 1    |  188:             8            384  java.io.OutputStreamWriter
jvm 1    |  189:             1            376  java.awt.Checkbox

To work around this, it is possible to set up exceptions. However, if we know that we want to only trigger off of the OutOfMemoryError class when it is shown in a stack trace, we can make use of the wildcards to produce a more focused pattern.

Example: 
wrapper.filter.trigger.1=Exception in thread "*" java.lang.OutOfMemoryError
wrapper.filter.allow_wildcards.1=TRUE
wrapper.filter.action.1=RESTART
wrapper.filter.message.1=The JVM has run out of memory.
Example Wrapper Output: 
jvm 1    | Mention the java.lang.OutOfMemoryError exception (Not triggered)
jvm 1    | 
jvm 1    | Now thow a new java.lang.OutOfMemoryError to invoke a stack trace:
jvm 1    | Exception in thread "MyApp-Main" java.lang.OutOfMemoryError
wrapper  | The JVM has run out of memory.  Restarting JVM.
jvm 1    |      at com.myapp.Main.doSomething(Main.java:321)
jvm 1    |      at com.myapp.Main.main(Main.java:654)
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...

There is still one case where you could get a false-positive, however. If the user prints out the entire Wrapper configuration, for example, then you see an output like the following:

Example Wrapper Output: 
jvm 1    |   wrapper.filter.trigger.1=Exception in thread "*" java.lang.OutOfMemoryError
wrapper  | The JVM has run out of memory.  Restarting JVM.

This is, of course, not what you want. You can avoid this by doing a plain text match on the same text WITHOUT wildcards enabled, as follows:

Example: 
wrapper.filter.trigger.1=Exception in thread "*" java.lang.OutOfMemoryError
wrapper.filter.action.1=NONE

wrapper.filter.trigger.2=Exception in thread "*" java.lang.OutOfMemoryError
wrapper.filter.allow_wildcards.2=TRUE
wrapper.filter.action.2=RESTART
wrapper.filter.message.2=The JVM has run out of memory.