OpenTelemetry 튜토리얼: 샘플 Java 앱 계측

데모 애플리케이션 다운로드

데모 앱을 아직 다운로드하지 않은 경우 다음을 실행하십시오.

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

종속성 설치

종속성을 추가하려면:

1. 애플리케이션 디렉토리로 이동합니다.

   bash

   복사

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

2. build.gradle 을(를) 엽니다.

3. 다음 강조 표시된 항목을 dependencies 블록에 추가합니다(코드 블록 내에서 아래로 스크롤해야 할 수 있음).

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

   복사

   메모:

• bom (재료 명세서) 종속성은 특정 생태계에 대한 종속성 버전을 동기화하는 데 사용됩니다. OpenTelemetry는 많은 Java 구성 요소를 게시하므로 이러한 구성 요소를 사용하는 경우 몇 개만 사용하든 많이 사용하든 모든 버전을 동기화하는 데 도움이 됩니다.
• 나머지 종속성은 SDK, API, OTLP 내보내기 및 계측 라이브러리에 대한 액세스를 제공합니다.
• spring-boot-starter-logging 모듈을 제외하기 위한 추가 설정이 있습니다. 이것은 log4j-slf4j-impl cannot be present with log4j-to-slf4j 와 관련된 빌드 오류 메시지를 방지합니다.

자동 구성 확장을 사용하여 SDK 구성

SDK를 수동으로 구성할 수 있지만 프로세스를 간소화하는 자동 구성 확장을 사용하는 것이 좋습니다.

1. 앱의 소스 코드 디렉터리로 이동합니다.

   bash

   복사

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

2. Application.java 을(를) 엽니다.

3. 강조 표시된 줄을 삽입합니다.

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

   복사

4. 아래의 환경 변수 참조 섹션 으로 이동하여 내보내야 하는 변수를 확인한 다음 이 단계로 돌아갑니다.

계측 라이브러리 추가: 추적

Application.java 에서 추적 필터를 등록하여 Spring Web MVC에 대해 강조 표시된 계측을 추가합니다.

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

계측 라이브러리 추가: 측정항목

Application.java 파일에 다음을 등록하여 Java 런타임에 대한 측정항목을 생성하고 수집합니다. 아래에 강조표시된 줄을 삽입합니다.

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

계측 라이브러리 추가: 로그

이 데모 애플리케이션은 GlobalLoggerProvider 를 사용하는 OpenTelemetryAppender ( log4j.xml 을 통해)를 사용하도록 구성됩니다. GlobalLoggerProvider 설정은 여기에서 자동 구성을 사용하여 구성된 로그 SDK에 OpenTelemetryAppender 를 연결합니다.

1. Application.java 을(를) 엽니다.

2. 다음 강조 표시된 줄을 삽입합니다.

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

   복사

3. Uninstrumented/src/main 에 resources 라는 디렉터리를 만듭니다.

4. 이 새 디렉터리에서 다음 콘텐츠가 포함된 log4j2.xml 라는 파일을 만듭니다.

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

   복사

   팁

   이 줄의 packages=... 섹션을 통해 Log4J는 OpenTelemetryAppender 을 찾고 구성할 수 있습니다. 소스 코드는 OpenTelemetry 저장소에 있으며 io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17 를 통해 종속성으로 추가되었습니다.)

사용자 정의 추적 계측: 범위 특성 상수 만들기

각 추적은 논리적 작업 단위 또는 특정 요청 내의 작업을 나타내는 범위로 구성됩니다. 아래 코드는 다음을 보여줍니다.

• 스팬에서 요청 수준 통찰력을 제공하는 데 사용할 수 있는 속성 키를 보유하는 정적 상수

• 범위를 생성하는 Tracer 를 초기화하는 방법

  다음 강조 표시된 줄을 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")
      . . .
  }

  복사

커스텀 추적 계측: 커스텀 범위 만들기

원하는 스팬은 무엇이든 만들 수 있으며 특정 작업에 대한 속성으로 스팬에 주석을 추가하는 것은 사용자의 몫입니다. 설정한 속성은 결과 또는 작업 속성과 같이 추적 중인 특정 작업에 대한 추가 컨텍스트를 제공합니다.

1. Controller.java 에서 강조 표시된 줄을 삽입하여 다음을 수행하는 fibonacci 라는 새 범위를 시작합니다.

   • 이 메서드의 실행에 대한 데이터를 캡처합니다.
   • 사용자 요청에서 n 값을 저장하는 속성을 설정합니다.

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

   복사

2. 성공적인 요청에 대한 정보를 저장하기 위해 스팬에 속성을 추가하여 코드에 세분화된 세부 정보를 추가합니다.

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

   복사

사용자 정의 추적 계측: 예외 기록

예외가 발생하면 기록할 수 있습니다. 스팬 상태 설정과 함께 이 작업을 수행하는 것이 좋습니다. 먼저 스팬을 현재 스팬으로 설정하고 예외 발생 시 상태 코드를 오류로 설정한 다음 스팬을 종료합니다.

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

이 메서드는 사용자가 잘못된 입력을 제공하는 경우 IllegalArgumentException 를 발생시킵니다. 이 경우 예외가 스팬에 이벤트로 기록되고 스팬의 상태가 ERROR 로 설정됩니다. 예외 메시지는 상태 설명으로 캡처됩니다. 예외는 발생하는 범위에서 이벤트로 기록됩니다.

