Go Collecteur : FAQ sur les opérations courantes

Pour initialiser le collecteur d' Go s, appelez instana.InitSensor() au début de votre main() fonction en lui fournissant un objet *instana.Options de configuration :

import instana "github.com/instana/go-sensor"

func main() {
    instana.InitSensor(&instana.Options{
        // ...
    })

    // ...
}
 

Le collecteur « Go » utilise les valeurs de instana.DefaultOptions() pour les champs non initialisés de l'objet de configuration fourni à la instana.InitSensor() fonction.

Pour vous assurer que le collecteur d' Go s a terminé le processus d'annonce et qu'il est prêt à collecter les traces avant d'envoyer le trafic vers une instance, utilisez la instana.Ready() méthode :

// Every 100ms whether Go Collector is ready and return on success
func awaitInstanaReady(ctx context.Context) error {
    ticker := time.NewTicker(100*time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            if instana.Ready() {
                return nil
            }
        case <-ctx.Done():
            return ctx.Err()
        }
    }

    return nil
}
 

Pour s'assurer que toutes les traces collectées ont bien été envoyées à l'agent hôte ou à l'acceptateur sans serveur, le collecteur Go API propose la instana.Flush() méthode. Cette méthode force le client de l'agent à envoyer immédiatement toutes les données mises en mémoire tampon. Il s'agit d'une opération bloquante, et il est recommandé de définir un délai d'attente ou une échéance pour cette opération, afin que votre service puisse se fermer correctement:

func main() {
    var srv http.Server

    // Initialize and use http.Server
    // ...

    // Server shutdown sequence:
    // 1. Finalize all pending requests and close the server
    shutdownCtx, _ := context.WithTimeout(ctx, 5 * time.Second)
    if err := srv.Shutdown(shutdownCtx); err != nil {
        // ...
    }
    // 2. Flush all buffered traces to the agent
    flushCtx, _ := context.WithTimeout(ctx, 5 * time.Second)
    if err := instana.Flush(flushCtx); err != nil {
        // ...
    }
    // ...
}
 

Lorsqu'un service est exécuté sur AWS Lambda, instana.Flush() il est automatiquement appelé par le collecteur Go une fois que le gestionnaire a terminé son travail; il n'est donc pas nécessaire de le faire manuellement.

Pour utiliser Go Collector pour contrôler un service exécuté dans un environnement sans serveur, tel que Fargate AWS ou Google Cloud Run, veillez à ce que les variables d'environnement INSTANA_ENDPOINT_URL et INSTANA_AGENT_KEY soient définies dans votre définition de tâche. Pour plus d'informations sur cette procédure, reportez-vous à la section correspondante de la documentation Instana :

• Configuration des définitions de tâches d' AWS Fargate
• Configuration des fonctions d' AWS Lambda
• Configuration des services d' Google Cloud Run

Les services exécutés dans des environnements sans serveur n'utilisent pas d'agent hôte pour envoyer les métriques et les données de traçage au backend d' Instana; par conséquent, la méthode habituelle de configuration du collecteur intégré via configuration.yaml un fichier n'est pas applicable. À la place, il existe un ensemble de variables d'environnement qui peuvent éventuellement être configurées dans la définition de tâche de service :

Pour une description plus détaillée de ces variables et de leur format de valeur, veuillez consulter la documentation disponible à l'adresse Instana.

