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

Si vous avez besoin d'un traçage distribué pour une application Go et que vous utilisez déjà Zipkin dans votre pile technologique, vous pouvez envoyer directement les données de trace vers Managed Service for OpenTelemetry. Après l'intégration, vous pouvez consulter la topologie des applications, les traces, les transactions anormales et lentes, ainsi que l'analyse SQL dans la console.

Important

Pour bénéficier de fonctionnalités plus riches, de capacités de traçage avancées et d'une meilleure expérience, connectez votre application à Managed Service for OpenTelemetry en utilisant le protocole OpenTelemetry. Pour plus d'informations, consultez la rubrique Préparatifs.
ARMS propose un agent développé en interne et pris en charge commercialement pour les applications Go. Cet agent permet une instrumentation non intrusive et offre un ensemble de fonctionnalités plus complet ainsi qu'une stabilité accrue. Pour plus d'informations, consultez la rubrique Surveiller les applications Go.

Fonctionnement

Zipkin est un système de traçage distribué open source développé par Twitter qui agrège les données de surveillance en temps réel provenant de plusieurs systèmes hétérogènes.

Votre application Go utilise la bibliothèque cliente Zipkin pour créer des spans et les envoyer à l'endpoint de Managed Service for OpenTelemetry via HTTP :

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un environnement de développement Go
Un accès à la console Managed Service for OpenTelemetry
L'endpoint Zipkin correspondant à votre région (consultez la section Obtenir l'endpoint Zipkin)

Obtenir l'endpoint Zipkin

Connectez-vous à la console Managed Service for OpenTelemetry.
Dans le volet de navigation de gauche, cliquez sur Cluster Configurations. Sur la page qui s'affiche, cliquez 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.
Définissez le paramètre Client sur Jaeger ou Zipkin. Dans cet exemple, Jaeger est sélectionné.
Copiez l'endpoint depuis la colonne Related Information.

Jaeger/Zipkin access point information

Remarque

Si votre application s'exécute dans un environnement de production Alibaba Cloud, utilisez l'endpoint VPC. Sinon, utilisez l'endpoint public. Utilisez l'endpoint v2, sauf si vous avez une raison spécifique d'utiliser la version v1.

Démarrage rapide

Exécutez une démo préconstruite pour vérifier que les données de trace atteignent bien Managed Service for OpenTelemetry avant d'instrumenter votre propre application.

Téléchargez le projet de démonstration.
Ouvrez le fichier utils.go et remplacez <endpoint> par l'endpoint Zipkin obtenu à l'étape Obtenir l'endpoint Zipkin.
Installez les dépendances :
```
dep ensure
```
Exécutez l'application :
```
go run main.go
```
Vérifiez les données de trace dans la console :
1. Connectez-vous à la console ARMS.
2. Dans le volet de navigation de gauche, choisissez Application Monitoring > Applications.
3. Cliquez sur le nom de l'application pour afficher ses données de trace.

Remarque

Si l'icône icon apparaît dans la colonne Language, l'application est connectée à Application Monitoring. Si un tiret (-) s'affiche, l'application est connectée à Managed Service for OpenTelemetry.

Instrumenter votre application

Cette section détaille chaque étape de l'instrumentation : ajout des dépendances, création d'un traceur, enregistrement des spans, ajout de tags aux spans et propagation du contexte entre les services.

Ajouter des dépendances

Ajoutez la bibliothèque Zipkin Go et un routeur à votre projet :

[[constraint]]
  name = "github.com/openzipkin/zipkin-go"
  version = "0.1.1"

[[constraint]]
  name = "github.com/gorilla/mux"
  version = "1.6.2"

Créer un traceur

Un traceur génère des spans qui enregistrent la durée et les métadonnées des opérations distribuées. Configurez-le avec l'endpoint de rapport, l'identité du service local et une stratégie d'échantillonnage.

func getTracer(serviceName string, ip string) *zipkin.Tracer {
    // Create a reporter that sends spans to the Zipkin endpoint.
    // Replace the URL with your actual endpoint from the console.
    reporter := httpreporter.NewReporter("http://tracing-analysis-dc-hz.aliyuncs.com/adapt_aokcdqnxyz@123456ff_abcdef123@abcdef123/api/v2/spans")

    // Set the local endpoint so spans are tagged with this service's identity.
    endpoint, _ := zipkin.NewEndpoint(serviceName, ip)

    // Sample every request. Increase the modulo value to reduce sampling
    // and lower reporting costs (e.g., NewModuloSampler(10) samples 1 in 10).
    sampler := zipkin.NewModuloSampler(1)

    // Initialize the tracer with the reporter, endpoint, and sampler.
    tracer, _ := zipkin.NewTracer(
        reporter,
        zipkin.WithLocalEndpoint(endpoint),
        zipkin.WithSampler(sampler),
    )
    return tracer
}

Créer des spans

Une span racine enregistre l'opération de niveau supérieur d'une requête :

span := tracer.StartSpan("some_operation")
// ... perform the operation ...
span.Finish()

Pour suivre les sous-opérations au sein d'une requête, créez des spans enfants en transmettant le contexte parent :

childSpan := tracer.StartSpan("some_operation2", zipkin.Parent(span.Context()))
// ... perform the sub-operation ...
childSpan.Finish()

Ajouter des tags et des annotations personnalisés (facultatif)

Les tags attachent des métadonnées clé-valeur à une span pour le filtrage et le débogage. Par exemple, enregistrez le code de statut HTTP :

childSpan.Tag("http.status_code", statusCode)

Les annotations enregistrent des événements horodatés au sein d'une span. Utilisez-les pour journaliser les erreurs avec leurs piles d'appels :

childSpan := tracer.StartSpan("some_operation2", zipkin.Parent(span.Context()))
// ... perform the operation ...

var events = make(map[string]string)
events["event"] = "error"
events["stack"] = "Runtime Exception: unable to find userid"
jsonStr, err := json.Marshal(events)
if err == nil {
    childSpan.Annotate(time.Now(), string(jsonStr))
}
childSpan.Finish()

Propager le contexte entre les services

Le contexte de trace (TraceId, ParentSpanId, SpanId et Sampled) doit accompagner chaque appel de procédure distante (RPC) afin que les spans de différents services soient liées au sein d'une seule trace. Zipkin utilise les en-têtes B3 pour propager le contexte via HTTP et gRPC.

Côté client : injecter le contexte dans la requête sortante

req, _ := http.NewRequest("GET", "/", nil)

// Inject trace context as B3 headers into the HTTP request.
injector := b3.InjectHTTP(req)
injector(sp.Context())

Côté serveur : extraire le contexte de la requête entrante

req, _ := http.NewRequest("GET", "/", nil)
b3.InjectHTTP(req)(sp.Context())

b.ResetTimer()
_ = b3.ExtractHTTP(copyRequest(req))

Dépannage

Aucune donnée après l'instrumentation

Vérifiez la sortie d'erreur de votre application :

**failed the request with status code 403** : Le nom d'utilisateur ou le mot de passe est incorrect. Copiez l'endpoint complet, y compris le segment d'authentification, depuis l'onglet Access point information.
Aucune erreur mais aucune donnée : Vérifiez que l'URL de l'endpoint inclut le protocole (http:// ou https://) et le chemin complet se terminant par /api/v2/spans. Confirmez également que votre réseau autorise les connexions sortantes vers l'endpoint.
Configuration de l'échantillonnage : NewModuloSampler avec une valeur supérieure à 1 n'échantillonne qu'une fraction des requêtes. Définissez-la sur 1 lors des tests pour capturer chaque requête.