Gunakan OpenTelemetry untuk menginstrumentasi aplikasi Go dan melaporkan jejak - Managed Service for OpenTelemetry

Managed Service for OpenTelemetry hanya menampilkan jejak terdistribusi setelah aplikasi Anda mengirimkan data jejak ke backend. Panduan ini memandu Anda melalui proses menginstrumentasi aplikasi Go dengan OpenTelemetry SDK for Go dan mengirimkan data jejak melalui gRPC atau HTTP menggunakan OpenTelemetry Protocol (OTLP).

Prasyarat

Untuk mendapatkan titik akhir OpenTelemetry, lakukan langkah-langkah berikut:

Masuk ke Konsol Managed Service for OpenTelemetry.
Pada panel navigasi sebelah kiri, klik Cluster Configurations, lalu klik tab Access point information.
Pada bilah navigasi atas, pilih wilayah. Di bagian Cluster Information, aktifkan Show Token.
Di bagian Client, klik OpenTelemetry.

Dapatkan titik akhir OpenTelemetry di kolom Related Information pada tabel di bagian bawah.

Catatan

Jika aplikasi Anda diterapkan di lingkungan produksi Alibaba Cloud, gunakan titik akhir Virtual Private Cloud (VPC). Jika tidak, gunakan titik akhir publik.

gRPC vs. HTTP: pilih transport

Baik gRPC maupun HTTP menggunakan OTLP untuk mengirimkan data jejak. Logika inisialisasi dan instrumentasi SDK hampir identik—hanya paket exporter dan konfigurasi klien yang berbeda.

Aspek	gRPC	HTTP
Impor paket	`otlptracegrpc`	`otlptracehttp`
Format titik akhir	`host:port` (nilai tunggal)	`Endpoint` (host:port) dan `URLPath`
Otentikasi	`WithHeaders` yang berisi token `Authentication`	Disematkan dalam path URL
Kasus penggunaan khas	Lingkungan dengan latensi rendah dan throughput tinggi	Lingkungan tempat gRPC diblokir atau tidak tersedia

Dua jalur pengiriman tersedia untuk masing-masing transport:

Jalur	Kapan digunakan
SDK direct submission	Kirimkan data jejak langsung dari aplikasi Anda ke Managed Service for OpenTelemetry. Memerlukan titik akhir dan token otentikasi dari bagian Prasyarat.
OpenTelemetry Collector forwarding	Arahkan data jejak melalui OpenTelemetry Collector yang dikelola sendiri. Ganti titik akhir dengan alamat IP layanan on-premises Anda dan hapus header otentikasi.

Kode contoh

Untuk contoh lengkap yang berfungsi, lihat oltp-exporter.

Kirimkan data melalui gRPC

Langkah 1: Instal dependensi

go get go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/trace \
  go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc

Langkah 2: Inisialisasi OpenTelemetry SDK

Fungsi initProvider mengonfigurasi exporter OTLP gRPC, menyiapkan atribut sumber daya, dan mendaftarkan TracerProvider global.

Ganti otelAgentAddr dan xtraceToken dengan titik akhir dan token otentikasi dari bagian Prasyarat.

Catatan

Jika Anda meneruskan data melalui OpenTelemetry Collector, ganti otelAgentAddr dengan alamat IP layanan on-premises Anda dan hapus peta headers.

