Migration vers Java OpenTelemetry

Pour activer l'agent Java X-Ray, les arguments JVM de votre application devaient être modifiés.

-javaagent:/path-to-disco/disco-java-agent.jar=pluginPath=/path-to-disco/disco-plugins

Pour utiliser des agents Java OpenTelemetry basés sur Java.

Pour instrumenter votre code avec le SDK X-Ray pour Java, il fallait d'abord configurer AWSXRay la classe avec des plug-ins de service et des règles d'échantillonnage locales, puis utiliser un enregistreur fourni.

static { AWS XRayRecorderBuilder builder = AWS XRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ECSPlugin()); AWS XRay.setGlobalRecorder(builder.build());
}

Les dépendances suivantes sont requises.

<dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.opentelemetry</groupId>
                <artifactId>opentelemetry-bom</artifactId>
                <version>1.49.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>io.opentelemetry.instrumentation</groupId>
                <artifactId>opentelemetry-instrumentation-bom</artifactId>
                <version>2.15.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-sdk</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-api</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.semconv</groupId>
            <artifactId>opentelemetry-semconv</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-exporter-otlp</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-xray</artifactId>
            <version>1.46.0</version>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-xray-propagator</artifactId>
            <version>1.46.0-alpha</version>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-resources</artifactId>
            <version>1.46.0-alpha</version>
        </dependency>
    </dependencies>

Configurez le OpenTelemetry SDK en instanciant un objet TracerProvider et enregistrez globalement un objet. OpenTelemetrySdk Configurez les composants suivants :

Pour plus d'informations sur l'utilisation du SDK X-Ray avec le framework Spring pour instrumenter votre application, consultez AOP with Spring et le SDK X-Ray pour Java. Pour activer l'AOP au printemps, procédez comme suit.

OpenTelemetry fournit des bibliothèques d'instrumentation pour collecter des traces pour les demandes entrantes pour les applications Spring Boot. Pour activer l'instrumentation Spring Boot avec une configuration minimale, incluez la dépendance suivante.

<dependency>
           <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-spring-boot-starter</artifactId>
        </dependency>

Pour plus d'informations sur la façon d'activer et de configurer l'instrumentation Spring Boot pour votre OpenTelemetry installation, consultez OpenTelemetry Getting started.

La méthode recommandée par défaut pour instrumenter les applications Spring Boot consiste à utiliser l'agent OpenTelemetry Java avec une instrumentation en bytecode, qui fournit également davantage d' out-of-the-boxinstrumentations et de configurations par rapport à l'utilisation directe du SDK. Pour commencer, voirSolution d'instrumentation automatique à code zéro.

Le SDK X-Ray pour Java peut automatiquement instrumenter AWS tous les clients du SDK v2 lorsque vous avez ajouté aws-xray-recorder-sdk-aws-sdk-v2-instrumentor le sous-module dans votre build.

Pour instrumenter les appels clients individuels aux AWS services en aval avec AWS SDK for Java 2.2 et versions ultérieures, aws-xray-recorder-sdk-aws-sdk-v2-instrumentor le module de votre configuration de compilation a été exclu et aws-xray-recorder-sdk-aws-sdk-v2 le module a été inclus. Les clients individuels ont été instrumentés en les configurant avec unTracingInterceptor.

import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...

public class MyModel {
  private DynamoDbClient client = DynamoDbClient.builder()
    .region(Region.US_WEST_2)
    .overrideConfiguration(
      ClientOverrideConfiguration.builder()
        .addExecutionInterceptor(new TracingInterceptor())
        .build()
      )
    .build();
//...

Pour instrumenter automatiquement tous les clients du AWS SDK, ajoutez le opentelemetry-aws-sdk-2.2-autoconfigure sous-module.

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-aws-sdk-2.2-autoconfigure</artifactId>
            <version>2.15.0-alpha</version>
            <scope>runtime</scope>
        </dependency>

Pour instrumenter des clients AWS SDK individuels, ajoutez le opentelemetry-aws-sdk-2.2 sous-module.

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-aws-sdk-2.2</artifactId>
            <version>2.15.0-alpha</version>
            <scope>compile</scope>
        </dependency>

Enregistrez ensuite un intercepteur lors de la création d'un client AWS SDK.

import io.opentelemetry.instrumentation.awssdk.v2_2.AwsSdkTelemetry;

// ...

