Migración a Java OpenTelemetry

Para habilitar el agente Java X-Ray, era necesario modificar los argumentos de la JVM de la aplicación.

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

Para utilizar agentes Java OpenTelemetry basados en Java.

Para instrumentar el código con el X-Ray SDK for Java, primero era necesario configurar la AWSXRay clase con complementos de servicio y reglas de muestreo locales y, a continuación, se utilizó una grabadora proporcionada.

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

Se requieren las siguientes dependencias.

<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>

Configure el OpenTelemetry SDK creando una instancia de un objeto TracerProvider y registrándolo globalmente. OpenTelemetrySdk Configura estos componentes:

Para obtener información sobre cómo utilizar el SDK de X-Ray con el marco Spring para instrumentar su aplicación, consulte AOP with Spring y X-Ray SDK for Java. Para habilitar AOP en Spring, sigue estos pasos.

OpenTelemetry proporciona bibliotecas de instrumentación para recopilar el seguimiento de las solicitudes entrantes de las aplicaciones Spring Boot. Para habilitar la instrumentación de Spring Boot con una configuración mínima, incluye la siguiente dependencia.

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

Para obtener más información sobre cómo habilitar y configurar la instrumentación de Spring Boot para su OpenTelemetry configuración, consulte Primeros OpenTelemetry pasos.

El método recomendado por defecto para instrumentar las aplicaciones de Spring Boot es utilizar el agente OpenTelemetry Java con instrumentación de bytecode, que también proporciona más out-of-the-box instrumentaciones y configuraciones en comparación con el uso directo del SDK. Solución de instrumentación automática sin códigoPara empezar, consulte.

El X-Ray SDK for Java puede instrumentar automáticamente todos los clientes del AWS SDK v2 al añadir el aws-xray-recorder-sdk-aws-sdk-v2-instrumentor submódulo a la compilación.

Para instrumentar las llamadas de clientes individuales posteriores a AWS los servicios con el AWS SDK para Java 2.2 y versiones posteriores, se excluyó el aws-xray-recorder-sdk-aws-sdk-v2-instrumentor módulo de la configuración de compilación y se incluyó el aws-xray-recorder-sdk-aws-sdk-v2 módulo. Los clientes individuales se instrumentaron configurándolos con un. TracingInterceptor

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();
//...

Para instrumentar automáticamente todos los clientes AWS del SDK, añada el opentelemetry-aws-sdk-2.2-autoconfigure submódulo.

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

Para instrumentar clientes de AWS SDK individuales, añada el opentelemetry-aws-sdk-2.2 submódulo.

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

A continuación, registre un interceptor al crear un cliente de 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();

Para instrumentar las solicitudes HTTP salientes con X-Ray, se necesitaba el SDK de X-Ray para la versión de Apache HttpClient de Java.

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

Al igual que el SDK de Java X-Ray, OpenTelemetry proporciona una ApacheHttpClientTelemetry clase que tiene un método de creación que permite la creación de una instancia de un HttpClientBuilder para proporcionar OpenTelemetry intervalos basados y propagación de contexto para 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>

El siguiente es un ejemplo de código de opentelemetry-java-instrumentation. El cliente HTTP proporcionado por newHttpClient () generará seguimientos para las solicitudes ejecutadas.

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();
  }
}

Con el SDK de X-Ray, se necesitan beginSubsegment los métodos beginSegment y métodos para crear manualmente segmentos y subsegmentos de rayos X.

  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();
        }

Puede utilizar intervalos personalizados para supervisar el rendimiento de las actividades internas que no se recopilan en las bibliotecas de instrumentación. Tenga en cuenta que solo los servidores de tipo tramo se convierten en segmentos de rayos X, todos los demás tramos se convierten en subsegmentos de rayos X.

En primer lugar, tendrás que crear un rastreador para generar intervalos, que puedes obtener mediante este método. openTelemetry.getTracer Esto proporcionará una instancia de Tracer de la TracerProvider que se registró globalmente en el ejemplo. Soluciones de instrumentación manual con el SDK Puede crear tantas instancias de Tracer como necesite, pero es habitual tener una sola instancia de Tracer para toda la aplicación.

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

Puede usar el Tracer para crear intervalos.

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();

Los tramos tienen un tipo predeterminado de INTERNO.

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

Añadir anotaciones y metadatos a los seguimientos con el SDK OpenTelemetry

En el ejemplo anterior, el setAttribute método se utiliza para añadir atributos a cada tramo. De forma predeterminada, todos los atributos del intervalo se convertirán en metadatos en los datos sin procesar de X-Ray. Para garantizar que un atributo se convierta en una anotación y no en metadatos, en el ejemplo anterior se agrega la clave de ese atributo a la lista de aws.xray.annotations atributos. Para obtener más información, consulte Habilitar las anotaciones y anotaciones de rayos X personalizadas y los metadatos.

Con agentes Java OpenTelemetry basados

Si utiliza el agente Java para instrumentar automáticamente la aplicación, necesitará realizar la instrumentación manual en la aplicación. Por ejemplo, al código de instrumentos dentro de la aplicación para secciones que no están cubiertas por ninguna biblioteca de autoinstrumentación.

Para realizar la instrumentación manual con el agente, es necesario utilizar el artefacto. opentelemetry-api La versión del artefacto no puede ser más reciente que la versión del agente.

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();

Al usar el SDK de X-Ray, una vez que su Lambda tenga activado el rastreo activo, no se requiere ninguna configuración adicional para usar el SDK de X-Ray. Lambda creará un segmento que represente la invocación del controlador de Lambda y usted puede crear subsegmentos o bibliotecas de instrumentos mediante el SDK de X-Ray sin necesidad de realizar ninguna configuración adicional.

Autoinstrumentación de capas Lambda: puede instrumentar automáticamente su Lambda con capas Lambda vendidas AWS mediante las siguientes soluciones:

Para utilizar la instrumentación manual junto con la capa de autoinstrumentación, consulte. Soluciones de instrumentación manual con el SDK Para reducir los arranques en frío, considere la posibilidad de utilizar instrumentación OpenTelemetry manual para generar OpenTelemetry trazas para la función Lambda.