ttl2-compatible/src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java
package com.alibaba.ttl.threadpool.agent;
import com.alibaba.ttl.threadpool.agent.logging.Logger;
import com.alibaba.ttl.threadpool.agent.transformlet.TtlTransformlet;
import com.alibaba.ttl.threadpool.agent.transformlet.internal.ForkJoinTtlTransformlet;
import com.alibaba.ttl.threadpool.agent.transformlet.internal.JdkExecutorTtlTransformlet;
import com.alibaba.ttl.threadpool.agent.transformlet.internal.TimerTaskTtlTransformlet;
import com.alibaba.ttl.threadpool.agent.transformlet.internal.PriorityBlockingQueueTtlTransformlet;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import java.lang.instrument.ClassFileTransformer;
import java.lang.instrument.Instrumentation;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
/**
* TTL Java Agent.
*
* <h2>The configuration for TTL agent</h2>
* <p>
* Configure TTL agent via {@code -D property}({@link System#getProperties()}) or TTL agent arguments.
* <ol>
* <li>{@code -D property} config format is: {@code -Dkey1=v2 -Dkey2=v2}</li>
* <li>TTL agent arguments config format is {@code key1:v1,key2:v2}.<br>
* separate key-value pairs by {@code char ,}, and separate key-value by {@code char :}.<br></li>
* </ol>
* <B><I>NOTE about the config sources and the precedence:</I></B><br>
* <ol>
* <li>Read {@code -D property}({@link System#getProperties()}) first.</li>
* <li>if no {@code -D property} configured(including empty property value configured by {@code -Dkey1}/{@code -Dkey1=}), read TTL Agent argument configuration.</li>
* </ol>
* Below is available TTL agent configuration keys.
*
* <h3>Configuration key: Log Type</h3>
* <p>
* The log type of TTL Java Agent is configured by key {@code ttl.agent.logger}. Since version {@code 2.6.0}.
*
* <ul>
* <li>{@code ttl.agent.logger : STDERR}<br>
* only log to {@code stderr} when error.
* This is <b>default</b>, when no/unrecognized configuration for key {@code ttl.agent.logger}.</li>
* <li>{@code ttl.agent.logger : STDOUT}<br>
* Log to {@code stdout}, more info than {@code ttl.agent.logger:STDERR}; This is needed when developing.</li>
* </ul>
* <p>
* Configuration example:
*
* <ol>
* <li>{@code -Dttl.agent.logger=STDOUT}</li>
* <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.logger:STDOUT}</li>
* </ol>
*
* <h3>Configuration key: Disable inheritable for thread pool</h3>
* <p>
* Enable "disable inheritable" for thread pool, configured by key {@code ttl.agent.disable.inheritable.for.thread.pool}.
* When no configuration for this key, default is {@code false}(aka. do <b>NOT</b> disable inheritable). Since version {@code 2.10.1}.
*
* <ul>
* <li>rewrite the {@link java.util.concurrent.ThreadFactory} constructor parameter
* of {@link java.util.concurrent.ThreadPoolExecutor}
* to {@link com.alibaba.ttl.threadpool.DisableInheritableThreadFactory}
* by util method {@link com.alibaba.ttl.threadpool.TtlExecutors#getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory) getDisableInheritableThreadFactory}.
* </li>
* <li>rewrite the {@link java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory} constructor parameter
* of {@link java.util.concurrent.ForkJoinPool}
* to {@link com.alibaba.ttl.threadpool.DisableInheritableForkJoinWorkerThreadFactory}
* by util method {@link com.alibaba.ttl.threadpool.TtlForkJoinPoolHelper#getDisableInheritableForkJoinWorkerThreadFactory(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory) getDisableInheritableForkJoinWorkerThreadFactory}.
* </li>
* </ul>
* More info about "disable inheritable" see {@link com.alibaba.ttl.TransmittableThreadLocal}.
* <p>
* Configuration example:
*
* <ol>
* <li>{@code -Dttl.agent.disable.inheritable.for.thread.pool=true}</li>
* <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.disable.inheritable.for.thread.pool:true}</li>
* </ol>
*
* <h3>Configuration key: Enable TimerTask class decoration</h3>
* <p>
* Enable TimerTask class decoration is configured by key {@code ttl.agent.enable.timer.task}.
* Since version {@code 2.7.0}.
* <p>
* When no configuration for this key, default is {@code true}(aka. <b>enabled</b>).<br>
* <b><i>Note</i></b>: Since version {@code 2.11.2} the default value is {@code true}(enable TimerTask class decoration);
* Before version {@code 2.11.1} default value is {@code false}.
* <p>
* Configuration example:
*
* <ol>
* <li>{@code -Dttl.agent.enable.timer.task=false}</li>
* <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false}</li>
* </ol>
*
* <h3>Configuration key: logging the transform class received by TTL Agent</h3>
* <p>
* Enable logging the transform class received by TTL Agent by key {@code ttl.agent.log.class.transform},
* default is {@code false}(aka. do <b>NOT</b> logging the transform class received by TTL Agent).
* Since version {@code 3.0.0}.
* <p>
* Configuration example:
*
* <ol>
* <li>{@code -Dttl.agent.log.class.transform=true}</li>
* <li>{@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.log.class.transform:true}</li>
* </ol>
*
* <h3>Multi key configuration example</h3>
* <p>
* For {@code -D property} config, simply specify multiply {@code -D property}, example:<br>
* {@code -Dttl.agent.logger=STDOUT -Dttl.agent.disable.inheritable.for.thread.pool=true}
* <p>
* For TTL agent arguments config, example:<br>
* {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.logger:STDOUT,ttl.agent.disable.inheritable.for.thread.pool:true}
*
* <h2>About boot classpath for TTL agent</h2>
* <p>
* <b><i>NOTE:</i></b> Since {@code v2.6.0}, TTL agent jar will auto add self to {@code boot classpath}.<br>
* But you <b>should <i>NOT</i></b> modify the downloaded TTL jar file name in the maven repo(eg: {@code transmittable-thread-local-2.x.y.jar}).<br>
* if you modified the downloaded TTL agent jar file name(eg: {@code ttl-foo-name-changed.jar}),
* you must add TTL agent jar to {@code boot classpath} manually
* by java option {@code -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar}.
* <p>
* The implementation of auto adding self agent jar to {@code boot classpath} use
* the {@code Boot-Class-Path} property of manifest file({@code META-INF/MANIFEST.MF}) in the TTL Java Agent Jar:
*
* <blockquote>
* <dl>
* <dt>Boot-Class-Path</dt>
* <dd>
* A list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries (commonly referred to as JAR or zip libraries on many platforms).
* These paths are searched by the bootstrap class loader after the platform specific mechanisms of locating a class have failed. Paths are searched in the order listed.
* </dd>
* </dl>
* </blockquote>
* <p>
* More info about {@code Boot-Class-Path} see
* <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.instrument/java/lang/instrument/package-summary.html">The mechanism for instrumentation</a>.
*
* @author Jerry Lee (oldratlee at gmail dot com)
* @see Instrumentation
* @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.instrument/java/lang/instrument/package-summary.html">The mechanism for instrumentation</a>
* @see <a href="https://docs.oracle.com/en/java/javase/21/docs/specs/jar/jar.html#jar-manifest">JAR File Specification - JAR Manifest</a>
* @see <a href="https://docs.oracle.com/javase/tutorial/deployment/jar/manifestindex.html">Working with Manifest Files - The Java™ Tutorials</a>
* @see com.alibaba.ttl.TransmittableThreadLocal
* @see java.util.concurrent.ThreadPoolExecutor
* @see java.util.concurrent.ScheduledThreadPoolExecutor
* @see java.util.concurrent.ForkJoinPool
* @see java.util.TimerTask
* @since 0.9.0
*/
public final class TtlAgent {
/**
* the TTL agent configuration key: Log Type
*
* @see TtlAgent
* @since 3.0.0
*/
public static final String TTL_AGENT_LOGGER_KEY = "ttl.agent.logger";
/**
* the TTL agent configuration key: Disable inheritable for thread pool
*
* @see TtlAgent
* @since 3.0.0
*/
public static final String TTL_AGENT_DISABLE_INHERITABLE_FOR_THREAD_POOL_KEY = "ttl.agent.disable.inheritable.for.thread.pool";
/**
* the TTL agent configuration key: Enable TimerTask class decoration
*
* @see TtlAgent
* @since 3.0.0
*/
public static final String TTL_AGENT_ENABLE_TIMER_TASK_KEY = "ttl.agent.enable.timer.task";
/**
* the TTL agent configuration key: logging the transform class received by TTL Agent
*
* @see TtlAgent
* @since 3.0.0
*/
public static final String TTL_AGENT_LOG_CLASS_TRANSFORM_KEY = "ttl.agent.log.class.transform";
// ======== TTL Agent internal States ========
private static volatile Map<String, String> kvs;
private static volatile boolean ttlAgentLoaded = false;
/**
* Entrance method of TTL Java Agent.
*
* @see TtlAgent
*/
public static void premain(final String agentArgs, @NonNull final Instrumentation inst) {
kvs = TtlAgentHelper.splitCommaColonStringToKV(agentArgs);
Logger.setLoggerImplType(getLoggerType());
final Logger logger = Logger.getLogger(TtlAgent.class);
try {
logger.info("[TtlAgent.premain] begin, agentArgs: " + agentArgs + ", Instrumentation: " + inst);
logger.info(logTtlAgentConfig());
final List<TtlTransformlet> transformletList = new ArrayList<>();
transformletList.add(new JdkExecutorTtlTransformlet());
transformletList.add(new PriorityBlockingQueueTtlTransformlet());
transformletList.add(new ForkJoinTtlTransformlet());
if (isEnableTimerTask()) transformletList.add(new TimerTaskTtlTransformlet());
final ClassFileTransformer transformer = new TtlTransformer(transformletList, isLogClassTransform());
inst.addTransformer(transformer, true);
logger.info("[TtlAgent.premain] add Transformer " + transformer.getClass().getName() + " success");
logger.info("[TtlAgent.premain] end");
ttlAgentLoaded = true;
} catch (Exception e) {
String msg = "Fail to load TtlAgent , cause: " + e.toString();
logger.error(msg, e);
throw new IllegalStateException(msg, e);
}
}
private static String logTtlAgentConfig() {
return "TTL Agent configurations:"
+ "\n " + TTL_AGENT_LOGGER_KEY + "=" + getLoggerType()
+ "\n " + TTL_AGENT_LOG_CLASS_TRANSFORM_KEY + "=" + isLogClassTransform()
+ "\n " + TTL_AGENT_DISABLE_INHERITABLE_FOR_THREAD_POOL_KEY + "=" + isDisableInheritableForThreadPool()
+ "\n " + TTL_AGENT_ENABLE_TIMER_TASK_KEY + "=" + isEnableTimerTask();
}
/**
* Whether TTL agent is loaded.
*
* @since 2.9.0
*/
public static boolean isTtlAgentLoaded() {
return ttlAgentLoaded;
}
/**
* Whether disable inheritable for thread pool is enhanced by ttl agent, check {@link #isTtlAgentLoaded()} first.
* <p>
* Same as {@code isBooleanOptionSet(TTL_AGENT_DISABLE_INHERITABLE_FOR_THREAD_POOL_KEY)}.
*
* @see com.alibaba.ttl.threadpool.TtlExecutors#getDefaultDisableInheritableThreadFactory()
* @see com.alibaba.ttl.threadpool.TtlExecutors#getDisableInheritableThreadFactory(java.util.concurrent.ThreadFactory)
* @see com.alibaba.ttl.threadpool.DisableInheritableThreadFactory
* @see com.alibaba.ttl.threadpool.TtlForkJoinPoolHelper#getDefaultDisableInheritableForkJoinWorkerThreadFactory()
* @see com.alibaba.ttl.threadpool.TtlForkJoinPoolHelper#getDisableInheritableForkJoinWorkerThreadFactory(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory)
* @see com.alibaba.ttl.threadpool.DisableInheritableForkJoinWorkerThreadFactory
* @see com.alibaba.ttl.TransmittableThreadLocal
* @see TtlAgent
* @see #isBooleanOptionSet(String)
* @see #TTL_AGENT_DISABLE_INHERITABLE_FOR_THREAD_POOL_KEY
* @since 2.10.1
*/
public static boolean isDisableInheritableForThreadPool() {
return isBooleanOptionSet(TTL_AGENT_DISABLE_INHERITABLE_FOR_THREAD_POOL_KEY);
}
/**
* Whether timer task is enhanced by ttl agent, check {@link #isTtlAgentLoaded()} first.
* <p>
* Same as {@code isBooleanOptionSet(TTL_AGENT_ENABLE_TIMER_TASK_KEY, true)}.
*
* @see java.util.Timer
* @see java.util.TimerTask
* @see TtlAgent
* @see #isBooleanOptionSet(String, boolean)
* @see #TTL_AGENT_ENABLE_TIMER_TASK_KEY
* @since 2.10.1
*/
public static boolean isEnableTimerTask() {
return isBooleanOptionSet(TTL_AGENT_ENABLE_TIMER_TASK_KEY, true);
}
/**
* Whether logging the transform class received by {@link TtlAgent}.
* <p>
* Same as {@code isBooleanOptionSet(TTL_AGENT_LOG_CLASS_TRANSFORM_KEY)}.
*
* @see TtlAgent
* @see #isBooleanOptionSet(String)
* @see #TTL_AGENT_LOG_CLASS_TRANSFORM_KEY
* @since 3.0.0
*/
public static boolean isLogClassTransform() {
return isBooleanOptionSet(TTL_AGENT_LOG_CLASS_TRANSFORM_KEY);
}
/**
* Get the TTL Agent Log type.
* <p>
* Same as {@code getStringOptionValue(TTL_AGENT_LOGGER_KEY, Logger.STDERR)}.
*
* @see Logger
* @see Logger#STDERR
* @see Logger#STDOUT
* @see TtlAgent
* @see #getStringOptionValue(String, String)
* @see #TTL_AGENT_LOGGER_KEY
* @since 3.0.0
*/
@NonNull
public static String getLoggerType() {
return getStringOptionValue(TTL_AGENT_LOGGER_KEY, Logger.STDERR);
}
// ======== Generic Option Getters ========
/**
* Generic Option Getters for {@code boolean type} option.
* <p>
* Same as {@code isBooleanOptionSet(key, false)}.
*
* @see #isBooleanOptionSet(String, boolean)
* @see TtlAgent
* @since 3.0.0
*/
public static boolean isBooleanOptionSet(@NonNull String key) {
return isBooleanOptionSet(key, false);
}
/**
* Generic Option Getters for {@code boolean type} option.
*
* @see TtlAgent
* @since 3.0.0
*/
public static boolean isBooleanOptionSet(@NonNull String key, boolean defaultValueIfKeyAbsent) {
return TtlAgentHelper.isBooleanOptionSet(kvs, key, defaultValueIfKeyAbsent);
}
/**
* Generic Option Getters for {@code string type} option.
* <p>
* usage example:
* <p>
* if {@code -Dttl.agent.logger=STDOUT} or
* TTL Agent configuration is {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.logger:STDOUT},
* {@code getOptionValue("ttl.agent.logger")} return {@code STDOUT}.
*
* @see TtlAgent
* @since 3.0.0
*/
@NonNull
public static String getStringOptionValue(@NonNull String key, @NonNull String defaultValue) {
return TtlAgentHelper.getStringOptionValue(kvs, key, defaultValue);
}
/**
* Generic Option Getters for {@code string list type} option.
* <p>
* TTL configuration use {@code |} to separate items.
* <p>
* usage example:<br>
* if {@code -Dfoo.list=v1|v2|v3} or
* TTL Agent configuration is {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=foo.list:v1|v2|v3},
* {@code getOptionValue("foo.list")} return {@code [v1, v2, v3]}.
*
* @see TtlAgent
*/
@NonNull
static List<String> getOptionStringListValues(@NonNull String key) {
return TtlAgentHelper.getOptionStringListValues(kvs, key);
}
@SuppressFBWarnings("CT_CONSTRUCTOR_THROW")
private TtlAgent() {
throw new InstantiationError("Must not instantiate this class");
}
}