|
1 | 1 | # Adding a new Plugin |
2 | 2 |
|
| 3 | +In the bonus part of the tutorial, we will be adding a new plugin that instruments every method for a service (both on the client-side and the server-side) to print a `Hello, SOSP` message to standard output every time a method is executed. |
| 4 | + |
| 5 | +We have provided the plugin implementation for instrumenting the server side. Your goal is to complete the implementation for instrumenting the client side. Once you have completed the plugin, we will then test out the newly completed plugin with the leaf application. |
| 6 | + |
| 7 | +## Instrumenting the Client Side |
| 8 | + |
| 9 | +To implement the client side portion of the plugin, you need to complete 3 steps: (i) Implementing a client-side template which will represent the modified code that will contain the instrumentation; (ii) Implementing the client IR node so that Blueprint's compiler can generate the modified code from the IR node; and (iii) Implementing the wiring API so that this plugin can be used in wiring specifications. |
| 10 | + |
| 11 | +### Implementing the client-side template |
| 12 | + |
| 13 | +To implement the client-side template, complete the template attributed to the variable `clientInstrumentTemplate` in [templates.go](./sosp_plugins/hellososp/templates.go) file. |
| 14 | + |
| 15 | +The template is generated using the `templateArgs` struct defined on lines 9-17 of the `templates.go` file. |
| 16 | + |
| 17 | +> Hint: Use the serverInstrumentTemplate as a guide for implementing the various steps in the clientInstrumentTemplate. |
| 18 | +
|
| 19 | +### Implementing the IR client node |
| 20 | + |
| 21 | +To implement the client-side IR node, complete the TODO list in the [ir_client.go](./sosp_plugins/hellososp/ir_client.go) file. |
| 22 | + |
| 23 | +We suggest first completing the implementation of the function `newHelloInstrumentClientWrapper` that constructs the IR Node as well as the implementation of the struct `HelloInstrumentClientWrapper` before finishing other TODOs. |
| 24 | + |
| 25 | +> Hint: Use the HelloInstrumentServerWrapper defined in [ir_server.go](./sosp_plugins/hellososp/ir_server.go) as a guide for implementing various steps in the serverInstrumentTemplate. |
| 26 | +
|
| 27 | +### Implementing the IR wiring |
| 28 | + |
| 29 | +To implement the IR wiring, complete the `AddHelloSOSPStatement` function in the [wiring.go](./sosp_plugins/hellososp/wiring.go) file. |
| 30 | + |
| 31 | +To complete this, you will need add the client-side wrapper to the client-side node chain of the desired service. Wrappers can be added to the node chains of the desired service as follows: |
| 32 | + |
| 33 | +```go |
| 34 | +import "github.com/blueprint-uservices/blueprint/blueprint/pkg/coreplugins/pointer" |
| 35 | + |
| 36 | +func addToChain(serviceName string, serverWrapper string, clientWrapper string) { |
| 37 | + // Get the pointer for the serviceName that has access |
| 38 | + ptr := pointer.GetPointer(spec, serviceName) |
| 39 | + serverNext := ptr.AddDstModifier(spec, serverWrapper) // Add serverWrapper to the server-side node chain |
| 40 | + clientNext := ptr.AddSrcModifier(spec, clientWrapper) // Add clientWrapper to the client-side node chain |
| 41 | + |
| 42 | + // Use serverNext to instantiate the IR node. |
| 43 | + |
| 44 | + // Use clientNext to instantiate the IR node. |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +Once you have added the client-side wrapper to the node chain, you must then use the return value `clientNext` which is the IR node that will be wrapped by the new IR Node. The following snippet shows how to add a new IR node to the wiring spec for the server side. |
| 49 | + |
| 50 | +```go |
| 51 | +spec.Define(wrapper_name, &HelloInstrumentServerWrapper{}, func(ns wiring.Namespace) (ir.IRNode, error) { |
| 52 | + // Get the IRNode that will be wrapped by HelloWrapper |
| 53 | + var server golang.Service |
| 54 | + if err := ns.Get(serverNext, &server); err != nil { |
| 55 | + return nil, blueprint.Errorf("Tutorial Plugin %s expected %s to be a golang.Service, but encountered %s", wrapper_name, serverNext, err) |
| 56 | + } |
| 57 | + |
| 58 | + // Instantiate the IRNode |
| 59 | + return newHelloInstrumentServerWrapper(wrapper_name, server) |
| 60 | + }) |
| 61 | +``` |
| 62 | + |
| 63 | +## Running Leaf application |
| 64 | + |
| 65 | +To run the leaf application with our new plugin, no extra code needs to be written. We have already provided a wiring specification that generates the implementation with our plugin. |
| 66 | + |
| 67 | +### Generating the application |
| 68 | + |
| 69 | +To generate the application, execute the following steps: |
| 70 | + |
| 71 | +```bash |
| 72 | +cd leaf/wiring |
| 73 | +go run main.go -w bonus -o build |
| 74 | +``` |
| 75 | + |
| 76 | +### Building the application |
| 77 | + |
| 78 | +We will use `docker compose` to build the containers and then eventually deploy them. |
| 79 | + |
| 80 | +To build the application, execute the following steps: |
| 81 | + |
| 82 | +```bash |
| 83 | +# Assuming you are in the leaf/wiring folder |
| 84 | +cd build/docker # Switch to the docker directory where the containers are |
| 85 | +cp ../../.env . # Copy the provided .env file from the wiring folder. Note that we are not using the generated .env file for simplicity. |
| 86 | +docker compose build # Build the containers |
| 87 | +``` |
| 88 | + |
| 89 | +> Note: executing docker commands may require sudo access |
| 90 | +
|
| 91 | +### Running the application |
| 92 | + |
| 93 | +To launch the built containers, execute the following command: |
| 94 | + |
| 95 | +```bash |
| 96 | +docker compose up -d |
| 97 | +``` |
| 98 | + |
| 99 | +### Testing the application |
| 100 | + |
| 101 | +To test the application, you can execute the following `curl` command: |
| 102 | + |
| 103 | +```bash |
| 104 | +curl http://localhost:12348/Hello?a=5 |
| 105 | +``` |
| 106 | + |
| 107 | +The Hello API simply returns a counter value indicating the number of previous requests processed. |
| 108 | + |
| 109 | +Thus, you should see the following output: |
| 110 | + |
| 111 | +```bash |
| 112 | +{"Ret0":0} |
| 113 | +``` |
| 114 | + |
| 115 | +On subsequent executions of the curl command, the counter will increase monotonically. |
| 116 | + |
| 117 | +### Checking logs |
| 118 | + |
| 119 | +To check if the message was printed, open the docker logs for the non-leaf container. To do so, execute the following command: |
| 120 | + |
| 121 | +```bash |
| 122 | +docker logs nonleaf_ctr-1 |
| 123 | +``` |
| 124 | + |
| 125 | +### Stopping the application |
| 126 | + |
| 127 | +To stop the launched containers, execute the following command: |
| 128 | + |
| 129 | +```bash |
| 130 | +docker compose down |
| 131 | +``` |
| 132 | + |
| 133 | +## Conclusion |
| 134 | + |
| 135 | +Congratulations on finishing all parts of the SOSP tutorial! You are now officially a semi-pro in Blueprint fundamentals! |
0 commit comments