eBPF-Based Instrumentation is currently the default setting of Odigos Open-Source version, and is also available with the Odigos Enterprise plan.Native Instrumentation is currently not supported for this language.
Supported Versions
Odigos uses the official opentelemetry-go-instrumentation OpenTelemetry Auto Instrumentation using eBPF, thus it supports the same golang versions as this project.- Go runtime versions 1.19 and above are supported.
Odigos Enterprise data collection is done using eBPF, so Odigos requires, at minimum, platforms that have underlying Linux kernel versions of 5.4.0.
Traces
Odigos will automatically instrument your golang services to record and collect spans for distributed tracing, by utilizing the OpenTelemetry Go official auto Instrumentation Libraries.Instrumentation Libraries
The following go modules will be auto instrumented by Odigos:HTTP Frameworks
github.com/gin-gonic/gin
HTTP web framework ⭐️net/http
go standard library for http server and client
Please note that in order for the
http.route
parameter to be properly extracted by Go auto instrumentation, you should use Go 1.22 or above and
declare a template handler as described in this article.HTTP Clients
net/http
go standard library for http server and client
Database Clients, ORMs, and data access libraries
github.com/gocql/gocql
⭐️ versions>= v1.0.0
. database client library for Apache Cassandragithub.com/elastic/go-elasticsearch/v8
⭐️ versions >= v8.0.0database/sql
go standard library for SQL database access
Messaging Systems Clients
github.com/rabbitmq/amqp091-go
⭐️ versions>= v1.4.0
. messaging client for RabbitMQgithub.com/segmentio/kafka-go
versions>= v0.4.1
. messaging client for Apache Kafkagithub.com/apache/pulsar-client-go
⭐️ versions>= v0.12.0
. messaging client for Apache Pulsargithub.com/IBM/sarama
⭐️ versions>= v1.40.0
. messaging client for Apache Kafka
RPC (Remote Procedure Call)
google.golang.org/grpc
versions>= v1.14.0
. rpc client and server for gRPC framework
About Go Offsets
Auto-instrumentation for Go with eBPF works by using eBPF uprobes to dynamically read variables in memory at runtime. For example, when instrumenting thenet/http
package Odigos is able to determine the http.request.method
by probing the Method
field in the current Request
.
Doing so relies on knowing the exact memory location of this field. This is known as the field’s “offset” (because it refers to the field’s location as a
number of bytes offset from the start of the current struct). With this information, our eBPF code can access the value directly.
However, most production Go programs do not preserve this offset information at compile time. Only Go programs compiled with debug information
will include this information by default. To work with all Go programs, Odigos ships with a precompiled list of known offsets for all currently supported
versions of instrumented libraries.
This precompiled list is updated to be up-to-date with every release of Odigos. But, this means that you may encounter errors instrumenting applications
that use very newly released versions of dependencies. If this occurs, it will be resolved by updating to the next release of Odigos, or alternatively
upgrading the locally-stored offsets with the odigos pro update-offsets
command.
Updating Offsets Between Versions
It is possible to pull the latest Go library support for Odigos without updating the entire Odigos installation. There are 3 ways to do so:- Manual updates (with
odigos pro update-offsets
). - Direct automatic updates (recommended, see below).
- Mirrored image automatic updates (for disconnected environments, see below).
Direct automatic updates
In “direct” mode, the CronJob will pull the latest Go library offsets directly from the Odigos cloud server and apply it to the cluster. This option consumes the fewest resources but requires that your cluster has direct internet access to this file hosted on the web. If you have restricted Internet egress policies, see “mirrored image updates” below. Enable automatic updates on any standard cron schedule by setting theodigos config set go-auto-offsets-cron
option to
any valid cron schedule. For example, enable nightly updates at midnight with odigos config set go-auto-offsets-cron "0 0 * * *"
.
To disable automatic updates, set the cron value to an empty string with odigos config set go-auto-offsets-cron ""
.
Mirrored image automatic updates
For clusters with restricted traffic policies, you have the option to mirror the Go library updates as an image. In this mode, the CronJob will run an image that contains the latest Go library offsets bundled into the image itself. This mode does not require direct Internet access from the cluster, but it does require you to mirror this image into your own registry and maintain the latest version on your nodes. To enable mirrored image updates, runodigos config set go-auto-offsets-mode "image"
. Then use the go-auto-offsets-cron
option described above to set the schedule.
To disable mirrored image updates, run odigos config set go-auto-offsets-mode "direct"
(to switch back to direct mode), or set the go-auto-offsets-cron
setting to an empty string (""
) as described above to disable automatic updates entirely.