mrproliu commented on code in PR #13: URL: https://github.com/apache/skywalking-go/pull/13#discussion_r1175191887
########## docs/en/concepts-and-designs/key-principles.md: ########## @@ -0,0 +1,174 @@ +# Key Principle + +Enhancing applications in hybrid compilation is very important for SkyWalking Go Agent. +In this section, I will delve deeper into several key technical points. + +## Method Interceptor + +Method interception is particularly important in SkyWalking Go, as it enables the creation of plugins. In SkyWalking Go, method interception mainly involves the following key points: + +1. **Finding Method**: Using `AST` to find method information in the target code to be enhanced. +2. **Modifying Methods**: Enhancing the specified methods and embedding interceptor code. +3. **Saving and Compiling**: Updating the modified files in the compilation arguments. + +### Finding Method + +When looking for methods, the SkyWalking Go Agent need to search according to the provided compilation arguments, which mainly include the following two parts: + +1. **Package information**: Based on the package name provided by the arguments, the Agent can find the specific plugin. +2 **Go files**: When a matching plugin is found, Agent can read the `.go` files and use `AST` to parse the method information contained in these files. When the method information matches the method information required by the plugin for interception, Agent can consider the method found. + +### Modifying Methods + +After finding the method, the SkyWalking Go Agent needs to modify the method implication and embed the interceptor code. + +#### Change Method Body + +When intercepting a method, the first thing to do is to modify the method and [embed the template code](../../../tools/go-agent/instrument/plugins/templates/method_inserts.tmpl). +This code segment includes two method executions: + +1. **Before method execution**: Pass in the current method's arguments, instances, and other information. +2. **After method execution**: Using the `defer` method, intercept the result parameters after the code execution is completed. + +Based on these two methods, the agent can intercept before and after method execution. + +In order not to affect the line of code execution, this code segment will only be executed in the **same line as the first statement in the method**. +This ensures that when an exception occurs in the framework code execution, the exact location can still be found without being affected by the enhanced code. + +#### Write Adapter File + +After the agent enhances the method body, it needs to implement the above two methods and write them into a single file, called the **adapter file**. These two methods will do the following: + +1. **Before method execution**: [Build by the template](../../../tools/go-agent/instrument/plugins/templates/method_intercept_before.tmpl). Build the context for before and after interception, and pass the parameter information during execution to the interceptor in each plugin. +2. **After method execution**: [Build by the template](../../../tools/go-agent/instrument/plugins/templates/method_intercept_after.tmpl). Pass the method return value to the interceptor and execute the method. + +#### Copy Files + +After completing the adapter file, the agent would perform the following copy operations: + +1. **Plugin Code**: Copy the Go files containing the interceptors in the plugin to the same level directory as the current framework. +2. **Plugin Development API Code**: Copy the operation APIs needed by the interceptors in the plugin to the same level directory as the current framework, such as `tracing`. + +After copying the files, they cannot be immediately added to the compilation parameters, because they may have the same name as the existing framework code. Therefore, we need to perform some rewriting operations, which include the following parts: + +1. **Types**: Rename created structures, interfaces, methods, and other types by adding a unified prefix. +2. **Static Methods**: Add a prefix to non-instance methods. Static methods do not need to be rewritten since they have already been processed in the types. +3. **Variables**: Add a prefix to global variables. It's not necessary to add a prefix to variables inside methods because they can ensure no conflicts would arise and are helpful for debugging. Review Comment: Sure, I have added the tracing API as an example. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