func initProvider() func() {
    ctx := context.Background()

    otelAgentAddr, xtraceToken, ok := common.ObtainXTraceInfo()

    if !ok {
        log.Fatalf("Cannot init OpenTelemetry, exit")
        os.Exit(-1)
    }

    // Setel header otentikasi untuk Managed Service for OpenTelemetry.
    headers := map[string]string{"Authentication": xtraceToken}
    traceClient := otlptracegrpc.NewClient(
        otlptracegrpc.WithInsecure(),
        otlptracegrpc.WithEndpoint(otelAgentAddr),
        otlptracegrpc.WithHeaders(headers),
        otlptracegrpc.WithDialOption(grpc.WithBlock()))
    log.Println("start to connect to server")
    traceExp, err := otlptrace.New(ctx, traceClient)
    handleErr(err, "Failed to create the collector trace exporter")

    res, err := resource.New(ctx,
        resource.WithFromEnv(),
        resource.WithProcess(),
        resource.WithTelemetrySDK(),
        resource.WithHost(),
        resource.WithAttributes(
            // Tetapkan nama layanan yang ditampilkan di Konsol Managed Service for OpenTelemetry.
            semconv.ServiceNameKey.String(common.ServerServiceName),
            semconv.HostNameKey.String(common.ServerServiceHostName),
        ),
    )
    handleErr(err, "failed to create resource")

    bsp := sdktrace.NewBatchSpanProcessor(traceExp)
    tracerProvider := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.AlwaysSample()),
        sdktrace.WithResource(res),
        sdktrace.WithSpanProcessor(bsp),
    )

    // Tetapkan propagator global ke tracecontext. Propagator global tidak ditentukan secara default.
    otel.SetTextMapPropagator(propagation.TraceContext{})
    otel.SetTracerProvider(tracerProvider)

    return func() {
        cxt, cancel := context.WithTimeout(ctx, time.Second)
        defer cancel()
        if err := traceExp.Shutdown(cxt); err != nil {
            otel.Handle(err)
        }
    }
}

Parameter Konfigurasi Utama:

Parameter	Deskripsi
`otelAgentAddr`	Titik akhir gRPC yang diperoleh dari konsol
`xtraceToken`	Token otentikasi yang diperoleh dari konsol
`Authentication`	Kunci header yang diperlukan untuk otentikasi Managed Service for OpenTelemetry
`semconv.ServiceNameKey`	Nama layanan yang ditampilkan di konsol

Langkah 3: Instrumentasi aplikasi

Buat penanganan HTTP yang dibungkus dengan instrumentasi OpenTelemetry. Pembungkus otelhttp.NewHandler secara otomatis membuat rentang untuk permintaan HTTP masuk.

shutdown := initProvider()
    defer shutdown()

    serverAttribute := attribute.String("server-attribute", "foo")
    fmt.Println("start to gen chars for trace data")
    initTraceDemoData()
    fmt.Println("gen trace data done")
    tracer := otel.Tracer(common.TraceInstrumentationName)

    // Bungkus penanganan HTTP dengan instrumentasi OpenTelemetry.
    handler := http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        // Simulasikan penundaan.
        var sleep int64
        switch modulus := time.Now().Unix() % 5; modulus {
        case 0:
            sleep = rng.Int63n(2000)
        case 1:
            sleep = rng.Int63n(15)
        case 2:
            sleep = rng.Int63n(917)
        case 3:
            sleep = rng.Int63n(87)
        case 4:
            sleep = rng.Int63n(1173)
        }
        ctx := req.Context()
        span := trace.SpanFromContext(ctx)
        span.SetAttributes(serverAttribute)

        actionChild(tracer, ctx, sleep)

        w.Write([]byte("Hello World"))
    })
    wrappedHandler := otelhttp.NewHandler(handler, "/hello")

    http.Handle("/hello", wrappedHandler)
    http.ListenAndServe(":7080", nil)

Langkah 4: Jalankan dan verifikasi

Jalankan aplikasi:

go run main.go

Di halaman Applications pada Konsol Managed Service for OpenTelemetry, klik nama aplikasi, lalu lihat Data jejak di halaman yang muncul.

Kirimkan data melalui HTTP

Langkah 1: Instal dependensi

go get go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/trace \
  go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

Catatan

Satu-satunya perbedaan dari dependensi gRPC adalah otlptracehttp menggantikan otlptracegrpc.

Langkah 2: Inisialisasi OpenTelemetry SDK

