Configuration de X-Ray SDK pour Java

The X-Ray SDK for Java inclut une classe nommée AWSXRay qui fournit l'enregistreur global. Ceci est un TracingHandler que vous pouvez utiliser pour outiller votre code. Vous pouvez configurer l'enregistreur global pour personnaliser celui AWSXRayServletFilter qui crée des segments pour les HTTP appels entrants.

Plug-ins de service

Permet plugins d'enregistrer des informations sur le service hébergeant votre application.

Pour utiliser un plug-in, appelez withPlugin sur votre AWSXRayRecorderBuilder.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

SDKIl 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 plugins, ils SDK utilisent l'ordre de résolution suivant pour déterminer l'origine : ElasticBeanstalk > EKS > ECS >EC2.

Règles d'échantillonnage

SDKUtilise 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 pour personnaliser la quantité de données enregistrées pour chacune de vos applications.

Les règles personnalisées SDK s'appliquent dans l'ordre dans lequel elles sont définies. Si une demande correspond à plusieurs règles personnalisées, seule la première règle SDK s'applique.

Vous pouvez également configurer le SDK pour charger les règles d'échantillonnage à partir d'un JSON document. Ils SDK peuvent 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.

{
  "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 des règles de sauvegarde dans Spring, configurez l'enregistreur mondial avec une stratégie CentralizedSamplingStrategy dans une classe de configuration.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {

  static {
  AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

  URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
  builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

  AWSXRay.setGlobalRecorder(builder.build());
}

Pour Tomcat, ajoutez un écouteur qui étend ServletContextListener et enregistrez l'écouteur dans le descripteur de déploiement.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

public class Startup implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

        URL ruleFile = Startup.class.getResource("/sampling-rules.json");
        builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

        AWSXRay.setGlobalRecorder(builder.build());
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) { }
}

...
  <listener>
    <listener-class>com.myapp.web.Startup</listener-class>
  </listener>

Pour utiliser les règles local uniquement, remplacez CentralizedSamplingStrategy par LocalizedSamplingStrategy.

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

Journalisation

Par défaut, les messages au ERROR niveau des SDK sorties sont envoyés dans les journaux de votre application. Vous pouvez activer la journalisation au niveau du débogage SDK pour générer des journaux plus détaillés dans le fichier journal de votre application. Les niveaux de journalisation valides sont DEBUG INFOWARN,,ERROR, etFATAL. FATALle niveau du journal fait taire tous les messages du journal car il SDK ne se connecte pas à un niveau fatal.

logging.level.com.amazonaws.xray = DEBUG

Utilisez les journaux de débogage pour identifier les problèmes, tels que des sous-segments ouverts, lorsque vous générez manuellement des sous-segments.

Injection d'ID de suivi dans les journaux

Pour exposer l'identifiant de trace complet actuel à vos instructions de journal, vous pouvez injecter l'identifiant dans le contexte de diagnostic mappé (MDC). À l'aide de l'interface SegmentListener, les méthodes sont appelées à partir de l'enregistreur X-Ray lors des événements du cycle de vie des segments. Lorsqu'un segment ou un sous-segment commence, l'ID de trace qualifié est injecté dans le MDC avec la cléAWS-XRAY-TRACE-ID. Lorsque ce segment se termine, la clé est supprimée duMDC. Ceci expose l'ID de trace à la bibliothèque de journalisation en cours d'utilisation. Lorsqu'un sous-segment se termine, son identifiant parent est injecté dans leMDC.

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

Cette fonctionnalité fonctionne avec les applications Java instrumentées avec le AWS X-Ray SDK for Java et prend en charge les configurations de journalisation suivantes :

Consultez les onglets suivants pour connaître les besoins de chaque frontal et de chaque backend.

Exemple d'injection d'ID de trace

Ce qui suit montre une chaîne PatternLayout modifiée pour inclure l'ID de trace. L'ID de trace est imprimé après le nom du thread (%t) et avant le niveau du journal (%-5p).

%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n

AWS X-Ray imprime automatiquement la clé et l'identifiant de trace dans l'instruction du journal pour faciliter l'analyse. Ce qui suit montre une instruction de journal à l'aide de la modification de PatternLayout.

2019-09-10 18:58:30.844 [nio-5000-exec-4]  AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here

Le message de journalisation lui-même est hébergé dans le modèle %m et est défini lors de l'appel de l'enregistreur.

Écouteurs de segment

Les écouteurs de segments sont une interface permettant d'intercepter les événements du cycle de vie tels que le début et la fin des segments produits par le. AWSXRayRecorder La mise en œuvre d'une fonction d'événement d'écoute de segment peut consister à ajouter la même annotation à tous les sous-segments lorsqu'ils sont créés avec onBeginSubsegment, à enregistrer un message après l'envoi de chaque segment au démon à l'aide afterEndSegment, ou à enregistrer les requêtes envoyées par les SQL intercepteurs beforeEndSubsegmentpour vérifier si le sous-segment représente une SQL requête, en ajoutant des métadonnées supplémentaires si c'est le cas.

Pour voir la liste complète des SegmentListener fonctions, consultez la documentation de l'AWS X-Ray enregistreur SDK pour Java API.

L'exemple suivant montre comment ajouter une annotation cohérente à tous les sous-segments lors de la création avec onBeginSubsegment et comment imprimer un message de journal à la fin de chaque segment avec afterEndSegment.

import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;

public class MySegmentListener implements SegmentListener {
    .....
    
    @Override
    public void onBeginSubsegment(Subsegment subsegment) {
        subsegment.putAnnotation("annotationKey", "annotationValue");
    }
    
    @Override
    public void afterEndSegment(Segment segment) {
        // Be mindful not to mutate the segment
        logger.info("Segment with ID " + segment.getId());
    }
}

Cet écouteur de segment personnalisé est ensuite référencé lors de la génération de AWSXRayRecorder.

AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new MySegmentListener());

Variables d’environnement

Vous pouvez utiliser des variables d'environnement pour configurer le X-Ray SDK pour Java. Le SDK prend en charge les variables suivantes.

Les variables d'environnement remplacent les propriétés de système et les valeurs équivalentes définies dans le code.

Propriétés système

Vous pouvez utiliser les propriétés du système comme alternative JVM spécifique aux variables d'environnement. prend SDK en charge les propriétés suivantes :

Si une propriété système et la variable d'environnement équivalente sont toutes les deux définies, c'est la valeur de la variable d'environnement qui est utilisée. Les deux méthodes remplacent les valeurs définies dans le code.