Certains encapsuleurs d'instrumentation fournis par Instana, par exemple les encapsuleurs de serveur et de client HTTP, collectent des données qui peuvent contenir des informations sensibles, comme des mots de passe, des clés et des secrets. Pour éviter toute fuite de ces valeurs, le collecteur d' Go s les remplace par <redacted> avant de les envoyer à l'agent. La liste des correspondances de noms de paramètres est définie dans com.instana.secrets la section du fichier de configuration del'agent hôte et sera transmise au traceur intégré à l'application pendant la phase d'annonce (nécessite le plugin de traçage de l'agent Gocom.instana.sensor-golang-trace v1.3.0 ou une version ultérieure).

Le paramètre par défaut du comparateur de secrets est contains-ignore-case avec la liste de termes suivante: key, password, secret. Cela occulterait la valeur d'un paramètre dont le nom contient l'une de ces chaînes en ignorant la casse.

Les wrappers d'instrumentation d' HTTP s peuvent collecter les en-têtes d' HTTP s et les envoyer avec les segments de requêtes entrantes ou sortantes. La liste des noms d'en-tête insensibles à la casse peut être fournie à la fois dans (instana.Options).Tracer.CollectableHTTPHeaders champ de l'objet d'options qui est transmis à instana.InitSensor() et dans le fichier de configuration de l'agent hôte. Ce dernier paramètre prévaut et nécessite le plugin de traçage de l'agent Go com.instana.sensor-golang-tracev1.3.0 ou une version ultérieure :

instana.InitSensor(&instana.Options{
        // ...
        Tracer: instana.TracerOptions{
                // ...
                CollectableHTTPHeaders: []string{"x-request-id", "x-loadtest-id"},
        },
})
 

Cette configuration correspond aux paramètres suivants dans le fichier de configuration de l'agent hôte :

com.instana.tracing:
  extra-http-headers:
    - 'x-request-id'
    - 'x-loadtest-id'
 

Par défaut, l'instrumentation HTTP ne collecte aucun en-tête.

Vous pouvez configurer le collecteur d' Go s pour qu'il utilise un enregistreur tiers conforme à instana.LeveledLogger l'interface. Par exemple, pour github.com/sirupsen/logrus ou go.uber.org/zap , utilisez la méthode [ instana.SetLogger()][ instana.SetLogger ] :

import (
    "github.com/uber-go/zap"
    instana "github.com/instana/go-sensor"
)

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    instana.SetLogger(logger)
}
 

Pour permettre à Go Collector d'écrire des journaux de débogage sans modifier le code de l'application, affectez à la variable d'environnement INSTANA_DEBUG une valeur non vide, par exemple :

export INSTANA_DEBUG=true
./your-app
 

La quantité de journaux de débogage que Go Collector produit dépend de votre application et peut être significative. Nous vous recommandons d'activer temporairement les journaux de débogage afin de recueillir des informations avant de signaler un problème au service d'assistance d' Instana.

Instana Go Collector propose une interface d'instrumentation permettant github.com/sirupsen/logrus de collecter et d'envoyer automatiquement les enregistrements des journaux d'erreurs et d'avertissements à l'agent. github.com/instana/go-sensor/instrumentation/instalogrus fournit une implémentation de logrus.Hook qui traite tous les enregistrements d'erreur ou d'avertissement et les associe à la portée indiquée dans l'enregistrement context.Context. Voici un exemple expliquant comment instrumenter le logrus.Loggerglobal et l'utiliser à l'intérieur de http.Handlerinstrumenté:

func main() {
        // ...

        // Register instalogrus hook within the global logger
        logrus.AddHook(instalogrus.NewHook(sensor))
}

func myMethod(w http.ResponseWriter, req *http.Request) {
        // ...

    // When logging an error, make sure to provide the context.Context containing
    // an active span, so that instrumentation hook could associate this message
    // with a call.
    logrus.WithContext(req.Context()).Error("something went wrong")

    // ...
}
 

Pour des exemples plus détaillés, consultez la documentation du package.

Pour activer de manière permanente le profilage continu pour votre service, fournissez EnableAutoProfile: true lors de l'initialisation du détecteur :

func main() {
    instana.InitSensor(&instana.Options{
                EnableAutoProfile: true,
                // ... other options
        })

        // ...
}
 

Pour activer ou désactiver temporairement AutoProfile™ à partir de votre code, appelez autoprofile.Enable() et autoprofile.Disable() :

func expensiveCalculation() {
    autoprofile.Enable()
    defer autoprofile.Disable()

    // ...
}
 

Pour activer la fonctionnalité « AutoProfile™ » pour une application sans modifier le code, définissez la INSTANA_AUTO_PROFILE=true variable d'environnement suivante :

export INSTANA_AUTO_PROFILE=true
./your-app
 

Avec la prise en charge de l'encapsulage d'un http.HandlerFunc, Instana ajoute rapidement la possibilité de tracer les demandes et de collecter les span enfants, exécutés dans le contexte du span de demande.

