Compile-Time Automatic Instrumentation for Go Applications: Principles, Modular Extensions, and Practical Usage

In Go development, despite the language's high performance, developers often face significant cost and technical challenges when implementing application monitoring and service governance, especially in heterogeneous systems where manual code changes are cumbersome.

To address this, the Alibaba Cloud ARMS team, the compiler team, and the MSE team jointly released an open‑source compile‑time automatic instrumentation technique for Go that requires no source code modifications; developers simply replace the go build command with a custom build command to obtain full monitoring and governance capabilities.

The open‑source version supports 16 mainstream frameworks (38 in the commercial version) and offers a modular instrumentation extension that allows users to inject custom code into any target function via a simple JSON configuration, achieving fine‑grained control, monitoring, governance, and security without altering the original repository.

Preprocess step : The tool reads a user‑provided rule.json file that specifies which functions in which libraries should receive custom hooks. A typical configuration looks like:

[{ "ImportPath": "google.golang.org/grpc", "Function": "NewClient", "OnEnter": "grpcNewClientOnEnter", "OnExit": "grpcNewClientOnExit", "Path": "/path/to/my/code" }]

During preprocessing, the tool analyzes third‑party dependencies, matches them against the rules, and prepares any additional dependencies before the normal compilation pipeline.

Code injection step : Before the standard six compilation phases, two extra phases—Preprocess and Instrument—are inserted. The tool injects trampoline code at the specified entry points, which forwards execution to the user‑defined hooks (e.g., grpcNewClientOnEnter and grpcNewClientOnExit ) while performing AST‑level optimizations to keep overhead minimal.

Usage Example 1 – Recording HTTP request/response headers

Hook code ( hook.go ):

package hook

import (
    "encoding/json"
    "fmt"
    "github.com/alibaba/opentelemetry-go-auto-instrumentation/pkg/api"
    "net/http"
)

func httpClientEnterHook(call api.CallContext, t *http.Transport, req *http.Request) {
    header, _ := json.Marshal(req.Header)
    fmt.Println("request header is ", string(header))
}

func httpClientExitHook(call api.CallContext, res *http.Response, err error) {
    header, _ := json.Marshal(res.Header)
    fmt.Println("response header is ", string(header))
}

Configuration ( conf.json ):

[{ "ImportPath":"net/http", "Function":"RoundTrip", "OnEnter":"httpClientEnterHook", "ReceiverType":"*Transport", "OnExit":"httpClientExitHook", "Path":"/path/to/hook" }]

Demo program ( main.go ):

package main

import (
    "context"
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)

func main() {
    req, _ := http.NewRequestWithContext(context.Background(), "GET", "http://www.aliyun.com", nil)
    req.Header.Set("otelbuild", "true")
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Running the program with ./otelbuild -rule=conf.json -- main.go prints the captured request and response headers, confirming successful injection.

Usage Example 2 – Replacing the standard library sort algorithm

Hook code ( hook.go ) implements a dual‑pivot quicksort and skips the original call:

package hook

import (
    "github.com/alibaba/opentelemetry-go-auto-instrumentation/pkg/api"
)

func partition(arr []int, low, high int) (int, int) { /* implementation omitted for brevity */ }

func dualPivotQuickSort(arr []int, low, high int) { /* implementation omitted for brevity */ }

func sortOnEnter(call api.CallContext, arr []int) {
    dualPivotQuickSort(arr, 0, len(arr)-1)
    call.SetSkipCall(true)
}

Configuration ( conf.json ):

[{ "ImportPath":"sort", "Function":"Ints", "OnEnter":"sortOnEnter", "Path":"/path/to/hook" }]

Demo program ( main.go ):

package main

import (
    "fmt"
    "sort"
)

func main() {
    arr := []int{6, 3, 7, 9, 4, 4}
    sort.Ints(arr)
    fmt.Printf("== %v\n", arr)
}

After building with ./otelbuild -rule=conf.json -- main.go , the output shows the array sorted by the custom dual‑pivot quicksort.

Usage Example 3 – Preventing SQL injection

Hook code ( hook.go ) checks queries for risky patterns:

package hook

import (
    "database/sql"
    "errors"
    "github.com/alibaba/opentelemetry-go-auto-instrumentation/pkg/api"
    "log"
    "strings"
)

func checkSqlInjection(query string) error {
    patterns := []string{"--", ";", "/*", " or ", " and ", "'"}
    for _, p := range patterns {
        if strings.Contains(strings.ToLower(query), p) {
            return errors.New("potential SQL injection detected")
        }
    }
    return nil
}

func sqlQueryOnEnter(call api.CallContext, db *sql.DB, query string, args ...interface{}) {
    if err := checkSqlInjection(query); err != nil {
        log.Fatalf("sqlQueryOnEnter %v", err)
    }
}

Configuration ( conf.json ):

[{ "ImportPath":"database/sql", "Function":"Query", "ReceiverType":"*DB", "OnEnter":"sqlQueryOnEnter", "Path":"/path/to/hook" }]

Demo program ( main.go ) intentionally injects a malicious query; when built with ./otelbuild -rule=conf.json -- main.go , the tool logs the injection detection.

Usage Example 4 – Adding traffic protection to gRPC client requests

Hook code ( hook.go ) adds a Sentinel‑Golang interceptor:

package hook

import (
    "context"
    "google.golang.org/grpc"
    sentinel "github.com/sentinel-golang/api"
    "github.com/sentinel-golang/core/base"
    pkgapi "github.com/alibaba/opentelemetry-go-auto-instrumentation/pkg/api"
)

func newClientOnEnter(call pkgapi.CallContext, target string, opts ...grpc.DialOption) {
    opts = append(opts, grpc.WithChainUnaryInterceptor(unaryClientInterceptor))
}

func unaryClientInterceptor(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
    entry, blockErr := sentinel.Entry(method, sentinel.WithResourceType(base.ResTypeRPC), sentinel.WithTrafficType(base.Outbound))
    defer func() { if entry != nil { entry.Exit() } }()
    if blockErr != nil { return blockErr }
    return invoker(ctx, method, req, reply, cc, opts...)
}

Configuration ( conf.json ):

[{ "ImportPath":"google.golang.org/grpc", "Function":"NewClient", "OnEnter":"newClientOnEnter", "Path":"/path/to/hook" }]

Demo program ( main.go ) creates a gRPC client and makes a request; after building with the otelbuild tool, the client automatically includes the traffic‑control interceptor.

Summary and Outlook

The compile‑time automatic instrumentation solves the tedious manual instrumentation problem in micro‑service monitoring, has been commercialized on Alibaba Cloud, and is now open‑sourced for the OpenTelemetry community, with potential applications in service governance, code auditing, application security, and debugging. The authors invite readers to try the commercial product and join community groups for further collaboration.