Go Instrumentation Auto SDK

The OpenTelemetry Go eBPF Instrumentation framework, used by tools like OBI, provides support for integrating with manually instrumented OpenTelemetry spans through the Auto SDK.

What is the Auto SDK?

The Auto SDK is a fully implemented, custom OpenTelemetry Go SDK that is designed for compatibility with Go eBPF auto-instrumentation. This allows automatically instrumented packages (like net/http, for example) to support context propagation with manual spans.

When should I use it?

OpenTelemetry Go eBPF instrumentation currently only supports a limited number of packages. You may still want to extend this instrumentation and create custom spans within your code. The Auto SDK enables this by instrumenting your custom spans with a shared trace context that will also be used by automatic spans.

How do I use it?

Since the release of OpenTelemetry Go v1.36.0, the Auto SDK is automatically imported as an indirect dependency with the standard Go API. You can confirm that your project has the Auto SDK by checking your go.mod for go.opentelemetry.io/auto/sdk.

Creating manual spans using the Auto SDK is essentially the same as creating spans using standard Go instrumentation.

With the Auto SDK available, using it is as simple as creating manual spans with tracer.Start():

package main

import (
	"log"
	"net/http"

	"go.opentelemetry.io/otel"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		// Get tracer
		tracer := otel.Tracer("example-server")

		// Start a manual span
		_, span := tracer.Start(r.Context(), "manual-span")
		defer span.End()

		// Add an attribute for demonstration
		span.SetAttributes()
		span.AddEvent("Request handled")
	})

	log.Println("Server running at :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

In this example, the eBPF framework automatically instruments incoming HTTP requests, then links the manual span to the same trace instrumented from the HTTP library. Note that there is no TracerProvider initialized in this sample. The Auto SDK registers its own TracerProvider that is crucial to enabling the SDK.

Essentially, there is nothing you need to do to enable the Auto SDK except create manual spans in an application instrumented by a Go zero-code agent. As long as you don’t manually register a global TracerProvider, the Auto SDK will automatically be enabled.

Auto SDK TracerProvider

In most use cases, it is unnecessary to manually interact with the Auto SDK’s built-in TracerProvider. However, for certain advanced use cases you may wish to manually configure the Auto SDK’s TracerProvider. You can access it with the auto.TracerProvider() function:

import (
	"go.opentelemetry.io/otel"
    autosdk "go.opentelemetry.io/auto/sdk"
)

func main() {
	tp := autosdk.TracerProvider()
	otel.SetTracerProvider(tp)
}

How does the Auto SDK work?

When an application is instrumented by OpenTelemetry eBPF, the eBPF program will look for the presence of the go.opentelemetry.io/auto/sdk dependency in the application (remember, this dependency is included by default in go.opentelemetry.io/otel; it does not need to be an explicit import). If it is found, the eBPF program will enable a boolean value in the global OpenTelemetry SDK to instruct OpenTelemetry to use the Auto SDK TracerProvider.

The Auto SDK then works very similarly to any other SDK, implementing all of the specification-required functionality. The main difference is that it is also auto-instrumented by eBPF to unify context propagation with other eBPF-instrumented libraries.

Essentially the Auto SDK is how OpenTelemetry eBPF identifies and orchestrates context propagation with the standard OpenTelemetry API, by instrumenting OpenTelemetry function symbols much like it does for any other package.