Tutoriales de OpenTelemetry: instrumentación de una aplicación Java de muestra

Descargue la aplicación de demostración

Si aún no ha descargado nuestra aplicación de demostración, ejecute lo siguiente:

$
git clone https://github.com/newrelic/newrelic-opentelemetry-examples.git

Instalar dependencia

Para agregar dependencia:

1. Vaya al directorio de la aplicación.

   bash

   Copia

   $
   cd newrelic-opentelemetry-examples/getting-started-guides/java/uninstrumented

2. Abra build.gradle.

3. Agregue los siguientes elementos resaltados al bloque dependencies (es posible que deba desplazarse hacia abajo dentro del bloque de código):

   plugins {
       id 'org.springframework.boot' version '2.7.5'
       id 'io.spring.dependency-management' version '1.1.0'
       id 'java'
   }
   
   java {
       toolchain {
           languageVersion = JavaLanguageVersion.of(17)
       }
   }
   
   repositories {
       mavenCentral()
   }
   
   bootRun {
       mainClass.set 'com.example.demo.Application'
   }
   
   configurations.all {
       exclude module: 'spring-boot-starter-logging'
   }
   
   dependencies {
       implementation 'org.springframework.boot:spring-boot-starter-web'
       implementation 'org.springframework.boot:spring-boot-starter-log4j2'
   
       // OpenTelemetry core
       implementation platform('io.opentelemetry:opentelemetry-bom:1.22.0')
       implementation platform('io.opentelemetry:opentelemetry-bom-alpha:1.22.0-alpha')
       implementation 'io.opentelemetry:opentelemetry-api'
       implementation 'io.opentelemetry:opentelemetry-sdk'
       implementation 'io.opentelemetry:opentelemetry-exporter-otlp'
       implementation 'io.opentelemetry:opentelemetry-exporter-otlp-logs'
       implementation 'io.opentelemetry:opentelemetry-sdk-extension-autoconfigure'
   
       // OpenTelemetry instrumentation
       implementation platform('io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:1.22.1-alpha')
       implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-metrics'
       implementation 'io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17'
       implementation 'io.opentelemetry.instrumentation:opentelemetry-spring-webmvc-6.0'
   }

   Copia

   Notas:

• La dependencia bom (lista de materiales) se utiliza para sincronizar versiones de dependencia para un ecosistema en particular. Dado que OpenTelemetry publica muchos componentes Java, estos ayudan a garantizar que todas las versiones estén sincronizadas, ya sea que use solo unas pocas o muchas.
• Las dependencias restantes brindan acceso al SDK, API, exportador OTLP y biblioteca de instrumentación.
• Hay una configuración adicional para excluir el módulo spring-boot-starter-logging. Esto evita un mensaje de error de compilación relacionado con log4j-slf4j-impl cannot be present with log4j-to-slf4j.

Configure el SDK con la extensión de configuración automática

Si bien puede configurar el SDK manualmente, le recomendamos utilizar la extensión de configuración automática, ya que agiliza el proceso.

1. Vaya al directorio del código fuente de la aplicación:

   bash

   Copia

   $
   cd newrelic-opentelemetry-examples/getting-started-guides/java/uninstrumented/src/main/java/com/example/demo

2. Abra Application.java.

3. Inserte las líneas resaltadas:

   @SpringBootApplication
   public class Application {
   
       private static volatile OpenTelemetry openTelemetry = OpenTelemetry.noop();
   
       public static void main(String[] args) {
           // Build the SDK auto-configuration extension module
           OpenTelemetrySdk openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.builder()
                   .setResultAsGlobal(false)
                   .build()
                   .getOpenTelemetrySdk();
           Application.openTelemetry = openTelemetrySdk;
   
           SpringApplication.run(Application.class, args);
       }
   
       @Bean
       public OpenTelemetry openTelemetry() {
           return openTelemetry;
       }
   }

   Copia

4. Vaya a nuestra sección de referencia de variables de entorno a continuación para ver qué variables necesita exportar y luego volver a estos pasos.

Añadir instrumentación biblioteca: traza

En Application.java, agregue la instrumentación resaltada para Spring Web MVC registrando un filtro de seguimiento:

@SpringBootApplication
public class Application {

    private static volatile OpenTelemetry openTelemetry = OpenTelemetry.noop();

    public static void main(String[] args) {
        // Build the SDK auto-configuration extension module
        OpenTelemetrySdk openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.builder()
                .setResultAsGlobal(false)
                .build()
                .getOpenTelemetrySdk();
        Application.openTelemetry = openTelemetrySdk;

        SpringApplication.run(Application.class, args);
    }