    AwsSdkTelemetry telemetry = AwsSdkTelemetry.create(openTelemetry);
    private final S3Client S3_CLIENT = S3Client.builder()
      .overrideConfiguration(ClientOverrideConfiguration.builder()
        .addExecutionInterceptor(telemetry.newExecutionInterceptor())
        .build())
      .build();

Pour instrumenter les requêtes HTTP sortantes avec X-Ray, le SDK X-Ray pour Java HttpClient était requis.

import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
...
  public String randomName() throws IOException {
    CloseableHttpClient httpclient = HttpClientBuilder.create().build();

Comme le SDK Java X-Ray, il OpenTelemetry fournit une ApacheHttpClientTelemetry classe dotée d'une méthode de création qui permet de créer une instance d'un HttpClientBuilder pour fournir des étendues OpenTelemetry basées et une propagation du contexte pour Apache. HttpClient

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-apache-httpclient-5.2</artifactId>
            <version>2.15.0-alpha</version>
            <scope>compile</scope>
        </dependency>

Voici un exemple de code tiré du opentelemetry-java-instrumentation. Le client HTTP fourni par newHttpClient () générera des traces pour les requêtes exécutées.

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.apachehttpclient.v5_2.ApacheHttpClientTelemetry;
import org.apache.hc.client5.http.classic.HttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;

public class ApacheHttpClientConfiguration {

  private OpenTelemetry openTelemetry;

  public ApacheHttpClientConfiguration(OpenTelemetry openTelemetry) {
    this.openTelemetry = openTelemetry;
  }

  // creates a new http client builder for constructing http clients with open telemetry instrumentation
  public HttpClientBuilder createBuilder() {
    return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClientBuilder();
  }

  // creates a new http client with open telemetry instrumentation
  public HttpClient newHttpClient() {
    return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClient();
  }
}

Avec le SDK X-Ray, les beginSubsegment méthodes beginSegment et sont nécessaires pour créer manuellement des segments et des sous-segments X-Ray.

  Segment segment = xrayRecorder.beginSegment("ManualSegment");
        segment.putAnnotation("annotationKey", "annotationValue");
        segment.putMetadata("metadataKey", "metadataValue");

        try {
            Subsegment subsegment = xrayRecorder.beginSubsegment("ManualSubsegment");
            subsegment.putAnnotation("key", "value");

            // Do something here

        } catch (Exception e) {
            subsegment.addException(e);
        } finally {
            xrayRecorder.endSegment();
        }

Vous pouvez utiliser des intervalles personnalisés pour surveiller les performances des activités internes qui ne sont pas capturées par les bibliothèques d'instrumentation. Notez que seuls les serveurs de type span sont convertis en segments X-Ray, tous les autres serveurs sont convertis en sous-segments X-Ray.

Tout d'abord, vous devez créer un traceur afin de générer des spans, que vous pouvez obtenir grâce à la openTelemetry.getTracer méthode. Cela fournira une instance Tracer à partir de TracerProvider celle qui a été enregistrée globalement dans l'Solutions d'instrumentation manuelle avec le SDKexemple. Vous pouvez créer autant d'instances de Tracer que nécessaire, mais il est courant d'avoir un seul Tracer pour l'ensemble d'une application.

Tracer tracer = openTelemetry.getTracer("my-app");

Vous pouvez utiliser le Tracer pour créer des travées.

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;

...

// SERVER span will become an X-Ray segment
Span span = tracer.spanBuilder("get-token")
  .setKind(SpanKind.SERVER)
  .setAttribute("key", "value")
  .startSpan();
try (Scope ignored = span.makeCurrent()) {

  span.setAttribute("metadataKey", "metadataValue");
  span.setAttribute("annotationKey", "annotationValue");
  
  // The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
  span.setAttribute(AttributeKey.stringArrayKey("aws.xray.annotations"), List.of("annotationKey"));

  // Do something here
}

span.end();

Le type par défaut des travées est INTERNAL.

// Default span of type INTERNAL will become an X-Ray subsegment
Span span = tracer.spanBuilder("process-header")
  .startSpan();
try (Scope ignored = span.makeCurrent()) {
  doProcessHeader();
}

Ajouter des annotations et des métadonnées aux traces avec OpenTelemetry le SDK

Dans l'exemple ci-dessus, la setAttribute méthode est utilisée pour ajouter des attributs à chaque intervalle. Par défaut, tous les attributs de span seront convertis en métadonnées dans les données brutes de X-Ray. Pour garantir qu'un attribut est converti en annotation et non en métadonnées, l'exemple ci-dessus ajoute la clé de cet attribut à la liste de l'aws.xray.annotationsattribut. Pour plus d'informations, voir Activer les annotations et les métadonnées X-Ray personnalisées.

Avec des agents Java OpenTelemetry basés sur Java

Si vous utilisez l'agent Java pour instrumenter automatiquement votre application, vous devez effectuer une instrumentation manuelle dans votre application. Par exemple, pour coder les instruments dans l'application pour les sections qui ne sont couvertes par aucune bibliothèque d'auto-instrumentation.

Pour effectuer une instrumentation manuelle avec l'agent, vous devez utiliser l'opentelemetry-api artefact. La version de l'artefact ne peut pas être plus récente que la version de l'agent.

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;

// ...
  
        Span parentSpan = Span.current();
        Tracer tracer = GlobalOpenTelemetry.getTracer("my-app");
        Span span = tracer.spanBuilder("my-span-name")
            .setParent(io.opentelemetry.context.Context.current().with(parentSpan))
            .startSpan();
        span.end();

À l'aide du SDK X-Ray, une fois qu'Active Tracing est activé sur votre Lambda, aucune configuration supplémentaire n'est requise pour utiliser le SDK X-Ray. Lambda créera un segment représentant l'invocation du gestionnaire Lambda, et vous pouvez créer des sous-segments ou des bibliothèques d'instruments à l'aide du SDK X-Ray sans aucune configuration supplémentaire.

Couches Lambda à instrumentation automatique — Vous pouvez instrumenter automatiquement votre Lambda AWS avec des couches Lambda vendues à l'aide des solutions suivantes :

Pour utiliser l'instrumentation manuelle avec la couche d'instrumentation automatique, voirSolutions d'instrumentation manuelle avec le SDK. Pour réduire les démarrages à froid, pensez à utiliser une instrumentation OpenTelemetry manuelle pour générer des OpenTelemetry traces pour votre fonction Lambda.