Ganti Endpoint dan URLPath dengan nilai dari titik akhir yang diperoleh di bagian Prasyarat.

Catatan

Jika Anda meneruskan data melalui OpenTelemetry Collector, ganti Endpoint dengan alamat IP layanan on-premises Anda dan hapus header otentikasi.

func initProvider() func() {
    ctx := context.Background()

    traceClientHttp := otlptracehttp.NewClient(
        otlptracehttp.WithEndpoint("127.0.XX.XX:8080"),                    // Ganti dengan host dan port titik akhir Anda.
        otlptracehttp.WithURLPath("/adapt_xxxxx/api/otlp/traces"),         // Ganti dengan path URL titik akhir Anda.
        otlptracehttp.WithInsecure())
    otlptracehttp.WithCompression(1)

    traceExp, err := otlptrace.New(ctx, traceClientHttp)
    handleErr(err, "Failed to create the collector trace exporter")

    res, err := resource.New(ctx,
        resource.WithFromEnv(),
        resource.WithProcess(),
        resource.WithTelemetrySDK(),
        resource.WithHost(),
        resource.WithAttributes(
            // Tetapkan nama layanan yang ditampilkan di Konsol Managed Service for OpenTelemetry.
            semconv.ServiceNameKey.String(common.ClientServiceName),
            semconv.HostNameKey.String(common.ClientServiceHostName),
        ),
    )
    handleErr(err, "failed to create resource")

    bsp := sdktrace.NewBatchSpanProcessor(traceExp)
    tracerProvider := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.AlwaysSample()),
        sdktrace.WithResource(res),
        sdktrace.WithSpanProcessor(bsp),
    )

    // Tetapkan propagator global ke tracecontext. Propagator global tidak ditentukan secara default.
    otel.SetTextMapPropagator(propagation.TraceContext{})
    otel.SetTracerProvider(tracerProvider)

    log.Println("OTEL init success")

    return func() {
        cxt, cancel := context.WithTimeout(ctx, time.Second)
        defer cancel()
        if err := traceExp.Shutdown(cxt); err != nil {
            otel.Handle(err)
        }
    }
}

Langkah 3: Instrumentasi aplikasi

Contoh ini membuat rentang secara manual dalam loop, bukan membungkus penanganan HTTP. Setiap iterasi memulai rentang bernama ExecuteRequest, memanggil makeRequest, dan menyambungkan anggota baggage yang dipropagasikan melintasi batas layanan.

tracer := otel.Tracer(common.TraceInstrumentationName)

    method, _ := baggage.NewMember("method", "repl")
    client, _ := baggage.NewMember("client", "cli")
    bag, _ := baggage.New(method, client)

    defaultCtx := baggage.ContextWithBaggage(context.Background(), bag)
    for {
        ctx, span := tracer.Start(defaultCtx, "ExecuteRequest")
        makeRequest(ctx)
        span.End()
        time.Sleep(time.Duration(1) * time.Second)
    }

Langkah 4: Jalankan dan verifikasi

Jalankan aplikasi:

go run main.go

Di halaman Applications pada Konsol Managed Service for OpenTelemetry, klik nama aplikasi tersebut. Di halaman yang muncul, tampilkan data jejak.

Auto-instrumentation untuk framework umum

OpenTelemetry menyediakan plugin instrumentasi semi-otomatis. Anda tidak perlu membuat rentang secara manual. Cukup panggil operasi API yang disediakan oleh plugin ini dalam kode Anda. Rentang dapat dibuat secara otomatis untuk framework umum. Untuk informasi selengkapnya tentang framework yang didukung, lihat OpenTelemetry Registry.

Langkah selanjutnya

Pustaka instrumentasi OpenTelemetry Go — instrumentasi otomatis untuk framework populer
OpenTelemetry SDK for Go — kode sumber dan contoh SDK
Dokumentasi OpenTelemetry Go — opsi konfigurasi lanjutan