Proposal: easeagent plugins

[tg123]

Proposal: easeagent plugins

Abstract

• Move built-in TracePoint to a separate jar which can be loaded by easeagent at JVM starts.

• Provide tools for users to build their own TracePoint jars to extend easeagent.

  Inspired by btracec

Background

easeagent now has built-in JDK transformer backed TracePoints below

• com.megaease.easeagent.requests.GenCaptureTrace
• com.megaease.easeagent.requests.GenCaptureExecuteSql
• com.megaease.easeagent.requests.GenCaptureHttpRequest
• com.megaease.easeagent.zipkin.GenTraceHttpServlet
• com.megaease.easeagent.zipkin.GenTraceHttpClient
• com.megaease.easeagent.zipkin.GenTraceRestTemplate
• com.megaease.easeagent.zipkin.GenTraceJedis
• com.megaease.easeagent.zipkin.GenTraceJdbcStatement
• com.megaease.easeagent.metrics.GenMeasureJdbcStatement
• com.megaease.easeagent.metrics.GenMeasureJdbcGetConnection
• com.megaease.easeagent.metrics.GenMeasureHttpRequest
• com.megaease.easeagent.metrics.GenCaptureCaller

The TracePoints are generated by project gen along with template-like projects requests, zipkin and metrics.

Though easeagent have config files, it is still difficult for end users to customize or add new futures.
The proposal is to convert existing TracePoint code into script and consumed by a compiler which would yield JDK transformer .class. The generated transformer will be packed into a plugin format for easeagent

Details

easeagentc (was gen) and TracePoint script

The plugin compiler, aka easeagentc, should take some script as input, and yield plugin as output.

The script

The first version of the script spec might be the same as current TracePoint java file which implement com.megaease.easeagent.core.Transformation.

For example, current TraceHttpClient.java will be compiled by easeagentc into a plugin.

@Injection.Provider(Provider.class)
public abstract class TraceHttpClient implements Transformation {
    @Override
    public <T extends Definition> T define(Definition<T> def) {
        return def.type(hasSuperType(named("org.apache.http.impl.client.CloseableHttpClient")))
                  .transform(execute(ElementMatchers.<MethodDescription>named("doExecute")))
                  .end();
    }

    // ...
}

The better script spec will be discussed in a separate proposal later.
The new script might have Groovy or JVM based scripts support, and easeagent DSL for easier plugin coding.

Dependencies

plugin may or may not have dependencies. easeagentc should pack dependencies into the plugin file.

The dependencies can be described in a pom.xml or build.gradle

Plugin format and its loader

plugin Format

The format of plugin file can be a jar with futures below

• libs: it should carry all dependency jars with it.
• metadata: it should contain the info for easeagent to load and search for all the transformers

Dynamic load and plugin config

easeagent should support

• search and load all visible plugins dynamically
• plugin may have a config helper to load config provided by easeagent which may defined in a config file

Universe Reporting Stub (optional)

For performance purpose, the easeagent runtime could have reporting stub for plugin to report their data.
The stub should handle data in a ring buffer like cache and provide multiple interfaces to emit data to outside world.

In that case, the plugins may have less dependencies and fewer class conflict issues.

The design idea of the report stub is from ETW

[zhao-kun]

We will work on it. A design document will be drafted by team members.
Welcome, you guys interesting in this topic to join the discussion and attend our design review in the future if free.

(@zhongl)

[Oseenix]

support plugins from v2.0.0