|
| 1 | +--- |
| 2 | +title: Go Instrumentation Auto SDK |
| 3 | +linkTitle: Auto SDK |
| 4 | +description: Integrate manual spans with zero-code eBPF spans with the Auto SDK. |
| 5 | +weight: 16 |
| 6 | +--- |
| 7 | + |
| 8 | +The OpenTelemetry Go eBPF Instrumentation framework, used by tools like |
| 9 | +[OBI](/docs/zero-code/obi), provides support for integrating with manually |
| 10 | +instrumented OpenTelemetry spans through the Auto SDK. |
| 11 | + |
| 12 | +## What is the Auto SDK? |
| 13 | + |
| 14 | +The Auto SDK is a fully implemented, custom OpenTelemetry Go SDK that is |
| 15 | +designed for compatibility with Go eBPF auto-instrumentation. This allows |
| 16 | +automatically instrumented packages (like `net/http`, for example) to support |
| 17 | +context propagation with manual spans. |
| 18 | + |
| 19 | +## When should I use it? |
| 20 | + |
| 21 | +OpenTelemetry Go eBPF instrumentation currently only supports a limited number |
| 22 | +of packages. You may still want to extend this instrumentation and create custom |
| 23 | +spans within your code. The Auto SDK enables this by instrumenting your custom |
| 24 | +spans with a shared trace context that will also be used by automatic spans. |
| 25 | + |
| 26 | +## How do I use it? |
| 27 | + |
| 28 | +Since the release of |
| 29 | +[OpenTelemetry Go v1.36.0](https://github.com/open-telemetry/opentelemetry-go/releases/tag/v1.36.0), |
| 30 | +the Auto SDK is automatically imported as an indirect dependency with the |
| 31 | +standard Go API. You can confirm that your project has the Auto SDK by checking |
| 32 | +your `go.mod` for `go.opentelemetry.io/auto/sdk`. |
| 33 | + |
| 34 | +Creating manual spans using the Auto SDK is essentially the same as creating |
| 35 | +spans using standard [Go instrumentation](/docs/languages/go/instrumentation/). |
| 36 | + |
| 37 | +With the Auto SDK available, using it is as simple as creating manual spans with |
| 38 | +`tracer.Start()`: |
| 39 | + |
| 40 | +```go |
| 41 | +package main |
| 42 | + |
| 43 | +import ( |
| 44 | + "log" |
| 45 | + "net/http" |
| 46 | + |
| 47 | + "go.opentelemetry.io/otel" |
| 48 | +) |
| 49 | + |
| 50 | +func main() { |
| 51 | + http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { |
| 52 | + // Get tracer |
| 53 | + tracer := otel.Tracer("example-server") |
| 54 | + |
| 55 | + // Start a manual span |
| 56 | + _, span := tracer.Start(r.Context(), "manual-span") |
| 57 | + defer span.End() |
| 58 | + |
| 59 | + // Add an attribute for demonstration |
| 60 | + span.SetAttributes() |
| 61 | + span.AddEvent("Request handled") |
| 62 | + }) |
| 63 | + |
| 64 | + log.Println("Server running at :8080") |
| 65 | + log.Fatal(http.ListenAndServe(":8080", nil)) |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +In this example, the eBPF framework automatically instruments incoming HTTP |
| 70 | +requests, then links the manual span to the same trace instrumented from the |
| 71 | +HTTP library. Note that there is no TracerProvider initialized in this sample. |
| 72 | +The Auto SDK registers its own TracerProvider that is crucial to enabling the |
| 73 | +SDK. |
| 74 | + |
| 75 | +Essentially, there is nothing you need to do to enable the Auto SDK except |
| 76 | +create manual spans in an application instrumented by a Go zero-code agent. As |
| 77 | +long as you don't manually register a global TracerProvider, the Auto SDK will |
| 78 | +automatically be enabled. |
| 79 | + |
| 80 | +{{% alert title="Important" color="warning" %}} |
| 81 | + |
| 82 | +Manually setting a global TracerProvider will conflict with the Auto SDK and |
| 83 | +prevent manual spans from properly correlating with eBPF-based spans. If you are |
| 84 | +creating manual spans in a Go application that is also instrumented by eBPF, do |
| 85 | +not initialize your own global TracerProvider. |
| 86 | + |
| 87 | +{{% /alert %}} |
| 88 | + |
| 89 | +### Auto SDK TracerProvider |
| 90 | + |
| 91 | +In most use cases, it is unnecessary to manually interact with the Auto SDK's |
| 92 | +built-in TracerProvider. However, for certain advanced use cases you may wish to |
| 93 | +manually configure the Auto SDK's TracerProvider. You can access it with the |
| 94 | +[`auto.TracerProvider()`](https://pkg.go.dev/go.opentelemetry.io/auto/sdk) |
| 95 | +function: |
| 96 | + |
| 97 | +```go |
| 98 | +import ( |
| 99 | + "go.opentelemetry.io/otel" |
| 100 | + autosdk "go.opentelemetry.io/auto/sdk" |
| 101 | +) |
| 102 | + |
| 103 | +func main() { |
| 104 | + tp := autosdk.TracerProvider() |
| 105 | + otel.SetTracerProvider(tp) |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +## How does the Auto SDK work? |
| 110 | + |
| 111 | +When an application is instrumented by OpenTelemetry eBPF, the eBPF program will |
| 112 | +look for the presence of the `go.opentelemetry.io/auto/sdk` dependency in the |
| 113 | +application (remember, this dependency is included by default in |
| 114 | +`go.opentelemetry.io/otel`; it does not need to be an explicit import). If it is |
| 115 | +found, the eBPF program will enable a boolean value in the global OpenTelemetry |
| 116 | +SDK to instruct OpenTelemetry to use the Auto SDK TracerProvider. |
| 117 | + |
| 118 | +The Auto SDK then works very similarly to any other SDK, implementing all of the |
| 119 | +specification-required functionality. The main difference is that it is also |
| 120 | +auto-instrumented by eBPF to unify context propagation with other |
| 121 | +eBPF-instrumented libraries. |
| 122 | + |
| 123 | +Essentially the Auto SDK is how OpenTelemetry eBPF identifies and orchestrates |
| 124 | +context propagation with the standard OpenTelemetry API, by instrumenting |
| 125 | +OpenTelemetry function symbols much like it does for any other package. |
0 commit comments