    @Bean
    public OpenTelemetry openTelemetry() {
        return openTelemetry;
    }

    // Add Spring WebMVC instrumentation by registering a tracing filter
    @Bean
    public Filter webMvcTracingFilter(OpenTelemetry openTelemetry) {
        return SpringWebMvcTelemetry.create(openTelemetry).createServletFilter();
    }
}

Agregar biblioteca de instrumentación: métrica

Genere y recopile métricas sobre su tiempo de ejecución de Java registrando lo siguiente en el archivo Application.java . Inserte las líneas resaltadas a continuación:

@SpringBootApplication
public class Application {

    private static volatile OpenTelemetry openTelemetry = OpenTelemetry.noop();

    public static void main(String[] args) {
        // Build the SDK auto-configuration extension module
        OpenTelemetrySdk openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.builder()
                .setResultAsGlobal(false)
                .build()
                .getOpenTelemetrySdk();
        Application.openTelemetry = openTelemetrySdk;

        // Register runtime metrics instrumentation
        BufferPools.registerObservers(openTelemetrySdk);
        Classes.registerObservers(openTelemetrySdk);
        Cpu.registerObservers(openTelemetrySdk);
        GarbageCollector.registerObservers(openTelemetrySdk);
        MemoryPools.registerObservers(openTelemetrySdk);
        Threads.registerObservers(openTelemetrySdk);

        SpringApplication.run(Application.class, args);
    }

    @Bean
    public OpenTelemetry openTelemetry() {
        return openTelemetry;
    }

    // Add Spring WebMVC instrumentation by registering a tracing filter
    @Bean
    public Filter webMvcTracingFilter(OpenTelemetry openTelemetry) {
        return SpringWebMvcTelemetry.create(openTelemetry).createServletFilter();
    }
}

Agregar biblioteca de instrumentación: log

Esta aplicación de demostración está configurada para usar OpenTelemetryAppender (a través de log4j.xml), que usa GlobalLoggerProvider. La configuración de GlobalLoggerProvider conecta el OpenTelemetryAppender al SDK log que se configura mediante la configuración automática aquí:

1. Abra Application.java.

2. Inserte las siguientes líneas resaltadas.

   @SpringBootApplication
   public class Application {
   
       private static volatile OpenTelemetry openTelemetry = OpenTelemetry.noop();
   
       public static void main(String[] args) {
           // Build the SDK auto-configuration extension module
           OpenTelemetrySdk openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.builder()
                   .setResultAsGlobal(false)
                   .build()
                   .getOpenTelemetrySdk();
           Application.openTelemetry = openTelemetrySdk;
   
           // Set GlobalLoggerProvider, which is used by Log4j2 appender
           GlobalLoggerProvider.set(openTelemetrySdk.getSdkLoggerProvider());
   
           // Register runtime metrics instrumentation
           BufferPools.registerObservers(openTelemetrySdk);
           Classes.registerObservers(openTelemetrySdk);
           Cpu.registerObservers(openTelemetrySdk);
           GarbageCollector.registerObservers(openTelemetrySdk);
           MemoryPools.registerObservers(openTelemetrySdk);
           Threads.registerObservers(openTelemetrySdk);
   
           SpringApplication.run(Application.class, args);
       }
   
       @Bean
       public OpenTelemetry openTelemetry() {
           return openTelemetry;
       }
   
       // Add Spring WebMVC instrumentation by registering a tracing filter
       @Bean
       public Filter webMvcTracingFilter(OpenTelemetry openTelemetry) {
           return SpringWebMvcTelemetry.create(openTelemetry).createServletFilter();
       }
   }

   Copia

3. Cree un directorio llamado resources en Uninstrumented/src/main.

4. En este nuevo directorio, cree un archivo llamado log4j2.xml con el siguiente contenido:

   <?xml version="1.0" encoding="UTF-8"?>
   <Configuration status="WARN" packages="io.opentelemetry.instrumentation.log4j.appender.v2_17">
     <Appenders>
       <Console name="ConsoleAppender" target="SYSTEM_OUT" follow="true">
         <PatternLayout pattern="%d{yyyy-mm-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
       </Console>
       <OpenTelemetry name="OpenTelemetryAppender" />
     </Appenders>
     <Loggers>
       <Root level="info">
         <AppenderRef ref="OpenTelemetryAppender" />
         <AppenderRef ref="ConsoleAppender" />
       </Root>
     </Loggers>
   </Configuration>

   Copia

   Sugerencia

   La sección packages=... de esta línea permite a Log4J encontrar y configurar el OpenTelemetryAppender. El código fuente está en el repositorio de OpenTelemetry y se agregó como una dependencia a través de io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17)

