package com.hapiware.asm.log4j;
import java.lang.instrument.Instrumentation;
import java.util.regex.Pattern;
/**
* Adds a JMX support for log4j in the case where source code is not available or if source code
* does not wanted to be changed for some other reason. {@code Log4jJmxSupportAgentDelegate}
* adds the JMX support during the class loading.
*
*
* <h3>Requirements</h3>
* {@code Log4jJmxSupportAgentDelegate} requires:
* <ul>
* <li>{@code com.hapiware.agent.Agent}</li>
* <li>
* {@code om.hapiware.jmx.log4j.JmxLog4jLogger} (i.e. {@code log4j-jmx-support-x.x.x.jar}).
* This also requires log4j v. 1.2. or later.
* </li>
* <li>
* ASM 3.0 or later (see <a href="http://asm.ow2.org/" target="_blank">http://asm.ow2.org/</a>)
* </li>
* </ul>
*
*
* <h3>Notice</h3>
* Only static {@code org.apache.log4j.Logger} objects will have the JMX support. This should
* be sufficient but if log4j loggers have been used too creatively then the source code must
* be refined (maybe using {@link com.hapiware.jmx.log4j.JmxLog4jLogger} directly thus eliminating
* the need for {@code Log4jJmxSupportAgentDelegate} altogether).
*
*
* <h3>Configuring log4j JMX support agent</h3>
* The support agent is configured by using the following elements:
* <ul>
* <li>{@code <agent/delegate>}</li>
* <li>{@code <agent/classpath>}</li>
* <li>{@code <agent/filter>} (Optional but recommended)</li>
* </ul>
*
* For example:
* <xmp>
* <?xml version="1.0" encoding="UTF-8" ?>
* <agent>
* <delegate>com.hapiware.asm.log4j.Log4jJmxSupportAgentDelegate</delegate>
* <classpath>
* <entry>/users/me/agent/target/log4j-jmx-support-delegate-1.0.0.jar</entry>
* <entry>/usr/local/asm-3.1/lib/asm-3.1.jar</entry>
* </classpath>
*
* <!--
* A JMX support is added to every log4j logger for every class in com.hapiware.* package.
* -->
* <filter>
* <include>^com/hapiware/.+</include>
* </filter>
* </agent>
* </xmp>
*
*
* <h3>Remember classpath</h3>
* Remember to add a suitable version of {@code log4j-jmx-support-x.x.x.jar} to the classpath
* of the target JVM. This jar file is needed to add the JMX support for log4j.
*
*
* @author <a href="http://www.hapiware.com" target="_blank">hapi</a>
* @see com.hapiware.asm.agent.Agent
* @see com.hapiware.jmx.log4j.JmxLog4jLogger
*/
public class Log4jJmxSupportAgentDelegate
{
/**
* This method is called by the general agent {@code com.hapiware.agent.Agent} and
* is done before the main method call right after the JVM initialisation.
* <p>
* <b>Notice</b> the difference between this method and
* the {@code public static void premain(String, Instrumentation} method described in
* {@code java.lang.instrument} package.
*
* @param includePatterns
* A list of patterns to include classes for instrumentation.
*
* @param excludePatterns
* A list patterns to set classes not to be instrumented.
*
* @param config
* Not used.
*
* @param instrumentation
* See {@link java.lang.instrument.Instrumentation}
*
* @throws IllegalArgumentException
* If there is something wrong with the configuration file.
*
* @see java.lang.instrument
*/
public static void premain(
Pattern[] includePatterns,
Pattern[] excludePatterns,
Object config,
Instrumentation instrumentation
)
{
try {
instrumentation.addTransformer(
new Log4jJmxSupportTransformer(includePatterns, excludePatterns)
);
}
catch(Exception e)
{
System.err.println(
"Couldn't start the Log4jJmxSupport agent delegate due to an exception. "
+ e.getMessage()
);
e.printStackTrace();
}
}
}