마지막으로 ErrorHandler 클래스의 handleException() 에서 다음 강조표시된 줄을 사용하여 스팬의 상태를 ERROR 로 설정합니다.

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

이전 단계에서와 같이 사용자가 잘못된 숫자를 입력하면 스팬의 상태 코드를 설정합니다. 그러나 이것은 fibonacci() 가 아닌 예외 핸들러에서 발생하기 때문에 현재 스팬은 요청의 상위 스팬입니다. 이 상위 범위는 Application 클래스의 필터를 통해 추가된 Spring Web MVC 계측에서 가져옵니다. 이제 애플리케이션 엔드포인트에서 예외가 발생하면 상위 스팬과 하위 스팬 모두 스팬 상태가 ERROR 입니다.

사용자 정의 메트릭 계측: 사용자 정의 메트릭 카운터 추가

메트릭은 개별 측정을 집계로 결합하고 시스템 부하의 함수로 일정한 데이터를 생성하기 때문에 정말 유용한 원격 분석 데이터 유형입니다. 이 데이터를 스팬과 함께 사용하여 추세를 파악하고 애플리케이션 런타임 원격 분석을 제공할 수 있습니다. 메트릭이 나타내는 측정의 하위 구분을 설명하는 데 도움이 되는 속성으로 메트릭에 주석을 달 수도 있습니다.

OpenTelemetry 메트릭 API는 메트릭 SDK에서 집계하고 외부 프로세스로 내보낸 측정값을 기록하는 여러 계측기를 정의합니다. 악기에는 두 가지 유형이 있습니다.

• 동기식: 이 계측기는 측정이 발생하는 대로 기록합니다.

• 비동기식: 이러한 도구는 컬렉션당 한 번만 호출되고 관련 컨텍스트가 없는 콜백을 등록합니다.

  팁

  OpenTelemetry 프로젝트의 메트릭 상태에 대한 질문이 있는 경우 신호 상태 를 참조하십시오.

  사용자 정의 카운터를 추가하려면 다음을 완료하십시오.

1. 사용자 정의 메트릭에 대한 부울 속성을 인스턴스화하고 메트릭 도구를 초기화합니다.

   팁

   이 경우에는 양수 값만 기록하고 네트워크를 통해 전송된 바이트 수와 같은 항목을 계산하는 데 유용한 LongCounter 를 사용하고 있습니다. 기본적으로 카운터 측정값은 단조로운(항상 증가하는) 합계로 집계됩니다.

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

   복사

2. 사용자 정의 카운터가 유효한 입력과 유효하지 않은 입력 및 각각의 발생 횟수를 캡처할 수 있도록 다음 강조 표시된 줄을 삽입하십시오.

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

   복사

사용자 정의 로그 계측

OpenTelemetry Java의 로그 신호 상태는 현재 실험적 입니다. 로그 메시지는 기본적으로 콘솔에 INFO 수준 이상의 로그를 보내는 앱의 루트 핸들러에서 관리합니다. 그러나 특정 클래스를 포함하여 로깅 수준을 변경하거나 사용자 지정 처리기 또는 필터를 설치하여 로거 동작을 수정할 수 있습니다.

로거 초기화

이전에 언급했듯이 이것은 java.util.logging 라이브러리에서 가져온 것입니다. 로거는 OpenTelemetry 구성 요소가 아니지만 애플리케이션은 OpenTelemetry Log SDK에 Log4j 로그를 보내도록 구성되었습니다.

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

사용자 지정 로그 메시지 추가 [#cust-log-messages]

로거를 초기화하면 로거를 사용하여 다음을 기록할 수 있습니다.

• 해당 결과의 값과 함께 유효한 입력의 결과
• 출력이 기록되지 않은 경우

다음 강조 표시된 줄을 삽입합니다.

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

앱을 실행하여 트래픽을 생성하세요.

New Relic에 일부 데이터를 보낼 준비가 되었습니다!

1. getting-started-guides/java 디렉터리로 이동하고 다음 명령을 사용하여 앱을 빌드하고 실행합니다.

   • 맥 OS:

     bash

     복사

     $
     ./gradlew bootRun

   • 파워셸:

     bash

     복사

     $
     .\gradlew.bat build

     팁

     터미널에 Spring ASCII가 표시되면 앱이 성공적으로 빌드되었고 실행 중임을 의미합니다.

     

2. getting-started-guides/java/Uninstrumented 디렉터리에서 새 터미널을 열고 부하 생성기를 실행하여 애플리케이션에서 트래픽을 생성합니다.

   • 맥 OS:

     bash

     복사

     $
     ./load-generator.sh

   • 파워셸:

     bash

     복사

     $
     .\load-generator.ps1

   팁

   또는 다음 URL에서 브라우저의 엔드포인트에 도달할 수 있습니다: http://localhost:8080/fibonacci?n=INSERT_A_VALUE . INSERT_A_VALUE 을 1에서 90 사이의 값으로 바꿉니다. 오류를 생성하려면 유효한 범위 밖의 정수를 삽입하십시오.

3. 일부 데이터를 New Relic에 전송했으므로 이제 UI에서 데이터 보기에 대한 지침을 참조하십시오.