Descripción de las Propiedades wrapper.filter.<x>.<n>

Los filtros son una función muy poderosa que permite agregar un nuevo comportamiento a las aplicaciones existentes sin necesidad de codificación. Funcionan monitoreando la salida de la consola de una JVM en busca de secuencias de texto. Cuando se encuentran, se pueden tomar cualquier cantidad de acciones.

Un ejemplo es reiniciar la JVM cada vez que se produce un error específico. Algunas aplicaciones tienen errores conocidos que hacen que dejen de funcionar una vez que llegan a un estado determinado. Esta función permite solucionar estos problemas de inmediato hasta que se puedan resolver en la aplicación.

A continuación se describen las propiedades que se utilizan para configurar filtros:

Como mínimo, un filtro debe definir las propiedades wrapper.filter.trigger.<n> y wrapper.filter.action.<n>. Las otras son opcionales.

Componente <n>:

En cada filtro, el componente "<n>" del nombre de la propiedad es un número entero a partir de "1". Por defecto, la numeración debe estar en secuencia sin espacios. La propiedad wrapper.ignore_sequence_gaps se puede configurar opcionalmente para permitir espacios en la secuencia.

El Wrapper escaneará los filtros definidos en orden incremental utilizando su número <n>. Tan pronto como coincida un filtro, el proceso se detendrá para esa línea de salida.

A continuación se pueden encontrar varios ejemplos de uso:

wrapper.filter.trigger.<n>
Compatibilidad :3.0.0
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

El disparador puede ser cualquier cadena y se requiere la siguiente propiedad es necesaria para su configuración.

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

Espacios en el Disparador:

La cadena que se está filtrando puede contener espacios, pero debido a la forma en que se cargan las propiedades de configuración en general, cualquier espacio inicial o final se eliminará cuando se cargue la propiedad.

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

Comodines:

A partir de la versión 3.5.5 del Wrapper, ahora es posible incluir comodines ('*' o '?') en el texto del disparador si la propiedad wrapper.filter.allow_wildcards.<n> también está configurada en TRUE.

Los caracteres comodín válidos son:

  • Un carácter '*', que coincidirá con "0 (zero)" o más carácteres.
  • Un carácter '?', que coincidirá con con exactamente un carácter.

NOTA

Los valores de disparadores se ubicarán en algún lugar dentro de una sola línea de salida, por lo que no es necesario colocar un comodín "*" antes o después de un valor. Tenga en cuenta que hacerlo afectará un poco el rendimiento del registro, ya que dificultará mucho más la comparación de patrones para determinar que un determinado disparador NO se encuentra en una línea de salida del registro.

wrapper.filter.action.<n>
Compatibilidad :3.0.0
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

Para especificar una acción es necesario configurar la siguiente propiedad. Si se omite una acción, se utilizará RESTART de forma predeterminada.

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

Las acciones posibles son:

  • DEBUG (desde versión 3.5.0):

    hará que se registre un mensaje de depuración. Esto solo es realmente útil para ayudar a comprender cuándo se ejecuta la acción.

  • STATS (desde versión 3.5.52, ediciones Estándar y Profesional):

    mostrará estadísticas de rendimiento.

  • DUMP (desde versión 3.3.6):

    invocará un volcado de hilo.

  • GC (desde versión 3.5.7):

    invocará un barrido completo de recolección de basura en la JVM. Tenga en cuenta que hacer esto con frecuencia puede afectar el rendimiento de la JVM, ya que un barrido completo a menudo provocará que todos los subprocesos se congelen mientras dure la GC.

  • RESTART:

    detendrá la JVM actual y luego reiniciará una nueva invocación.

  • SHUTDOWN:

    dentendrá la JVM, así como el Wrapper.

  • USER_<n> (desde versión 3.5.0, edición Profesional):

    hará que se active un evento definido por el usuario. Esto puede ser el envío de un correo electrónico o la ejecución de un comando externo del sistema. El comando puede ser cualquier cosa, desde realizar operaciones de limpieza hasta activar una trampa SNMP.

  • PAUSE (desde versión 3.5.0):

    pausará la aplicación Java si la pausa está habilitada y la JVM se está ejecutando. Consulte la página de la propiedad wrapper.pausable para más detalles.

  • RESUME (desde versión 3.5.0):

    reanudará la aplicación Java si está en estado de pausa. Esto se puede utilizar si la JVM no se detiene cuando está en pausa. Consulte la página de la propiedad wrapper.pausable para más detalles.

  • SUSPEND_TIMEOUTS_<n> (desde versión 3.5.40, ediciones Estándar y Profesional):

    Indica al Wrapper que suspenda todos los tiempos de espera utilizados cuando la JVM no responde. <n> especifica el número de segundos para suspender los tiempos de espera, y debe estar en el rango 1-3600 (1h). Esto se puede utilizar si la aplicación Java necesita realizar una tarea de bloqueo larga y evitar que el Wrapper considere que la aplicación no responde.

    Los tiempos de espera también pueden suspenderse mediante otras propiedades de la acción, el archivo de comandos, o el método Java WrapperManager.suspendTimeouts().

    Si se realizan varias solicitudes para suspender los tiempos de espera, no se sumará el número de segundos especificado por cada solicitud. En cambio, el tiempo recién especificado reemplazará el tiempo de suspensión restante si es más largo, y se ignorará en caso contrario.

  • RESUME_TIMEOUTS (desde versión 3.5.40, ediciones Estándar y Profesional):

    Indica al Wrapper que reanude todos los tiempos de espera suspendidos previamente.

    Los tiempos de espera también se pueden reanudar a través de otras propiedades de acción, el archivo de comandos, o el médoto Java WrapperManager.resumeTimeouts().

  • NONE:

    es útil porque evitará que se active cualquier disparador con un número mayor.

