Go 客户端埋点：OpenTelemetry Go SDK

# 核心 API 与 SDK：全部 v1.47.0
go get go.opentelemetry.io/otel@v1.47.0
go get go.opentelemetry.io/otel/sdk@v1.47.0
go get go.opentelemetry.io/otel/trace@v1.47.0

# OTLP 导出链路（v1.47.0）
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace@v1.47.0
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc@v1.47.0
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp@v1.47.0

# 调试用 stdout 导出器（v1.47.0）
go get go.opentelemetry.io/otel/exporters/stdout/stdouttrace@v1.47.0

# contrib 框架插桩：v0.72.0（版本号与核心不同步，别写错）
go get go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin@v0.72.0
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@v0.72.0
go get go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc@v0.72.0

# 兼容旧系统的传播器：v1.47.0
go get go.opentelemetry.io/contrib/propagators/b3@v1.47.0
go get go.opentelemetry.io/contrib/propagators/jaeger@v1.47.0

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	"go.opentelemetry.io/otel/propagation"
	sdkresource "go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.43.0"
	"go.opentelemetry.io/otel/trace"
)

func initTracer(ctx context.Context) (func(context.Context) error, error) {
	// 1) OTLP gRPC 导出器。otlptracegrpc 默认端点 localhost:4317；
	//    本地 Jaeger all-in-one 是明文 gRPC，必须 WithInsecure，否则 TLS 握手失败。
	exp, err := otlptrace.New(ctx, otlptracegrpc.NewClient(
		otlptracegrpc.WithEndpoint("localhost:4317"),
		otlptracegrpc.WithInsecure(),
	))
	if err != nil {
		return nil, fmt.Errorf("creating OTLP exporter: %w", err)
	}

	// 2) Resource：描述"产生遥测的实体"，随每个 ResourceSpans 只发一次。
	res, err := sdkresource.Merge(
		sdkresource.Default(),
		sdkresource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceName("order-svc"), // v1.43.0 提供 ServiceName() 函数
			attribute.String("deployment.environment", "prod"),
		),
	)
	if err != nil {
		return nil, fmt.Errorf("building resource: %w", err)
	}

	// 3) TracerProvider：批处理器 + Resource + 采样器。
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exp),
		sdktrace.WithResource(res),
		// 入口服务自定义比例时必须套 ParentBased，原因见下文"采样"一节。
		sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.1))),
	)
	otel.SetTracerProvider(tp)

	// 4) 全局传播器——不调这一步，跨进程链路全部静默失效（默认是 no-op）！
	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
		propagation.TraceContext{}, // W3C traceparent/tracestate
		propagation.Baggage{},      // W3C baggage
	))

	return tp.Shutdown, nil
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	shutdown, err := initTracer(ctx)
	if err != nil {
		log.Fatal(err)
	}
	// 进程退出前必须 Shutdown 冲刷；给它一个独立的短超时 ctx，避免退出卡死。
	defer func() {
		sctx, scancel := context.WithTimeout(context.Background(), time.Second)
		defer scancel()
		if err := shutdown(sctx); err != nil {
			log.Println("otel shutdown:", err)
		}
	}()

	tracer := otel.Tracer("order/handler")
	cctx, span := tracer.Start(ctx, "place-order",
		trace.WithAttributes(attribute.String("order.id", "A-1")))
	doWork(cctx)
	span.End() // 别忘了 End：批处理器只导出"已结束"的 span。
	fmt.Println("done")
}

func doWork(ctx context.Context) {
	tracer := otel.Tracer("order/db")
	_, span := tracer.Start(ctx, "query-inventory")
	defer span.End()
	time.Sleep(10 * time.Millisecond)
}

export OTEL_SERVICE_NAME=order-svc
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=prod,service.version=1.8.2"

# 1) 起 Jaeger v2.22 all-in-one（OTLP 4317/4318 + UI 16686）
docker run --rm -d --name jaeger \
  -p 16686:16686 -p 4317:4317 -p 4318:4318 \
  cr.jaegertracing.io/jaegertracing/jaeger:2.22.0

# 2) 跑上面的程序
go run .

# 3) 打开 http://localhost:16686，服务列表选 order-svc，Run Query

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
	"go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/trace"
)

func main() {
	r := gin.Default()
	r.Use(otelgin.Middleware("order-svc",
		// 噪声路由直接不建 span：健康检查、/metrics 这类高频调用
		// 会把 trace 列表刷满毫无信息量的 GET /healthz。
		otelgin.WithGinFilter(func(c *gin.Context) bool {
			return c.Request.URL.Path != "/healthz" && c.Request.URL.Path != "/metrics"
		}),
	))

	r.GET("/orders/:id", func(c *gin.Context) {
		// 中间件已把 server span 放进 c.Request.Context()，
		// 注意：取 span 用 trace.SpanFromContext，不存在 otel.SpanFromContext。
		span := trace.SpanFromContext(c.Request.Context())
		span.SetAttributes(attribute.String("order.id", c.Param("id")))
		c.JSON(http.StatusOK, gin.H{"id": c.Param("id")})
	})

	r.GET("/healthz", func(c *gin.Context) { c.String(http.StatusOK, "ok") })
	_ = r.Run(":8080")
}

package main

