apache/skywalking-go: Go auto-instrumentation without editing your code

The problem SkyWalking Go targets: Go has no runtime agent story

Most APM agents attach at runtime. A Java agent is a jar passed on the command line, a .NET agent is a profiler DLL, and both can be dropped into an existing deployment without a rebuild. Go does not offer that. The binary is statically compiled, there is no stable runtime hook for injecting instrumentation after the fact, and the community has settled on compile-time instrumentation as the practical answer. SkyWalking Go takes that route. It is the Golang auto-instrument Agent for Apache SkyWalking, and the README frames it as providing native tracing, metrics and logging abilities for Golang projects. The audience is teams already running a SkyWalking backend who want Go services to appear in the same topology as their Java or Python services. The second audience is smaller but real: teams who want distributed tracing in Go and are willing to accept a build-time dependency to avoid hand-writing spans around every HTTP handler and database call.

How the agent hooks a Go build through toolexec

The repository layout tells most of the story. There is an agent/ directory holding the injected runtime, a plugins/ directory holding per-library instrumentation, a toolkit/ directory for shared helpers, and a tools/ directory whose Makefile target tools/go-agent builds the agent binary. The Dockerfile shows the intended distribution shape: it builds with a golang:1.24 builder image, runs make -C tools/go-agent linux, and copies the resulting bin/skywalking-go-agent*linux* file into /usr/local/bin/skywalking-go-agent in a base Go image. That binary is what the Go toolchain calls. The RELATED SEARCHES list includes Golang toolexec, which is the mechanism: the go command accepts a -toolexec flag that wraps every compile and link step, and the agent binary intercepts those invocations to rewrite the package source before it is compiled. That is why no application code changes are needed and also why the instrumentation is fixed at build time. Plugins under plugins/ exist per library, so a span for a given framework or driver only appears if that plugin is present and the library is linked into the binary. The go.mod pins google.golang.org/grpc v1.55.0 and google.golang.org/protobuf v1.30.0, which are the transport and encoding for reporting data to the SkyWalking backend over gRPC. github.com/segmentio/kafka-go v0.4.43 appears in the direct requirements, consistent with Kafka being one of the instrumented surfaces.

Installing the SkyWalking Go agent and running a first build

The README points to the official documentation at skywalking.apache.org under the GoAgent section rather than embedding install steps, so treat that page as the authoritative source for the current command. What the repository does show is the build shape. The Dockerfile builds the agent with the tools/go-agent make target, and the Makefile defines VERSION and HUB variables with HUB defaulting to docker.io/apache and PROJECT defaulting to skywalking-go. A source build of the agent looks like this, run from the repository root.

make -C tools/go-agent linux

The output lands in bin/ as a file matching skywalking-go-agent*linux*, which is the name the Dockerfile copies to /usr/local/bin/skywalking-go-agent. The repository files do not show the exact invocation used to point your own service build at that binary, so the agent's own documentation is where that step belongs. The application binary is produced as usual once the agent is wired into the build. The difference is that packages the agent recognizes have been rewritten before compilation, so the running process reports to the SkyWalking backend without any import of a SkyWalking package in your source. Configuration for the agent is read by the injected runtime, and the official documentation is where the current keys and their defaults are listed; the README does not enumerate them.

The build-time coupling is the real cost

Because instrumentation happens during compilation, the agent version and the application binary are welded together. Upgrading the agent means rebuilding and redeploying every service, and a service built without the agent produces no telemetry, silently. There is no runtime switch to turn instrumentation off for one process, and no way to add a plugin to a binary that was already compiled without it. The release cadence reinforces how much of a commitment this is: v0.5.0 shipped on 2024-08-28, v0.6.0 on 2025-04-28, and v0.7.0 on 2026-08-07, so major releases arrive roughly annually. A team that pins an agent version and later wants a plugin added to a long-lived binary will be rebuilding it. The second constraint is coverage. Plugins live in plugins/, and instrumentation only reaches libraries that have a plugin. If your service uses an HTTP router or a database driver that is not covered, that call produces no span, and the trace will show a gap rather than an error. The README does not document a fallback for uncovered libraries, so the manual instrumentation API in api.go is the escape hatch. There is also a toolchain constraint: go.mod declares go 1.24, and a toolexec wrapper sits in the middle of every compile, so any build environment that does not tolerate the wrapper, including some hermetic or heavily sandboxed CI setups, will need adjustment.

SkyWalking Go versus the OpenTelemetry eBPF approach

The obvious alternative for Go tracing is OpenTelemetry, and the interesting comparison is not the SDK but the eBPF-based auto-instrumentation projects in that ecosystem. The difference in approach is where the interception happens. SkyWalking Go rewrites source at compile time through toolexec, which means the instrumentation is exact and type-aware: the agent sees the real function signature and can wrap it precisely. An eBPF agent attaches to the kernel and observes syscalls and network traffic, which means no rebuild at all and no per-library plugin, but the visibility is at the boundary of the process rather than inside it. You get HTTP and gRPC edges; you do not get a span for an internal function call or a clean parent-child relationship that the compiler knew about. That trade-off cuts both ways. If you cannot rebuild your binaries, or you run third-party Go services you do not compile, the compile-time route is unavailable and the eBPF route is the only option. If you need span-level detail inside the process and you do control the build, the toolexec approach gives more. A second alternative is simply using the OpenTelemetry Go SDK directly, which is a manual instrumentation library rather than an agent. It requires code changes, it does not care about your build pipeline, and it will keep working when you change compilers. Choosing between them is mostly a question of whether you value the absence of code changes more than the absence of build changes.

Licence, maintenance and what an upgrade actually involves

The project is licensed under Apache-2.0, with the LICENSE file at the repository root and a NOTICE file alongside it, which is the standard Apache Software Foundation arrangement. For most users this means the usual obligations: retain the licence and NOTICE, and be aware that the NOTICE file carries attribution requirements if you redistribute a binary built with the agent. That is a general description of the licence, not legal advice, and anyone redistributing a modified agent should read the files themselves. On maintenance, the last push to the default branch was on 2026-08-07, the same day v0.7.0 was released, so the repository is not archived and has recent activity. The upgrade path is the part worth planning for. Since the agent is compiled into the binary, an agent upgrade is a full application release: rebuild with the new agent, run the test suite, and redeploy. The Makefile exposes VERSION and HUB variables so a build can be pinned to a specific agent release, and the Dockerfile takes VERSION and TARGETARCH as build arguments, which is the mechanism for producing reproducible agent images. Teams should pin a version rather than tracking main, because a plugin change between releases alters what spans appear and can shift how existing dashboards aggregate.

Editorial conclusion

Adopt apache/skywalking-go if you already run a SkyWalking backend and want traces from Go services without touching handler code, and you control the build pipeline. Do not adopt it if you cannot rebuild binaries or you need a runtime-attached agent. Verify first that your Go version matches the go.mod requirement of go 1.24, that the plugins you depend on exist under plugins/, and that your CI can pass the toolexec flag through to every go build invocation.

Frequently asked questions

Official sources

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