Utiliser OpenTelemetry pour instrumenter des applications Go et exporter les traces - Application Real-Time Monitoring Service

Managed Service for OpenTelemetry n'affiche les traces distribuées qu'après la réception des données de trace par le backend. Ce guide explique comment instrumenter une application Go à l'aide du SDK OpenTelemetry pour Go et envoyer les données de trace via gRPC ou HTTP en utilisant le protocole OpenTelemetry (OTLP).

Prérequis

Pour obtenir un endpoint OpenTelemetry, suivez ces étapes :

Connectez-vous à la console Managed Service for OpenTelemetry.
Dans le volet de navigation de gauche, cliquez sur Cluster Configurations, puis sur l'onglet Access point information.
Dans la barre de navigation supérieure, sélectionnez une région. Dans la section Cluster Information, activez l'option Show Token.
Dans la section Client, cliquez sur OpenTelemetry.

Récupérez l'endpoint OpenTelemetry dans la colonne Related Information du tableau situé en bas de page.

OpenTelemetry access point information

Remarque

Si votre application est déployée dans un environnement de production Alibaba Cloud, utilisez un endpoint VPC (Virtual Private Cloud). Sinon, utilisez un endpoint public.

gRPC ou HTTP : choisir un transport

gRPC et HTTP utilisent tous deux OTLP pour transmettre les données de trace. La logique d'initialisation du SDK et d'instrumentation est presque identique ; seuls le package d'exportateur et la configuration du client diffèrent.

Aspect	gRPC	HTTP
Package d'importation	`otlptracegrpc`	`otlptracehttp`
Format de l'endpoint	`host:port` (valeur unique)	`Endpoint` (host:port) et `URLPath` distincts
Authentification	Map `WithHeaders` contenant le jeton `Authentication`	Intégrée au chemin de l'URL
Cas d'utilisation typique	Environnements à faible latence et haut débit	Environnements où gRPC est bloqué ou indisponible

Deux méthodes d'envoi sont disponibles pour chaque transport :

Méthode	Quand l'utiliser
Envoi direct via le SDK	Envoyez les données de trace directement depuis votre application vers Managed Service for OpenTelemetry. Nécessite l'endpoint et le jeton d'authentification obtenus dans la section Prérequis.
Transfert via OpenTelemetry Collector	Acheminez les données de trace via un OpenTelemetry Collector auto-géré. Remplacez l'endpoint par l'adresse IP de votre service sur site et supprimez les en-têtes d'authentification.

Exemple de code

Pour des exemples complets et fonctionnels, consultez le dépôt oltp-exporter.

Envoyer des données via gRPC

Étape 1 : Installer les dépendances

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

Étape 2 : Initialiser le SDK OpenTelemetry

La fonction initProvider configure l'exportateur OTLP gRPC, définit les attributs de ressource et enregistre un TracerProvider global.

Remplacez otelAgentAddr et xtraceToken par l'endpoint et le jeton d'authentification obtenus dans la section Prérequis.

Remarque

Si vous transférez les données via un OpenTelemetry Collector, remplacez otelAgentAddr par l'adresse IP de votre service sur site et supprimez la map 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)
        }
    }
}

Paramètres de configuration clés :

Paramètre	Description
`otelAgentAddr`	L'endpoint gRPC obtenu depuis la console
`xtraceToken`	Le jeton d'authentification obtenu depuis la console
`Authentication`	La clé d'en-tête requise pour l'authentification auprès de Managed Service for OpenTelemetry
`semconv.ServiceNameKey`	Le nom du service affiché dans la console

Étape 3 : Instrumenter l'application

Créez un gestionnaire HTTP encapsulé avec l'instrumentation OpenTelemetry. L'encapsuleur otelhttp.NewHandler crée automatiquement des spans pour les requêtes 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)

Étape 4 : Exécuter et vérifier

Démarrez l'application :

go run main.go

Sur la page Applications de la console Managed Service for OpenTelemetry, cliquez sur le nom de l'application. Sur la page qui s'affiche, consultez les données de trace.

Envoyer des données via HTTP

Étape 1 : Installer les dépendances

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

Remarque

La seule différence par rapport aux dépendances gRPC réside dans l'utilisation de otlptracehttp au lieu de otlptracegrpc.

Étape 2 : Initialiser le SDK OpenTelemetry

Remplacez Endpoint et URLPath par les valeurs de l'endpoint obtenu dans la section Prérequis.

Remarque

Si vous transférez les données via un OpenTelemetry Collector, remplacez Endpoint par l'adresse IP de votre service sur site et supprimez les en-têtes d'authentification.

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

Étape 3 : Instrumenter l'application

Cet exemple crée manuellement des spans dans une boucle au lieu d'encapsuler un gestionnaire HTTP. Chaque itération démarre une span nommée ExecuteRequest, appelle makeRequest et attache des membres baggage qui se propagent au-delà des limites de service.

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

Étape 4 : Exécuter et vérifier

Démarrez l'application :

go run main.go

Sur la page Applications de la console Managed Service for OpenTelemetry, cliquez sur le nom de l'application. Sur la page qui s'affiche, consultez les données de trace.

Auto-instrumentation pour les frameworks courants

OpenTelemetry propose des plug-ins d'instrumentation semi-automatiques. Vous n'avez pas besoin de créer manuellement une span. Il vous suffit d'appeler les opérations API fournies par ces plug-ins dans le code. Des spans peuvent être créées automatiquement pour les frameworks courants. Pour plus d'informations sur les frameworks pris en charge, consultez le Registre OpenTelemetry.

Étapes suivantes

Bibliothèques d'instrumentation OpenTelemetry Go – instrumentation automatique pour les frameworks populaires
SDK OpenTelemetry pour Go – code source du SDK et exemples
Documentation OpenTelemetry Go – options de configuration avancées