如何添加新的插桩规则

2025-01-20

1. 创建规则

我们将通过一个示例演示如何为新软件包注入代码。

下面是如何将日志注入 os.Setenv() 函数，以跟踪键和值的使用情况。

首先，在新目录中创建并初始化一个 Go 模块：

$ mkdir mysetenv && cd mysetenv
$ go mod init mysetenv

接下来，在 mysetenv 目录中创建 hook.go 文件：

package mysetenv

import (
  "fmt"

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

func onEnterSetenv(call api.CallContext, key, value string) {
  fmt.Printf("Setting environment variable %s to %s", key, value)
}

运行 go mod tidy 下载依赖项。这将设置钩子代码。

2. 注册规则

创建 rule.json 文件，指定目标函数和钩子代码：

[
  {
    "ImportPath": "os",
    "Function": "Setenv",
    "OnEnter": "onEnterSetenv",
    "Path": "/path/to/mysetenv"
  }
]

ImportPath: 包含函数的包的导入路径
Function: 需要进行代码插桩的函数名
OnEnter: 插桩的代码
Path: 包含插桩代码的目录名

还可以指定其他字段，如 OnExit 和 Order。详情请参考文档。

3. 验证规则

下面通过一个简单的程序来验证相关规则是否生效：

$ mkdir setenv-demo && cd setenv-demo
$ go mod init setenv-demo
$ cat <<EOF > main.go
package main
import "os"
func main() {
    os.Setenv("hello", "world")
}
EOF
$ ~/otel -rule=rule.json go build main.go
$ ./main
Setting environment variable hello to world%

当调用 os.Setenv() 时，输出会显示信息，确认代码注入成功。

本示例未涉及许多高级功能，更多信息可参考 pkg/rules 目录中的现有规则。