Des modifications minimales sont nécessaires pour qu'Instana puisse capturer les informations nécessaires. En encapsulant simplement le fichier http.HandlerFunc actuellement existant, Instana collecte et injecte automatiquement les informations nécessaires.

Cela dit, une simple fonction de gestionnaire comme celle qui suit sera simplement encapsulée et enregistrée comme d'habitude.

L'exemple de code suivant montre comment instrumenter un gestionnaire HTTP à l'aide de instana.TracingHandlerFunc() :

sensor := instana.NewSensor("my-http-server")

http.HandleFunc("/", instana.TracingHandlerFunc(sensor, "/", func(w http.ResponseWriter, req *http.Request) {
        // ...
}))
 

Si votre gestionnaire est implémenté en tant que http.Handler, transmettez sa méthode ServeHTTP à la place :

h := http.FileServer(http.Dir("./"))
http.HandleFunc("/files", instana.TracingHandlerFunc(sensor, "index", h.ServeHTTP))
 

Consultez le example/http-database-greeter pour voir l'exemple complet.

La demande de données ou d'informations auprès d'autres systèmes, souvent externes, se fait généralement par le biais de demandes HTTP. Pour s'assurer que les traces contiennent tous les spans, en particulier sur tous les différents systèmes, certaines informations sur les spans doivent être injectées dans les en-têtes de la demande HTTP avant de l'envoyer. L'outil « Go Collector » de Instana permet d'automatiser ce processus autant que possible.

Pour qu'Instana injecte des informations dans les en-têtes de demande, créez http.Client, encapsulez-le dans Transport avec instana.RoundTripper() et utilisez-le comme dans l'exemple suivant.

req, err := http.NewRequest("GET", url, nil)
client := &http.Client{
        Transport: instana.RoundTripper(sensor, nil),
}

ctx := instana.ContextWithSpan(context.Background(), parentSpan)
resp, err := client.Do(req.WithContext(ctx))
 

L'objet fourni parentSpan correspond à la requête entrante provenant du gestionnaire de requêtes (voir l'exemple précédent) et contient les informations de traçage et de span nécessaires pour créer un span enfant et l'injecter dans la requête.

Pour instrumenter un pilote de base de données, enregistrez-le d'abord à l'aide de instana.InstrumentSQLDriver() et remplacez l'appel à sql.Open() par instana.SQLOpen(). Voici un exemple de procédure à effectuer pour le pilote PostgreSQL github.com/lib/pq :

// Create a new instana.Sensor instance
sensor := instana.NewSensor("my-database-app")

// Instrument the driver
instana.InstrumentSQLDriver(sensor, "postgres", &pq.Driver{})

// Create an instance of *sql.DB to use for database queries
db, err := instana.SQLOpen("postgres", "postgres://...")
 

Le pilote instrumenté est enregistré sous le nom <original_name>_with_instana, par exemple, dans l'exemple précédent, le nom serait postgres_with_instana.

Consultez le example/http-database-greeter pour voir l'exemple complet.

À partir de Go v1.10 database/sql fournit une nouvelle façon d'initialiser *sql.DB qui ne nécessite pas l'utilisation du registre de pilotes global. Si la bibliothèque de pilotes de base de données fournit un type qui satisfait à l'interface database/sql/driver.Connector, elle peut être utilisée pour créer une connexion de base de données.

Pour instrumenter une instance de driver.Connector, encapsulez-la à l'aide de instana.WrapSQLConnector(). Voici un exemple de ce que vous pouvez faire pour le pilote MySQL github.com/go-sql-driver/mysql/ :

// Create a new instana.Sensor instance
sensor := instana.NewSensor("my-database-app")

// Initialize a new connector
connector, err := mysql.NewConnector(cfg)
// ...

// Wrap the connector before passing it to sql.OpenDB()
db, err := sql.OpenDB(instana.WrapSQLConnector(sensor, "mysql://...", connector))
 

Le github.com/instana/go-sensor/instrumentation/instamongo module fournit des méthodes de construction qui créent une nouvelle instance de go.mongodb.org/mongo-driver `client` et l'équipent d'un ` Instana `.

Consultez la documentation du module pour obtenir des exemples détaillés et des instructions d'utilisation.