Instrumentación de traza personalizada: Crear constantes de atributo span

Cada traza se compone de tramos, que representan una unidad de trabajo lógica o una operación dentro de una solicitud particular. El siguiente código lo demuestra:

• Constantes estáticas para contener claves de atributos que se pueden usar para proporcionar Insights a nivel de solicitud en sus intervalos.

• Cómo inicializar un rastreador, que crea tramos

  Inserte las siguientes líneas resaltadas en Controller.java:

  @RestController
  public class Controller {
  
      // Attribute constants
      private static final AttributeKey<Long> ATTR_N = AttributeKey.longKey("fibonacci.n");
      private static final AttributeKey<Long> ATTR_RESULT = AttributeKey.longKey("fibonacci.result");
  
      private final Tracer tracer;
  
      @Autowired
      Controller(OpenTelemetry openTelemetry) {
          // Initialize tracer
          tracer = openTelemetry.getTracer(Controller.class.getName());
      }
  
      @GetMapping(value = "/fibonacci")
      . . .
  }

  Copia

Traza instrumentación personalizada: Crear un tramo personalizado

Puede crear los intervalos que desee y depende de usted anotar sus intervalos con atributos en operaciones específicas. El atributo que establezca proporcionará contexto adicional sobre la operación específica que está rastreando, como resultados o propiedades de la operación.

1. En Controller.java, inserte estas líneas resaltadas para iniciar un nuevo intervalo llamado fibonacci que hace lo siguiente:

   • Captura datos sobre la ejecución de este método.
   • Establece un atributo que almacena el valor de n de la solicitud del usuario.

   private long fibonacci(long n) {
       // Start a new span and set your first attribute
       var span = tracer.spanBuilder("fibonacci").setAttribute(ATTR_N, n).startSpan();
       . . .
   }

   Copia