Encadenar Múltiples Acciones:

A partir de la versión 3.5.0 del Wrapper, es posible especificar más de una acción separándolas con un espacio o una coma. Cuando se especifica más de una acción, las acciones se ejecutarán en rápida sucesión en el orden especificado.

En coincidencia con el disparador, el siguiente ejemplo realizará un volcado de subprocesos y luego reiniciará la JVM.

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

wrapper.filter.allow_wildcards.<n>
Compatibilidad :3.5.5
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

Si se establece en TRUE, esta propiedad le indica al Wrapper que procese cualquier comodín encontrado en wrapper.filter.trigger.<n> para el filtro. Consulte: Ejemplos de Uso para más detalles.

Ejemplo: 
wrapper.filter.allow_wildcards.1=TRUE

NOTA

No es tan malo, pero buscar un disparador que contenga un comodín puede consumir un poco más de CPU. Esto es especialmente cierto con largas líneas de salida cuando los comodines del disparador están hacia el comienzo del disparador. El uso de varios comodines en el mismo disparador también enlentecerá el proceso, ya que el Wrapper debe probar todas las combinaciones posibles para ver si el patrón coincide.

wrapper.filter.message.<n>
Compatibilidad :3.5.0
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

La propiedad wrapper.filter.message.<n> se puede utilizar para controlar el mensaje que se muestra al usuario cuando se activa un disparador. Esto puede ser muy útil para explicar al usuario lo que está sucediendo. El valor predeterminado es "Filter trigger matched". The default value is "Filter trigger matched (Disparador de filtro coincidente)."

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

Ejemplos de Uso:

En esta sección, le mostraremos varios ejemplos de cómo utilizar los disparadores. Los filtros funcionan monitoreando la salida de la consola de la JVM. Para que se active un disparador por una excepción, la aplicación Java debe imprimir el mensaje que se está filtrando en la consola.

Coincidencia Simple

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.

Ejemplo: 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=RESTART
Ejemplo de Salida del Wrapper: 
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...

Comodines

En algunos casos, no se conoce la cadena exacta con la que se realizará la coincidencia, por lo que suele ser muy útil poder configurar un disparador que contenga comodines que se puedan usar para realizar la coincidencia.

Ejemplo: 
wrapper.filter.trigger.1=Head*Tail-?
wrapper.filter.allow_wildcards.1=TRUE
wrapper.filter.action.1=RESTART
Ejemplo de Salida del Wrapper: 
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...

Encadenar Múltiples Acciones

A partir de la versión 3.5.0 del Wrapper, es posible especificar más de una acción separándolas con un espacio o una coma. Cuando se especifica más de una acción, las acciones se ejecutarán en rápida sucesión en el orden especificado.

El siguiente ejemplo realizará un volcado de subproceso y luego reiniciará la JVM en respuesta a un mensaje "user error" detectado en la salida de la consola.

Ejemplo: 
wrapper.filter.trigger.1=User Error
wrapper.filter.action.1=DUMP,RESTART
Ejemplo de Salida del Wrapper: 
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...

Coincidencia Con Excepciones

En muchos casos, puede que quiera escribir alguna lógica para que se active a partir de un fragmento de texto, y luego descubrir que, en determinados contextos, querrá ignorarlos. El disparador se procesará en el orden de "<n>". Una vez encontrada una coincidencia, se ignorarán todas las demás. Esto permite configurar excepciones de coincidencia.

En este ejemplo, queremos activar todas las instancias de la palabra "Error" y reiniciar la JVM excepto cuando se encuentre en "IgnoreError".

Ejemplo: 
wrapper.filter.trigger.1=IgnoreError
wrapper.filter.action.1=NONE
wrapper.filter.trigger.2=Error
wrapper.filter.action.2=RESTART
Ejemplo de Salida del Wrapper: 
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...

Detección de OutOfMemoryError

NOTA

A partir de la versión 3.5.16 del Wrapper, se actualizó la plantilla del archivo de configuración predeterminado del Wrapper para que un reinicio debido a un filtro coincidente ya no se active de manera predeterminada si el usuario habilita la salida -verbose:class.

Al juntar todo esto, podemos crear un filtro para detectar cada vez que se lanza un OutOfMemoryError en un seguimiento de pila.

La forma más sencilla de hacerlo es la siguiente:

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

Esto puede tener el problema de que si el nombre de la clase se muestra en cualquier otra ubicación inesperada, se podría provocar un reinicio no deseado. Un ejemplo de esto es cuando el argumento -XX:+PrintClassHistogram se ha pasado a la JVM, Java generará un histograma muy útil de todas las clases cargadas, mostrando cuántas instancias hay actualmente en la memoria. Cuando Java genera el recuento para la clase OutOfMemoryError, el disparador anterior hará que la JVM se reinicie.

Ejemplo: 
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

Para solucionar este problema, es posible configurar excepciones. Sin embargo, si sabemos que queremos que la clase OutOfMemoryError solo se active cuando se muestre en un seguimiento de pila, podemos usar comodines para generar un patrón más específico.

Ejemplo: 
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.
Ejemplo de Salida del Wrapper: 
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...

Sin embargo, todavía existe un caso en el que se puede obtener un falso positivo. Si el usuario imprime la configuración completa del Wrapper, por ejemplo, verá una salida como la siguiente:

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

Por supuesto, esto no es deseable. Puede evitarlo haciendo una coincidencia de texto simple en el mismo texto SIN comodines habilitados, de la siguiente manera:

Ejemplo: 
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.