make apm-toolkit-trace support a a programmatic interface #6625
Description
Please answer these questions before submitting your issue.
- Why do you submit this issue?
- Question or discussion
- Bug
- Requirement
- Feature or performance improvement
Requirement
I want to pragmatically instrument Java code. There are possible two ways to do it.
gRPC API
This approach uses gPRC API to report segments to the OAP server. This approach is similar to go2sky. But there is a problem with it. The spans create by gPRC API can‘t be related to the spans created by the Java agent. Consider the following example:
@GetMapping("/greeting")
public String greeting() {
foo();
return "hello";
}
private void foo() {
// Create a span B.
// Report a segment which contains span B to the OAP server with gRPC
}Java agent creates an entry span A for the greeting method A. And a segment that contains span A is reported to the OAP server by Java agent. There will be no ChildOf relation created between span A and span B since Java agent and gRPC API do the instrument separately. In one word, this approach does not integrate well with the automatic instrument by Java agent.
apm-toolkit-trace
apm-toolkit-trace uses Java annotations to create tracing data such as span, log, and tag. For example, we can use @Trace annotation to create a span for bar method:
@Trace
public void bar() {
}The problem is that I can't decide whether to create a span for bar at runtime. For example, I want to disable span creation for bar method by default. After I turn on some flag, I want to create spans for the invocation of the method bar.
So the existing approaches do not solve my problem. I want to implement the following feature by extending apm-toolkit-trace module. My idea is to add the following APIs to apm-toolkit-trace module (This API list is incomplete. If this design makes sense, I will make a complete API list for review):
- createLoalSpan
- createEntrySpan
- createExitSpan
- stopSpan
The above methods essentially do the same thing as the aforementioned annotations. For example, createLoalSpan and stopSpan can do the same thing as @Trace annotation. In summary, my idea is to provide a programmatic interface for the functionalities which have existed in apm-toolkit-trace module.