Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Configuration du kit SDK X-Ray pour Go **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Vous pouvez spécifier la configuration du SDK X-Ray pour Go par le biais de variables d'environnement, en `Configure` appelant avec `Config` un objet ou en utilisant des valeurs par défaut. Les variables d'environnement ont priorité sur les valeurs `Config`, qui prévalent elles-même sur n'importe quelle valeur par défaut. **Topics** + [Plug-ins de service](#xray-sdk-go-configuration-plugins) + [Règles d'échantillonnage](#xray-sdk-go-configuration-sampling) + [Logging](#xray-sdk-go-configuration-logging) + [Variables d’environnement](#xray-sdk-go-configuration-envvars) + [Utilisation de Configure](#xray-sdk-go-configuration-configure) ## Plug-ins de service Permet `plugins` d'enregistrer des informations sur le service hébergeant votre application. **Plug-ins** + Amazon EC2 — `EC2Plugin` ajoute l'ID de l'instance, la zone de disponibilité et le groupe de CloudWatch journaux. + Elastic `ElasticBeanstalkPlugin` Beanstalk : ajoute le nom de l'environnement, l'étiquette de version et l'ID de déploiement. + Amazon ECS — `ECSPlugin` ajoute l'ID du conteneur. ![\[Segment - Scorekeep details showing Elastic Beanstalk, EC2, and Xray configuration information.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-go.png) Pour utiliser un module d'extension, importez l'un des modules suivants : ``` "github.com/aws/aws-xray-sdk-go/awsplugins/ec2" "github.com/aws/aws-xray-sdk-go/awsplugins/ecs" "github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk" ``` Chaque plug-in a un appel de fonction `Init()` explicite qui charge le plug-in. **Example ec2.Init()** ``` import ( "os" "github.com/aws/aws-xray-sdk-go/awsplugins/ec2" "github.com/aws/aws-xray-sdk-go/xray" ) func init() { // conditionally load plugin if os.Getenv("ENVIRONMENT") == "production" { ec2.Init() } xray.Configure(xray.Config{ ServiceVersion: "1.2.3", }) } ``` Le SDK utilise également les paramètres du plugin pour définir le `origin` champ du segment. Cela indique le type de AWS ressource qui exécute votre application. Lorsque vous utilisez plusieurs plug-ins, le SDK utilise l'ordre de résolution suivant pour déterminer l'origine : ElasticBeanstalk > EKS > ECS > EC2. ## Règles d'échantillonnage Le SDK utilise les règles d'échantillonnage que vous définissez dans la console X-Ray pour déterminer les demandes à enregistrer. La règle par défaut suit la première demande chaque seconde, et 5 % de toutes les demandes supplémentaires provenant de tous les services envoient des traces à X-Ray. [Créez des règles supplémentaires dans la console X-Ray](xray-console-sampling.md) pour personnaliser la quantité de données enregistrées pour chacune de vos applications. Le SDK applique les règles personnalisées dans l'ordre dans lequel elles sont définies. Si une demande correspond à plusieurs règles personnalisées, le SDK applique uniquement la première règle. **Note** Si le SDK ne parvient pas à accéder à X-Ray pour obtenir des règles d'échantillonnage, il revient à une règle locale par défaut concernant la première demande chaque seconde, et 5 % de toutes les demandes supplémentaires par hôte. Cela peut se produire si l'hôte n'est pas autorisé à appeler sampling APIs ou ne peut pas se connecter au daemon X-Ray, qui agit comme un proxy TCP pour les appels d'API effectués par le SDK. Vous pouvez également configurer le SDK pour charger des règles d'échantillonnage à partir d'un document JSON. Le SDK peut utiliser les règles locales comme solution de rechange dans les cas où l'échantillonnage X-Ray n'est pas disponible, ou utiliser exclusivement les règles locales. **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` Cet exemple définit une règle personnalisée et une règle par défaut. La règle personnalisée applique un taux d'échantillonnage de 5 % sans nombre minimum de demandes à suivre pour les chemins sous-jacents. `/api/move/` La règle par défaut suit la première demande chaque seconde et 10 % des demandes supplémentaires. L'inconvénient de définir des règles localement est que la cible fixe est appliquée par chaque instance de l'enregistreur indépendamment, au lieu d'être gérée par le service X-Ray. Au fur et à mesure que vous déployez de nouveaux hôtes, le taux fixe est multiplié, ce qui complique le contrôle de la quantité de données enregistrées. Activé AWS Lambda, vous ne pouvez pas modifier le taux d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des demandes échantillonnées par ce service seront enregistrés par Lambda. Si le suivi actif est activé et qu'aucun en-tête de suivi n'est présent, Lambda prend la décision d'échantillonnage. Pour fournir les règles de sauvegarde, pointez sur le fichier JSON d'échantillonnage local en utilisant `NewCentralizedStrategyWithFilePath`. **Example main.go — Règle d'échantillonnage local** ``` s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json xray.Configure(xray.Config{SamplingStrategy: s}) ``` Pour utiliser uniquement les règles locales, pointez sur le fichier JSON d'échantillonnage local en utilisant `NewLocalizedStrategyFromFilePath`. **Example main.go — Désactive l'échantillonnage** ``` s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json xray.Configure(xray.Config{SamplingStrategy: s}) ``` ## Logging **Note** Les champs `xray.Config{}` `LogLevel` et `LogFormat` sont obsolètes à partir de la version 1.0.0-rc.10. X-Ray utilise l'interface suivante pour la journalisation. L'enregistreur d’événements par défaut écrit sur `stdout` pour `LogLevelInfo` et au-dessus. ``` type Logger interface { Log(level LogLevel, msg fmt.Stringer) } const ( LogLevelDebug LogLevel = iota + 1 LogLevelInfo LogLevelWarn LogLevelError ) ``` **Example écrire à `io.Writer`** ``` xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError)) ``` ## Variables d’environnement Vous pouvez utiliser des variables d'environnement pour configurer le SDK X-Ray for Go. Le kit SDK prend en charge les variables suivantes. + `AWS_XRAY_CONTEXT_MISSING`— Réglé sur `RUNTIME_ERROR` pour générer des exceptions lorsque votre code instrumenté tente d'enregistrer des données alors qu'aucun segment n'est ouvert. **Valeurs valides** + `RUNTIME_ERROR`— Lance une exception d'exécution. + `LOG_ERROR`— Enregistrez une erreur et continuez (par défaut). + `IGNORE_ERROR`— Ignorez l'erreur et continuez. Des erreurs liées à des segments ou sous-segments manquants peuvent se produire lorsque vous essayez d'utiliser un client instrumenté dans un code de démarrage qui s'exécute lorsqu'aucune demande n'est ouverte, ou dans un code qui génère un nouveau thread. + `AWS_XRAY_TRACING_NAME`— Définissez le nom de service que le SDK utilise pour les segments. + `AWS_XRAY_DAEMON_ADDRESS`— Définissez l'hôte et le port de l'écouteur du daemon X-Ray. Par défaut, le SDK envoie les données de suivi à`127.0.0.1:2000`. Utilisez cette variable si vous avez configuré le démon pour qu'il [écoute sur un port différent](xray-daemon-configuration.md) ou s'il s'exécute sur un autre hôte. + `AWS_XRAY_CONTEXT_MISSING`— Définissez la valeur pour déterminer comment le SDK gère les erreurs de contexte manquantes. Des erreurs relatives aux segments ou aux sous-segments manquants peuvent se produire lorsque vous tentez d'utiliser un client instrumenté dans le code de démarrage quand aucune demande n'est ouverte, ou dans un code qui génère un nouveau thread. + `RUNTIME_ERROR`— Par défaut, le SDK est configuré pour lancer une exception d'exécution. + `LOG_ERROR`— Paramétré pour enregistrer une erreur et continuer. Les variables d'environnement remplacent les valeurs équivalentes définies dans le code. ## Utilisation de Configure Vous pouvez également configurer le SDK X-Ray pour Go à l'aide `Configure` de cette méthode. `Configure`prend un argument, un `Config` objet, avec les champs facultatifs suivants. DaemonAddr Cette chaîne indique l'hôte et le port de l'écouteur du daemon X-Ray. Si elle n'est pas spécifiée, X-Ray utilise la valeur de la variable d'`AWS_XRAY_DAEMON_ADDRESS`environnement. Si cette valeur n'est pas définie, c'est « 127.0.0.1:2000 » qui est utilisé. ServiceVersion Cette chaîne définit la version du service. Si elle n'est pas spécifiée, X-Ray utilise la chaîne vide (« »). SamplingStrategy Cet objet `SamplingStrategy` définit les appels d'application qui sont suivis. Si ce n'est pas spécifié, X-Ray utilise un`LocalizedSamplingStrategy`, qui prend la stratégie telle que définie dans`xray/resources/DefaultSamplingRules.json`. StreamingStrategy Cet `StreamingStrategy` objet indique s'il faut diffuser un segment lorsqu'il **RequiresStreaming**renvoie **true**. Si ce n'est pas spécifié, X-Ray utilise un `DefaultStreamingStrategy` qui diffuse un segment échantillonné si le nombre de sous-segments est supérieur à 20. ExceptionFormattingStrategy Cet objet `ExceptionFormattingStrategy` définit la façon dont vous souhaitez gérer les diverses exceptions. Si ce n'est pas spécifié, X-Ray utilise un `DefaultExceptionFormattingStrategy` avec un type `XrayError` of`error`, le message d'erreur et le stack trace.