How to Add Zero‑Code Observability to Golang Apps with Alibaba’s OpenTelemetry Agent

Background

Observability of Go applications traditionally required developers to embed OpenTelemetry SDKs into source code, creating friction between development and operations teams. The Alibaba Cloud open‑source Golang Agent provides zero‑code instrumentation by acting as a drop‑in replacement for the go build command, automatically emitting traces, metrics, and logs.

Quick Start Overview

The Agent binary intercepts the build process, injects OpenTelemetry instrumentation, and produces a binary that reports data to standard OpenTelemetry back‑ends.

Step 1 – Build the Agent binary

Clone the repository and compile the Agent:

# Clone the project
git clone https://github.com/alibaba/opentelemetry-go-auto-instrumentation.git
cd opentelemetry-go-auto-instrumentation
# Build the binary (requires Go toolchain and make)
make clean && make build
chmod u+x ./otel

Step 2 – Compile a Go application with the Agent

Replace the ordinary go build command with the Agent binary. Example for the demo program:

cd example/demo
../../otel go build .

The resulting demo executable contains built‑in tracing, metrics, and log correlation.

Step 3 – Run the tracing pipeline

Start required services (MySQL, Redis) and a Jaeger all‑in‑one collector:

# MySQL (empty password for demo)
docker run -d -p 3306:3306 -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql:8.0.36
# Redis
docker run -d -p 6379:6379 redis:latest
# Jaeger (OTLP, Zipkin, UI ports exposed)
docker run --rm --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 6831:6831/udp -p 6832:6832/udp \
  -p 5778:5778 -p 16686:16686 \
  -p 4317:4317 -p 4318:4318 \
  jaegertracing/all-in-one:1.53.0

Configure OpenTelemetry environment variables and start the instrumented application:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"
export OTEL_EXPORTER_OTLP_INSECURE=true
export OTEL_SERVICE_NAME=demo
./demo

Generate traffic and view traces:

curl http://localhost:9000/http-service
# Open Jaeger UI at http://localhost:16686/jaeger/ui/search

Metrics Reporting

Build the metrics example and launch an OpenTelemetry Collector together with Prometheus using Docker Compose:

cd example/metrics
# Start collector and Prometheus (docker‑compose.yml is provided in the repo)
docker compose up --force-recreate --remove-orphans --detach

Set the same OTLP endpoint variables and run the metrics binary:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"
export OTEL_EXPORTER_OTLP_INSECURE=true
export OTEL_SERVICE_NAME=metrics
./metrics

Query the exported metrics:

curl http://localhost:9000/gc-metrics   # Go GC metrics
curl http://localhost:9000/mem-metrics  # Go memory metrics
# Open Prometheus UI at http://localhost:9090 to explore the time‑series data

Log Correlation

Automatic correlation

If the application uses a supported logging library (e.g., zap), the Agent automatically injects trace_id and span_id fields into each log entry.

cd example/log
./test   # Starts an HTTP server on port 9999
curl http://localhost:9999/log   # Triggers a log line with trace identifiers

Sample JSON log output includes "trace_id" and "span_id" fields.

Manual correlation

Developers can retrieve the identifiers via the OpenTelemetry SDK and add them to logs explicitly. The following example uses the SDK together with zap:

package main

import (
    "go.opentelemetry.io/otel/sdk/trace"
    "go.uber.org/zap"
    "net/http"
)

func main() {
    http.HandleFunc("/logwithtrace", func(w http.ResponseWriter, r *http.Request) {
        logger := zap.NewExample()
        traceId, spanId := trace.GetTraceAndSpanId()
        logger.Info("info with fields", zap.String("traceId", traceId), zap.String("spanId", spanId))
    })
    http.ListenAndServe(":9999", nil)
}

Build and run the example:

cd example/log
./test   # or build with the Agent and run the binary
curl http://localhost:9999/logwithtrace

Conclusion

The Golang Agent eliminates the need for manual instrumentation code, enabling seamless observability for Go services. By simply replacing go build with the Agent binary, developers obtain tracing, metrics, and log correlation out‑of‑the‑box, facilitating service governance, performance analysis, and debugging.

Repository: https://github.com/alibaba/opentelemetry-go-auto-instrumentation