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に関連するビルド エラー メッセージが表示されなくなります。

autoconfigure 拡張機能を使用して 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を設定すると、ここで autoconfigure を使用して構成された Log 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 によって集計され、アウト オブ プロセスでエクスポートされる測定値を記録する多数の計測器を定義します。器具には次の 2 種類があります。

• 同期: これらの計測器は、発生時に測定値を記録します。

• 非同期: これらの計測器はコールバックを登録します。これはコレクションごとに 1 回だけ呼び出され、関連付けられたコンテキストはありません。

  ヒント

  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ライブラリからのものです。Logger は OpenTelemetry コンポーネントではありませんが、アプリケーションは Log4j ログを OpenTelemetry Log SDK に送信するように構成されています。

@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 でデータを表示する手順を参照してください。