1. Le github.com/instana/go-sensor/instrumentation/instaredis module fournit des wrappers de fonction pour go-redis cet instrument, une instance de redis.Client ou de redis.ClusterClient , en ajoutant des hooks au client redis.

   Consultez la documentation du module pour obtenir des exemples détaillés et des instructions d'utilisation.

2. Le github.com/instana/go-sensor/instrumentation/instaredigo module fournit des wrappers pour redigo cet instrument, ainsi qu'une instance de redis.Conn.

   Consultez la documentation du module pour obtenir des exemples détaillés et des instructions d'utilisation.

Ce github.com/instana/go-sensor/instrumentation/instagrpc module fournit à la fois des intercepteurs de flux et des intercepteurs de fonction unaire. La documentation dumodule fournit des explications détaillées sur la manière de l'utiliser pour instrumenter un serveur gRPC implémenté avec google.golang.org/grpc .

Consultez le example/grpc-client-server pour voir l'exemple complet.

Ce github.com/instana/go-sensor/instrumentation/instagrpc module fournit à la fois des intercepteurs de flux et des intercepteurs de fonction unaire. La documentation dumodule fournit des explications détaillées sur la manière de l'utiliser pour instrumenter un client gRPC implémenté avec google.golang.org/grpc .

Consultez le example/grpc-client-server pour voir l'exemple complet.

Le github.com/instana/go-sensor/instrumentation/instasarama module fournit des méthodes de construction qui permettent de créer une nouvelle instance de clients producteur/consommateur et de l'instrumenter à l'aide d' Instana.

Consultez le example/kafka-producer-consumer pour voir l'exemple complet.

Le github.com/instana/go-sensor/instrumentation/instaamqp module propose une fonction d'encapsulation autour de amqp.Channel qui renvoie une instaamqp.AmqpChannel instance. Cet objet ` Instana ` fournit des fonctionnalités d'instrumentation pour les méthodes amqp.Channel.Publish amqp.Channel.Consume et qui permettent de suivre les données issues des messages envoyés et reçus.

Consultez l'exemple complet à l'adresse github.com/instana/go-sensor/blob/main/instrumentation/instaamqp .

Une instrumentation minimale d'une méthode avec Go Collector s'effectue en deux étapes :

1. Commencez une nouvelle ligne avec instana.Sensor .
2. Finalisez l'intervalle avant que la méthode ne soit renvoyée.

Les étapes facultatives incluent la collecte des détails relatifs à cet appel pour les associer à l'intervalle actif et l'injection de l'intervalle actif dans context.Context afin de garantir la continuation de la trace.

func MyMethod(sensor *instana.Sensor) {
    // Start a new span associated with this method execution
    span := sensor.Tracer().StartSpan("my-method")
    // Schedule span finalization to send it to Instana agent
    defer span.Finish()

    // Optionally attach any relevant information that would help you to identify this call later
    span.SetTag("key1", "value1")
    span.SetTag("answer", 42)

    // ...
}
 

Consultez le example/opentracing pour un exemple plus détaillé.

Pour associer un sous-appel à un intervalle actif, fournissez son contexte via l'option de début d'intervalle opentracing.ChildOf() lors du démarrage de l'intervalle de sous-appel:

var spanOpts []opentracing.StartSpanOption

// Check whether there is an active trace by fetching the currently active span from context
if parent, ok := instana.SpanFromContext(ctx); ok {
    spanOpts = append(spanOpts, opentracing.ChildOf(parent.Context()))
}

// Start the subcall span
span := tracer.StartSpan("my-func", spanOpts...)
 

Il incombe à l'appelant de s'assurer que l'instance de context.Context fournie au destinataire contient la portée active dans laquelle a instana.ContextWithSpan() été injecté :

// And inject it into context, so any subcalls could use it as a parent
SubCall(instana.ContextWithSpan(ctx, span))
 

Les wrappers de code fournis par Instana utilisent context.Context pour intégrer la balise span parente dans un sous-appel. En d'autres termes, à l'intérieur d'une fonction de gestionnaire ou de rappel instrumentée, vous pouvez partir du principe que instana.SpanFromContext() renvoie la plage lancée par la méthode d'encapsulation :

parentSpan, ok := instana.SpanFromContext(ctx)