Use OpenTelemetry to instrument Go applications and report traces - Application Real-Time Monitoring Service

Managed Service for OpenTelemetry muestra las trazas distribuidas únicamente después de que su aplicación reporta los datos de traza al backend. Esta guía le explica cómo instrumentar una aplicación Go con el SDK de OpenTelemetry para Go. También aprenderá a enviar los datos de traza mediante gRPC o HTTP con el protocolo OpenTelemetry (OTLP).

Requisitos previos

Siga estos pasos para obtener un endpoint de OpenTelemetry:

Inicie sesión en la consola de Managed Service for OpenTelemetry.
En el panel de navegación izquierdo, haga clic en Cluster Configurations. Luego, seleccione la pestaña Access point information.
En la barra de navegación superior, elija una región. En la sección Cluster Information, active Show Token.
En la sección Client, haga clic en OpenTelemetry.

Obtenga el endpoint de OpenTelemetry en la columna Related Information de la tabla ubicada en la parte inferior.

OpenTelemetry access point information

Nota

Si su aplicación está desplegada en un entorno de producción de Alibaba Cloud, use un endpoint de Virtual Private Cloud (VPC). De lo contrario, utilice un endpoint público.

gRPC frente a HTTP: elija un transporte

Tanto gRPC como HTTP usan OTLP para entregar los datos de traza. La inicialización del SDK y la lógica de instrumentación son casi idénticas; solo cambian el paquete del exportador y la configuración del cliente.

Aspecto	gRPC	HTTP
Paquete de importación	`otlptracegrpc`	`otlptracehttp`
Formato del endpoint	`host:port` (un solo valor)	`Endpoint` (host:puerto) y `URLPath` por separado
Autenticación	Mapa `WithHeaders` que contiene el token de `Authentication`	Integrada en la ruta de la URL
Caso de uso típico	Entornos de baja latencia y alto rendimiento	Entornos donde gRPC está bloqueado o no está disponible

Para ambos transportes hay dos rutas de envío disponibles:

Ruta	Cuándo usarla
Envío directo con el SDK	Envíe los datos de traza directamente desde su aplicación hacia Managed Service for OpenTelemetry. Requiere el endpoint y el token de autenticación de la sección Requisitos previos.
Reenvío con OpenTelemetry Collector	Dirija los datos de traza a través de un OpenTelemetry Collector autoadministrado. Sustituya el endpoint por la dirección IP de su servicio local y elimine los encabezados de autenticación.

Código de ejemplo

Para ver ejemplos funcionales completos, consulte oltp-exporter.

Enviar datos mediante gRPC

Paso 1: Instalar las dependencias

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

Paso 2: Inicializar el SDK de OpenTelemetry

La función initProvider configura el exportador OTLP gRPC, define los atributos del recurso y registra un TracerProvider global.

Sustituya otelAgentAddr y xtraceToken por el endpoint y el token de autenticación que obtuvo en la sección Requisitos previos.

Nota

Si reenvía los datos a través de un OpenTelemetry Collector, sustituya otelAgentAddr por la dirección IP de su servicio local y elimine el mapa headers.

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

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

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

    // Set the authentication header for 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(
            // Set the service name displayed in the Managed Service for OpenTelemetry console.
            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),
    )

    // Set the global propagator to tracecontext. The global propagator is not specified by 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)
        }
    }
}

Parámetros de configuración principales:

Parámetro	Descripción
`otelAgentAddr`	El endpoint gRPC obtenido desde la consola
`xtraceToken`	El token de autenticación obtenido desde la consola
`Authentication`	La clave del encabezado obligatoria para la autenticación en Managed Service for OpenTelemetry
`semconv.ServiceNameKey`	El nombre del servicio que se muestra en la consola

Paso 3: Instrumentar la aplicación

Cree un controlador HTTP envuelto con la instrumentación de OpenTelemetry. El contenedor otelhttp.NewHandler genera automáticamente spans para las solicitudes HTTP entrantes.

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)

    // Wrap the HTTP handler with OpenTelemetry instrumentation.
    handler := http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        // Simulate a delay.
        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)

Paso 4: Ejecutar y comprobar

Ejecute la aplicación:

go run main.go

En la página Applications de la consola de Managed Service for OpenTelemetry, haga clic en el nombre de la aplicación. Consulte los datos de traza en la página que aparece.

Enviar datos mediante HTTP

Paso 1: Instalar las dependencias

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

Nota

La única diferencia respecto a las dependencias de gRPC es el uso de otlptracehttp en lugar de otlptracegrpc.

Paso 2: Inicializar el SDK de OpenTelemetry

Sustituya Endpoint y URLPath por los valores del endpoint que obtuvo en la sección Requisitos previos.

Nota

Si reenvía los datos a través de un OpenTelemetry Collector, sustituya Endpoint por la dirección IP de su servicio local y elimine los encabezados de autenticación.

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

    traceClientHttp := otlptracehttp.NewClient(
        otlptracehttp.WithEndpoint("127.0.XX.XX:8080"),                    // Replace with your endpoint host and port.
        otlptracehttp.WithURLPath("/adapt_xxxxx/api/otlp/traces"),         // Replace with your endpoint URL path.
        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(
            // Set the service name displayed in the Managed Service for OpenTelemetry console.
            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),
    )

    // Set the global propagator to tracecontext. The global propagator is not specified by 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)
        }
    }
}

Paso 3: Instrumentar la aplicación

Este ejemplo crea spans manualmente dentro de un bucle, en lugar de envolver un controlador HTTP. Cada iteración inicia un span llamado ExecuteRequest, llama a makeRequest y adjunta miembros de baggage que se propagan entre distintos servicios.

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)
    }

Paso 4: Ejecutar y comprobar

Ejecute la aplicación:

go run main.go

En la página Applications de la consola de Managed Service for OpenTelemetry, haga clic en el nombre de la aplicación. Consulte los datos de traza en la página que aparece.

Autoinstrumentación para frameworks comunes

OpenTelemetry ofrece complementos de instrumentación semiautomática. No necesita crear spans manualmente, ya que basta con invocar las operaciones de API de estos complementos en su código. Los spans se generan automáticamente para los frameworks más comunes. Para conocer los frameworks compatibles, consulte el registro de OpenTelemetry.

Pasos siguientes

Bibliotecas de instrumentación de OpenTelemetry para Go: instrumentación automática para frameworks populares.
SDK de OpenTelemetry para Go: código fuente y ejemplos del SDK.
Documentación de OpenTelemetry para Go: opciones avanzadas de configuración.