import (
	"context"
	"fmt"
	"io"
	"net/http"

	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

func main() {
	client := &http.Client{
		Transport: otelhttp.NewTransport(http.DefaultTransport),
	}
	req, _ := http.NewRequestWithContext(context.Background(),
		http.MethodGet, "http://inventory-svc:8080/stock", nil)
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

req, _ := http.NewRequestWithContext(ctx, http.MethodPost, url, body)
otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header))

package main

import (
	"log"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
)

func dialQuery() (*grpc.ClientConn, error) {
	return grpc.NewClient("dns:///query-svc:9000",
		grpc.WithTransportCredentials(insecure.NewCredentials()),
		grpc.WithStatsHandler(otelgrpc.NewClientHandler()),
	)
}

func main() {
	if _, err := dialQuery(); err != nil {
		log.Fatal(err)
	}
}

package main

import (
	"log"
	"net"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
	"google.golang.org/grpc"
)

func main() {
	s := grpc.NewServer(
		grpc.StatsHandler(otelgrpc.NewServerHandler(
			otelgrpc.WithPublicEndpoint(), // 公网直连的边缘服务才需要，见下
		)),
	)
	lis, err := net.Listen("tcp", ":9000")
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(s.Serve(lis))
}

package main

import (
	"context"
	"log"

	"github.com/twmb/franz-go/pkg/kgo"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/propagation"
	"go.opentelemetry.io/otel/trace"
)

// 生产端：在"业务处理"的 ctx 里建 producer span，注入消息头。
func produce(ctx context.Context, client *kgo.Client, topic, key, payload string) error {
	tracer := otel.Tracer("order/producer")
	cctx, span := tracer.Start(ctx, "send "+topic,
		trace.WithSpanKind(trace.SpanKindProducer))
	defer span.End()

	carrier := propagation.MapCarrier{}
	otel.GetTextMapPropagator().Inject(cctx, carrier)

	headers := make([]kgo.RecordHeader, 0, len(carrier))
	for k, v := range carrier {
		headers = append(headers, kgo.RecordHeader{Key: k, Value: []byte(v)})
	}

	rec := &kgo.Record{Topic: topic, Key: []byte(key), Value: []byte(payload), Headers: headers}
	if err := client.ProduceSync(cctx, rec).FirstErr(); err != nil {
		span.RecordError(err)
		return err
	}
	return nil
}

// 消费端：从消息头 Extract 出上下文，再建 consumer span 作为远程父级的 child。
func consume(ctx context.Context, rec *kgo.Record) {
	carrier := propagation.MapCarrier{}
	for _, h := range rec.Headers {
		carrier[h.Key] = string(h.Value)
	}
	pctx := otel.GetTextMapPropagator().Extract(ctx, carrier)

	tracer := otel.Tracer("order/consumer")
	_, span := tracer.Start(pctx, "process "+rec.Topic,
		trace.WithSpanKind(trace.SpanKindConsumer))
	defer span.End()

	span.SetAttributes(
		attribute.String("messaging.kafka.message.key", string(rec.Key)),
		attribute.Int64("messaging.kafka.source.offset", rec.Offset),
	)
	// ... 这里做真正的业务处理 ...
}

func main() {
	cl, err := kgo.NewClient(kgo.SeedBrokers("localhost:9092"))
	if err != nil {
		log.Fatal(err)
	}
	defer cl.Close()
	// 业务代码里：
	//   _ = produce(ctx, cl, "orders", "A-1", payload)
	//   for _, rec := range cl.PollFetches(ctx).Records() { consume(ctx, rec) }
}

package main

import (
	"context"
	"fmt"
	"log"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/baggage"
	"go.opentelemetry.io/otel/trace"
)

// 入口服务：设置 baggage，随后随传播器注入自动带给下游。
// 注意 baggage.New 返回 (Baggage, error)——没有 MustNew 这个函数，别凭直觉写。
func withTenant(ctx context.Context, tenant string) (context.Context, error) {
	m, err := baggage.NewMemberRaw("tenant.id", tenant)
	if err != nil {
		return ctx, fmt.Errorf("build baggage member: %w", err)
	}
	b, err := baggage.New(m)
	if err != nil {
		return ctx, fmt.Errorf("build baggage: %w", err)
	}
	return baggage.ContextWithBaggage(ctx, b), nil
}

// 中间任一服务：读取，并按需转成当前 span 的属性（这才进 Jaeger 可检索字段）。
func tagTenant(ctx context.Context) {
	m := baggage.FromContext(ctx).Member("tenant.id")
	if m.Value() != "" {
		trace.SpanFromContext(ctx).SetAttributes(attribute.String("tenant.id", m.Value()))
	}
}

func main() {
	ctx, err := withTenant(context.Background(), "acme")
	if err != nil {
		log.Fatal(err)
	}
	tagTenant(ctx)
}

package main

import (
	"context"
	"errors"
	"fmt"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/codes"
	"go.opentelemetry.io/otel/trace"
)

func charge(ctx context.Context) error {
	return errors.New("sku-9 out of stock")
}

func placeOrder(ctx context.Context) error {
	ctx, span := otel.Tracer("order/handler").Start(ctx, "place-order")
	defer span.End()

	if err := charge(ctx); err != nil {
		// 惯用三件套：记事件 + 标失败 + 原样上抛。
		span.RecordError(err, trace.WithStackTrace(true))
		span.SetStatus(codes.Error, "charge failed")
		return fmt.Errorf("place order: %w", err)
	}
	return nil
}

func main() {
	fmt.Println(placeOrder(context.Background()))
}