loongsuite-go: compile-time OpenTelemetry instrumentation for Go

The instrumented application never changes

The core claim of the Loongsuite Go Agent is that no code changes are required in the target application, because the instrumentation happens at compile time. What you do instead is change one command. Where you would have run go build, you run otel go build, and the tool rewrites the program as it is compiled so that the resulting binary carries OpenTelemetry instrumentation. The instrumented program is still an ordinary Go binary, which is the property that matters operationally: there is no sidecar agent, no environment variable read at startup, and no proxy in the request path. The project's stated goal is an automatic solution for Golang applications that want to use OpenTelemetry to enable effective observability, and the mechanism it chose is a compiler front end rather than a runtime library. The dependency list explains how: github.com/dave/dst is present, and dst is a Go library for decoding and re-encoding syntax trees, which is exactly the tool you need to insert statements into a program's source without changing the source itself.

Go 1.25 is required on both the tool and the target

There is a hard version floor and it applies twice. The documentation marks it as important rather than as a note, and states that Go 1.25 or newer is required for both the tool and the instrumented application, with a pointer to a compatibility document for details. The module declaration in go.mod agrees, setting the go directive to 1.25.0. This matters more than a normal minimum version requirement, because the tool is a build-time participant. It has to be able to read and rewrite the syntax of the language version your program is written in, and the compatibility file is the place to look when a program targets a newer or older language level than the tool expects. A team that has not moved past Go 1.24 cannot use this agent at all, and a team on the newest Go release should read the compatibility document before assuming the tool tracks the language automatically.

Installing the tool is a curl, a sudo, or a make

Three routes are documented and they are conventional for a Go command line tool. Prebuilt binaries are published per platform, with separate downloads for Linux amd64 and arm64, macOS amd64 and arm64, and Windows amd64. On Linux and macOS there is a shell script that installs the tool to /usr/local/bin/otel by default:

$ curl -fsSL https://cdn.jsdelivr.net/gh/alibaba/loongsuite-go@main/install.sh | sudo bash

Building from source uses the Makefile in the repository root, and the two targets are separated so you can compile without touching the system:

$ make         # build only
$ make install # build and install

Prefixing the build is the entire user interface

Once the tool is on the path, the workflow is a single prefix. The documentation shows the plain build first, then a build with an explicit output path, and then a build with the compiler flag for printing escape analysis, which suggests the tool forwards arbitrary arguments to the Go toolchain rather than only supporting a fixed command set:

$ otel go build
$ otel go build -o app cmd/app
$ otel go build -gcflags="-m" cmd/app

Before any of that, the tool reports its own version, which is the quickest way to confirm the binary on your path is the one you installed:

$ # You may use "otel-linux-amd64" instead of "otel"
$ otel version

The detailed options live in a separate Usage document under docs/user, so the tool is not limited to the prefix shown here.

Library support is a table of version ranges, not a promise

The list of instrumented libraries is the part of this project that will age fastest, and the project presents it that way, as a table with a minimum version and a maximum version per library. Many entries have no maximum at all, marked with a dash, and the ones that do have upper bounds show them: gin runs from v1.7.0 to v1.10.2, gorm from v1.22.0 to v1.25.10, fiber from v2.43.0 to v2.53.0, and elasticsearch from v8.4.0 to v8.15.1. Others are open ended, including database/sql, grpc, kafka style clients such as franz-go, hertz, kitex, echo, fasthttp and dubbo-go. The upper bounds are the interesting part, because they tell you that a dependency upgrade can silently take you outside the range the agent was written against. When a library you use is absent from the table, or present but outside its range, the honest expectation is that the agent will not add the right instrumentation for it, and no amount of configuration in the Usage document will change that.

The examples double as a regression suite

The repository carries an example directory that is worth reading as a map of what the tool actually does. There is a demo for end to end tracing and metrics, a log example for auto-instrumentation of go.uber.org/zap logging, a nethttp example for HTTP monitoring with request and response instrumentation, a benchmark directory for performance testing and overhead measurement, and a sqlinject example described as custom code injection for SQL injection detection. There are also framework-specific examples for Kratos and for Kafka consumer message monitoring, plus examples for gRPC, eino, genai and openai. The sql injection example is the most interesting of the set, because it shows the tool injecting code that is not instrumentation in the telemetry sense at all, which tells you the mechanism generalises to arbitrary source transformation. The benchmark directory is the one to look at if you care about what the compile-time approach costs at runtime.

The toolchain wraps the Go compiler rather than sitting beside it

The build system in this repository shows how much machinery sits behind the otel command. The Makefile derives the main version from the git tags with git describe, detects the current operating system and normalises the architecture, mapping aarch64 to arm64 and the older arm variants to arm, and then defines one output binary name per platform pair, all prefixed with otel. The version string is assembled from the tag and the short commit hash and then injected into the binary with linker flags, one of which sets the tool config ToolVersion and another which sets a version tag in the instrumentation API package. The API itself is generated rather than written: the Makefile keeps a source file in pkg/api and a template in tool/instrument, and the build syncs one from the other, which is how the instrumented code and the agent stay in step. The repository also carries a golangci configuration for linting and a .codeconv configuration, both signs that the code style is enforced automatically.

Apache-2.0 and a monthly release cadence

The licence field on the repository says Apache-2.0, and the build file carries the standard Apache License 2.0 header, so redistribution and modification are permitted under that licence with its notice and patent terms intact. The project also links to a commercial edition for users who want a managed version of the monitoring, which is worth understanding before you build a dependency on the open source tool. On the release side the cadence is regular: v1.15.0 on 2026-09-28, v1.14.0 on 2026-08-25 and v1.13.0 on 2026-07-14, one minor version a month across three consecutive months. The last push was on 2026-10-19, so work is landing between releases rather than only at release time. The practical consequence for an adopter is that a monthly upgrade path exists, and that the supported library table is likely to move with it, which is another argument for reading the table again at each bump.

Editorial conclusion

loongsuite-go fits a Go team that wants OpenTelemetry traces and metrics without editing application code and without adding OpenTelemetry imports to every handler, and that can accept a compile-time tool in its build. It does not fit a team still on Go 1.24, a team that needs instrumentation for a library outside the supported list, or anyone who needs to trace a program they did not compile. Before adopting it, check your Go version against the 1.25 requirement, confirm the libraries you depend on appear in the supported list at a version inside the stated range, and read the Usage document before changing CI, because the tool wraps the compiler rather than sitting beside it.

Frequently asked questions

Official sources

1. alibaba/loongsuite-go on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases