Tutoriais OpenTelemetry: instrumento um exemplo de aplicativo Java

Baixe o aplicativo de demonstração

Se você ainda não baixou nosso aplicativo de demonstração, execute o seguinte:

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

Instalar dependência

Para adicionar dependência:

1. Vá para o diretório do aplicativo.

   bash

   Copiar

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

2. Abra build.gradle.

3. Adicione os seguintes itens destacados ao bloco dependencies (talvez seja necessário rolar para baixo dentro do bloco 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'
   }

   Copiar

   Notas:

• A dependência bom (lista de materiais) é usada para sincronizar versões de dependência para um ecossistema específico. Como o OpenTelemetry publica muitos componentes Java, eles ajudam a garantir que todas as versões sejam sincronizadas, quer você use apenas algumas ou muitas delas.
• As dependências restantes fornecem acesso ao SDK, API, exportador OTLP e biblioteca de instrumentação.
• Há uma configuração adicional para excluir o módulo spring-boot-starter-logging. Isso evita uma mensagem de erro de compilação relacionada a log4j-slf4j-impl cannot be present with log4j-to-slf4j.

Configure o SDK com a extensão autoconfigure

Embora você possa configurar o SDK manualmente, recomendamos usar a extensão autoconfigure, pois ela agiliza o processo.

1. Vá para o diretório do código-fonte do aplicativo:

   bash

   Copiar

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

2. Abra Application.java.

3. Insira as linhas destacadas:

   @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;
       }
   }

   Copiar

4. Vá para nossa seção de referência de variáveis de ambiente abaixo para ver quais variáveis você precisa exportar e depois retorne a estas etapas.

Adicionar biblioteca de instrumentação: trace

Em Application.java, adicione a instrumentação destacada para Spring Web MVC registrando um filtro de rastreamento:

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

Adicionar biblioteca de instrumentação: métrica

Gere e colete métricas sobre seu tempo de execução Java registrando o seguinte no arquivo Application.java . Insira as linhas destacadas abaixo:

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

Adicionar biblioteca de instrumentação: log

Este aplicativo de demonstração está configurado para usar o OpenTelemetryAppender (via log4j.xml), que usa GlobalLoggerProvider. A configuração de GlobalLoggerProvider conecta o OpenTelemetryAppender ao SDK log que é configurado usando autoconfigure aqui:

1. Abra Application.java.

2. Insira as seguintes linhas destacadas.

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

   Copiar

3. Crie um diretório chamado resources em Uninstrumented/src/main.

4. Neste novo diretório, crie um arquivo chamado log4j2.xml com o seguinte conteúdo:

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

   Copiar

   Dica

   A seção packages=... desta linha permite que o Log4J encontre e configure o OpenTelemetryAppender. O código-fonte está no repositório OpenTelemetry e foi adicionado como uma dependência via io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17)

Instrumentação trace customizada: Criar constantes de atributo de span

Cada trace é composto por spans, que representam uma unidade lógica de trabalho ou uma operação dentro de uma solicitação específica. O código abaixo demonstra:

• Constantes estáticas para armazenar chaves de atributo que podem ser usadas para fornecer insights em nível de solicitação em seus períodos

• Como inicializar um Tracer, que cria spans

  Insira as seguintes linhas destacadas em 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")
      . . .
  }

  Copiar

Instrumentação trace customizada: Crie um intervalo customizado

Você pode criar os spans que desejar e cabe a você anotar seus spans com atributos em operações específicas. O atributo definido fornecerá contexto adicional sobre a operação específica que você está acompanhando, como resultados ou propriedades da operação.

1. Em Controller.java, insira essas linhas destacadas para iniciar um novo intervalo chamado fibonacci que faz o seguinte:

   • Captura dados sobre a execução deste método
   • Define um atributo que armazena o valor de n da solicitação do usuário

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

   Copiar

2. Adicione detalhes granulares ao seu código adicionando um atributo ao seu intervalo para armazenar informações sobre solicitações bem-sucedidas:

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

   Copiar

Instrumentação trace customizada: Registrar uma exceção

Você pode querer registrar as exceções à medida que elas acontecem. Recomendamos que você faça isso em conjunto com a configuração do status do intervalo. Primeiro, defina seu intervalo como o intervalo atual, defina o código de status como erro no caso de uma exceção e, em seguida, encerre o 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 gera um IllegalArgumentException se um usuário fornecer uma entrada inválida. Quando isso acontece, a exceção é registrada como um evento no intervalo e o status do intervalo será definido como ERROR. A mensagem de exceção é capturada como a descrição do status. A exceção será registrada como um evento no intervalo onde ocorre.

Por fim, em handleException() na classe ErrorHandler , defina o status do intervalo como ERROR com estas linhas destacadas:

@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 na etapa anterior, isso define o código de status do intervalo se o usuário inserir um número inválido. No entanto, como isso acontece no manipulador de exceções, e não em fibonacci(), o intervalo atual é o intervalo pai da solicitação. Esse span pai vem da instrumentação Spring Web MVC adicionada por meio do filtro na classe aplicativo. Agora, quando o endpoint do seu aplicativo gerar uma exceção, tanto o span pai quanto o span filho terão um status de span de ERROR.

Instrumentação métrica personalizada: Adicionar um contador de métrica personalizado

Métricas são um tipo de dados de telemetria realmente úteis porque combinam medições individuais em agregações e produzem dados constantes em função da carga do sistema. Você pode usar esses dados em conjunto com períodos para ajudar a identificar tendências e fornecer telemetria de tempo de execução do aplicativo. Você também pode anotar qualquer métrica com um atributo para ajudar a descrever qual subdivisão das medidas a métrica representa.

A API OpenTelemetry métrica define uma série de instrumentos, que registram medidas que são agregadas pelo SDK métrica e exportadas fora do processo. Existem dois tipos de instrumento:

• Síncrono: Este instrumento registra as medições à medida que ocorrem

• Assíncrono: Este instrumento registra um retorno de chamada, que é invocado apenas uma vez por coleta e não possui contexto associado

  Dica

  Se você tiver alguma dúvida sobre o status da métrica no projeto OpenTelemetry, consulte os status do sinal.

  Conclua o seguinte para adicionar um contador personalizado:

1. Instancie um atributo booleano para sua métrica personalizada e inicialize um instrumento métrico.

   Dica

   Nesse caso, estamos usando um LongCounter, que registra apenas valores positivos e é útil para contar coisas, como o número de bytes enviados por uma rede. Por padrão, as medidas do contador são agregadas em somas monotônicas (sempre crescentes).

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

   Copiar

2. Insira as seguintes linhas destacadas para que seu contador personalizado possa capturar entradas válidas e inválidas, bem como o número de vezes que cada uma ocorre.

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

   Copiar

Instrumentação de log customizada

O status do sinal de log no OpenTelemetry Java é atualmente experimental. mensagem do log são gerenciados pelo manipulador raiz em seu aplicativo, que enviará log de nível INFO e superior para o console por padrão. No entanto, você pode modificar o comportamento do agente alterando o nível de log, inclusive para classes específicas, ou instalando um manipulador ou filtro customizado.

Inicialize o agente

Conforme afirmado anteriormente, isso é da biblioteca java.util.logging . O agente não é um componente do OpenTelemetry, mas o aplicativo foi configurado para enviar o Log4j para o SDK log do 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");
    . . .
}

Adicionar mensagem personalizada do log [#cust-log-messages]

Depois de inicializar o agente, você poderá usá-lo para registrar:

• O resultado de uma entrada válida, juntamente com o valor desse resultado
• Quando nenhuma saída foi gravada

Insira as seguintes linhas destacadas:

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

Exercite o aplicativo para gerar algum tráfego

Você está pronto para enviar alguns dados para a New Relic!

1. Vá para o diretório getting-started-guides/java e crie e execute o aplicativo com este comando:

   • Mac OS:

     bash

     Copiar

     $
     ./gradlew bootRun

   • PowerShell:

     bash

     Copiar

     $
     .\gradlew.bat build

     Dica

     Se o seu terminal exibir o Spring ASCII, significa que seu aplicativo foi compilado com sucesso e está em execução:

     

2. Gere tráfego do aplicativo abrindo um novo terminal no diretório getting-started-guides/java/Uninstrumented e executando o gerador de carga:

   • Mac OS:

     bash

     Copiar

     $
     ./load-generator.sh

   • PowerShell:

     bash

     Copiar

     $
     .\load-generator.ps1

   Dica

   Alternativamente, você pode acessar o endpoint no browser neste URL: http://localhost:8080/fibonacci?n=INSERT_A_VALUE. Substitua INSERT_A_VALUE por um valor de 1 a 90. Para gerar um erro, insira um número inteiro fora do intervalo válido.

3. Agora que você enviou alguns dados para o New Relic, veja nossas instruções sobre como visualizar os dados na interface.