2. Agregue detalles granulares a su código agregando un atributo a su intervalo para almacenar información sobre solicitudes exitosas:

   private long fibonacci(long n) {
       // Start a new span and set your first attribute
       var span = tracer.spanBuilder("fibonacci").setAttribute(ATTR_N, n).startSpan();
   
       try {
           if (n < 1 || n > 90) {
               throw new IllegalArgumentException("n must be 1 <= n <= 90.");
           }
   
           long result = 1;
           if (n > 2) {
           long a = 0;
           long b = 1;
   
           for (long i = 1; i < n; i++) {
               result = a + b;
               a = b;
               b = result;
           }
           // Set a span attribute to capture information about successful requests
           span.setAttribute(ATTR_RESULT, last);
           return last;
       } catch (IllegalArgumentException e) {
           throw e;
       }
   }

   Copia

Instrumentación de traza personalizada: Registrar una excepción

Es posible que desee registrar las excepciones a medida que ocurren. Le recomendamos hacer esto junto con la configuración del estado del intervalo. Primero, establezca su intervalo como el intervalo actual, establezca el código de estado en error en caso de una excepción y luego finalice el intervalo:

private long fibonacci(long n) {
    // Start a new span and set your first attribute
    var span = tracer.spanBuilder("fibonacci").setAttribute(ATTR_N, n).startSpan();

    // Set the span as the current span
    try (var scope = span.makeCurrent()) {
        if (n < 1 || n > 90) {
            throw new IllegalArgumentException("n must be 1 <= n <= 90.");
        }

        long result = 1;
        if (n > 2) {
            long a = 0;
            long b = 1;

            for (long i = 1; i < n; i++) {
                result = a + b;
                a = b;
                b = result;
            }
        }
        // Set a span attribute to capture information about successful requests
        span.setAttribute(ATTR_RESULT, result);
        return result;
    } catch (IllegalArgumentException e) {
        // Record the exception and set the span status
        span.recordException(e).setStatus(StatusCode.ERROR, e.getMessage());
        throw e;
    } finally {
        // End the span
        span.end();
    }
}

Este método genera un IllegalArgumentException si un usuario proporciona una entrada no válida. Cuando esto sucede, la excepción se registra como un evento en el intervalo y el estado del intervalo se establecerá en ERROR. El mensaje de excepción se captura como descripción del estado. La excepción se registrará como un evento en el lapso donde ocurra.

Finalmente, en handleException() en la clase ErrorHandler , establezca el estado del intervalo en ERROR con estas líneas resaltadas:

@ControllerAdvice
private static class ErrorHandler {

    @ExceptionHandler({
        IllegalArgumentException.class,
        MissingServletRequestParameterException.class,
        HttpRequestMethodNotSupportedException.class
    })
    public ResponseEntity<Object> handleException(Exception e) {
        // Set the span status and description
        Span.current().setStatus(StatusCode.ERROR, e.getMessage());
        return new ResponseEntity<>(Map.of("message", e.getMessage()), HttpStatus.BAD_REQUEST);
    }
}

Como en el paso anterior, esto establece el código de estado del intervalo si el usuario ingresa un número no válido. Sin embargo, debido a que esto sucede en el controlador de excepciones, en lugar de en fibonacci(), el intervalo actual es el principal de intervalo de la solicitud. Este tramo principal proviene de la instrumentación Spring Web MVC agregada mediante el filtro en la clase de aplicación. Ahora, cuando el extremo de su aplicación genere una excepción, tanto el tramo principal como el tramo secundario tendrán un estado de tramo de ERROR.

Instrumentación métrica personalizada: Añadir un contador métrica personalizada

Las métricas son un tipo telemetry data que son realmente útiles porque combinan mediciones individuales en agregaciones y producen datos que son constantes en función de la carga del sistema. Puede utilizar estos datos junto con intervalos para ayudar a detectar tendencias y proporcionar telemetría en tiempo de ejecución de la aplicación. También puede anotar cualquier métrica con un atributo para ayudar a describir qué subdivisión de las medidas representa la métrica.

La API de OpenTelemetry métrica define una serie de instrumentados, que registran mediciones que son agregadas por el SDK de métrica y exportadas fuera de proceso. Hay dos tipos de instrumentado:

• Síncrono: Estos instrumentados registran las mediciones a medida que ocurren.

• Asincrónico: Estos instrumentados registran un callback, el cual se invoca solo una vez por colección y no tiene contexto asociado

  Sugerencia

  Si tiene alguna pregunta sobre el estado de la métrica en el proyecto OpenTelemetry, consulte los estados de las señales.

  Complete lo siguiente para agregar un contador personalizado:

1. Cree una instancia de un atributo booleano para su métrica personalizada e inicialice una métrica instrumentada.

   Sugerencia

   En este caso, estamos usando un LongCounter, que registra solo valores positivos y es útil para contar cosas, como la cantidad de bytes enviados a través de una red. De forma predeterminada, las medidas de los contadores se agregan a sumas monótonas (siempre crecientes).

   @RestController
   public class Controller {
   
       // Attribute constants
       private static final AttributeKey<Long> ATTR_N = AttributeKey.longKey("fibonacci.n");
       private static final AttributeKey<Long> ATTR_RESULT = AttributeKey.longKey("fibonacci.result");
       private static final AttributeKey<Boolean> ATTR_VALID_N = AttributeKey.booleanKey("fibonacci.valid.n");
   
       private final Tracer tracer;
       private final LongCounter fibonacciInvocations;
   
       @Autowired
       Controller(OpenTelemetry openTelemetry) {
           // Initialize tracer
           tracer = openTelemetry.getTracer(Controller.class.getName());
           // Initialize instrument
           Meter meter = openTelemetry.getMeter(Controller.class.getName());
           fibonacciInvocations = meter
               .counterBuilder("fibonacci.invocations")
               .setDescription("Measures the number of times the fibonacci method is invoked.")
               .build();
       }
       . . .
   }

   Copia

2. Inserte las siguientes líneas resaltadas para que su contador personalizado pueda capturar entradas válidas e inválidas, así como la cantidad de veces que ocurre cada una.

   private long fibonacci(long n) {
       // Start a new span and set your first attribute
       var span = tracer.spanBuilder("fibonacci").setAttribute(ATTR_N, n).startSpan();
   
       // Set the span as the current span
       try (var scope = span.makeCurrent()) {
           if (n < 1 || n > 90) {
               throw new IllegalArgumentException("n must be 1 <= n <= 90.");
           }
   
           long result = 1;
           if (n > 2) {
               long a = 0;
               long b = 1;
   
               for (long i = 1; i < n; i++) {
                   result = a + b;
                   a = b;
                   b = result;
               }
           }
           // Set a span attribute to capture information about successful requests
           span.setAttribute(ATTR_RESULT, result);
           // Counter to increment the number of times a valid input is recorded
           fibonacciInvocations.add(1, Attributes.of(ATTR_VALID_N, true));
           return result;
       } catch (IllegalArgumentException e) {
           // Record the exception and set the span status
           span.recordException(e).setStatus(StatusCode.ERROR, e.getMessage());
           // Counter to increment the number of times an invalid input is recorded
           fibonacciInvocations.add(1, Attributes.of(ATTR_VALID_N, false));
           throw e;
       } finally {
           // End the span
           span.end();
       }
   }

   Copia

Instrumentación log personalizados

El estado de la señal de log en OpenTelemetry Java es actualmente experimental. Los mensajes de log son administrados por el controlador raíz de su aplicación, que enviará logs de nivel INFO y superiores a la consola de forma predeterminada. Sin embargo, puede modificar el comportamiento logger cambiando el nivel de logging, incluso para clases específicas, o instalando un controlador o filtro personalizado.

Inicializar el logger

Como se indicó anteriormente, esto es de la biblioteca java.util.logging . El logger no es un componente de OpenTelemetry, pero la aplicación se ha configurado para enviar el log de Log4j al SDK log OpenTelemetry:

@RestController
public class Controller {

    // Logger (note that this is not an OTel component)
    private static final Logger LOGGER = LogManager.getLogger(Controller.class);

    // Attribute constants
    private static final AttributeKey<Long> ATTR_N = AttributeKey.longKey("fibonacci.n");
    private static final AttributeKey<Long> ATTR_RESULT = AttributeKey.longKey("fibonacci.result");
    private static final AttributeKey<Boolean> ATTR_VALID_N = AttributeKey.booleanKey("fibonacci.valid.n");
    . . .
}

Agregar mensaje de log personalizado [#cust-log-messages]

Una vez que haya inicializado el logger, puede utilizarlo para logger :

• El resultado de una entrada válida, junto con el valor de ese resultado.
• Cuando no se registró ninguna salida

Inserte las siguientes líneas resaltadas:

private long fibonacci(long n) {
    // Start a new span and set your first attribute
    var span = tracer.spanBuilder("fibonacci").setAttribute(ATTR_N, n).startSpan();

    // Set the span as the current span
    try (var scope = span.makeCurrent()) {
        if (n < 1 || n > 90) {
            throw new IllegalArgumentException("n must be 1 <= n <= 90.");
        }

        long result = 1;
        if (n > 2) {
            long a = 0;
            long b = 1;

            for (long i = 1; i < n; i++) {
                result = a + b;
                a = b;
                b = result;
            }
        }
        // Set a span attribute to capture information about successful requests
        span.setAttribute(ATTR_RESULT, result);
        // Counter to increment the number of times a valid input is recorded
        fibonacciInvocations.add(1, Attributes.of(ATTR_VALID_N, true));
        // Log the result of a valid input
        LOGGER.info("Compute fibonacci(" + n + ") = " + result);
        return result;
    } catch (IllegalArgumentException e) {
        // Record the exception and set the span status
        span.recordException(e).setStatus(StatusCode.ERROR, e.getMessage());
        // Counter to increment the number of times an invalid input is recorded
        fibonacciInvocations.add(1, Attributes.of(ATTR_VALID_N, false));
        // Log when no output was recorded
        LOGGER.info("Failed to compute fibonacci(" + n + ")");
        throw e;
    } finally {
        // End the span
        span.end();
    }
}

Ejercite la aplicación para generar algo de tráfico.

¡Estás listo para enviar algunos datos a New Relic!

1. Vaya al directorio getting-started-guides/java y cree y ejecute la aplicación con este comando:

   • Mac OS:

     bash

     Copia

     $
     ./gradlew bootRun

   • Potencia Shell:

     bash

     Copia

     $
     .\gradlew.bat build

     Sugerencia

     Si su terminal muestra Spring ASCII, significa que su aplicación se ha creado correctamente y se está ejecutando:

     

2. Genere tráfico desde la aplicación abriendo una nueva terminal en el directorio getting-started-guides/java/Uninstrumented y ejecutando el generador de carga:

   • Mac OS:

     bash

     Copia

     $
     ./load-generator.sh

   • Potencia Shell:

     bash

     Copia

     $
     .\load-generator.ps1

   Sugerencia

   Alternativamente, puede llegar al extremo en el browser en esta URL: http://localhost:8080/fibonacci?n=INSERT_A_VALUE. Reemplace INSERT_A_VALUE con un valor de 1 a 90. Para generar un error, inserte un número entero fuera del rango válido.

3. Ahora que ha enviado algunos datos a New Relic, consulte nuestras instrucciones sobre cómo ver los datos en la UI.