This project tracks offsets of fields inside of Go structs across versions.

This tracking is needed in order to create a stable eBPF based instrumentation.

Calculating offsets is accomplished by creating a binary file containing the relevant struct and analyzing its DWARF information.

The main.go file specifies all the tracking targets. Each tracking target has a name which can be either a fully qualified go module name or go for tracking parameters in the standard library.

For example, in order to track the URL field inside the net/http.Request struct in the Go standard library we register the following target:

target.New("go").
  FindOffsets([]*binary.DataMember{
    {
      StructName: "net/http.Request",
      Field:      "URL",
    },
  })

offsets-tracker writes all the tracked offsets into a file named offset_results.json. For example, here is the tracking of method field inside transport.Stream struct in the google.golang.org/grpc module:

{
  "name": "google.golang.org/grpc",
  "data_members": [
    {
      "struct": "google.golang.org/grpc/internal/transport.Stream",
      "field_name": "method",
      "offsets": [
        {
          "offset": 72,
          "version": "v1.0.2"
        },
        {
          "offset": 72,
          "version": "v1.0.3"
        },
        {
          "offset": 72,
          "version": "v1.0.4"
        },
        {
          "offset": 80,
          "version": "v1.3.0"
        },
        {
          "offset": 80,
          "version": "v1.4.0"
        },

By default, offsets-tracker finds availble versions by executing go list -versions <target-name>.

Unfortunately, Go standard library versions are not discoverable via go list. In order to discover Go versions, offsets-tracker can fetch the versions published at https://go.dev/dl. Fetching go.dev for discovering versions can be enabled by setting.FindVersionsBy(target.GoDevFileVersionsStrategy) when registering a new target.

offsets-tracker wraps every Go module version as a Go application that depends on that module. Those applications are the result of generating template files with the appropriate version.

In the case of the Go standard library, offsets-tracker downloads the published binary for the specified version.

offsets-tracker downloads and compiles every version found in the previous step by default. Some targets do not require support for very old versions. Add the following to limit the version scope:

minimunGoVersion, err := version.NewConstraint(">= 1.12")

target.New('go')
... 
VersionConstraint(&minimunGoVersion)

This project is currently in Alpha. Check out our issues section to learn more about improvements we're working on.

This project is licensed under the terms of the Apache 2.0 open source license. Please refer to LICENSE for the full terms.