OpenTelemetry Collectorをインストールする

1. はじめに

OpenTelemetry Collector は、インフラストラクチャーとアプリケーションを計装するためのコアコンポーネントです。 その役割は収集と送信です：

• インフラストラクチャーのメトリクス（ディスク、CPU、メモリなど）
• Application Performance Monitoring（APM）のトレース情報
• プロファイリングに関するデータ
• ホストおよびアプリケーションのログ

Splunk Observability Cloud では、インフラストラクチャーとアプリケーションの両方で Collector のセットアップを案内するウィザードを提供しています。デフォルトでは、ウィザードはコレクターのインストールのみを行うコマンドのみを提供します。

2. 環境変数を設定する

すでに Splunk IM ワークショップを終了している場合は、既存の環境変数を利用することができます。そうでない場合は、ACCESS_TOKENとREALMの環境変数を設定して、OpenTelemetry Collector のインストールコマンドを実行していきます。

例えば、Realm が us1 の場合、export REALM=us1 と入力し、eu0 の場合は export REALM=eu0 と入力します。

export ACCESS_TOKEN="<replace_with_O11y-Workshop-ACCESS_TOKEN>"

export REALM="<replace_with_REALM>"

helm delete splunk-otel-collector

3. OpenTelemetry Collector をインストールする

次に、Collector をインストールします。インストールスクリプトに渡される追加のパラメータは --deployment-environment です。

curl -sSL https://dl.signalfx.com/splunk-otel-collector.sh > /tmp/splunk-otel-collector.sh && \
sudo sh /tmp/splunk-otel-collector.sh --deployment-environment $(hostname)-petclinic --realm $REALM -- $ACCESS_TOKEN

sudo sed -i 's/gcp, ecs, ec2, azure, system/system, gcp, ecs, ec2, azure/g' /etc/otel/collector/agent_config.yaml

sudo systemctl restart splunk-otel-collector

インストールが完了したら、Splunk Observability の Hosts with agent installed ダッシュボードに移動して、Dashboards → Hosts with agent installed からホストのデータを確認してみましょう。

ダッシュボードのフィルタを使用して host.nameを選択し、仮想マシンのホスト名を入力または選択します。ホストのデータが表示されたら、APM コンポーネントを使用する準備が整いました。

OpenTelemetry Javaエージェントをインストールする

1. Spring PetClinic アプリケーションを動かす

APMをセットアップするためにまず必要なのは…そう、アプリケーションです！この演習では、Spring PetClinicアプリケーションを使用します。これはSpringフレームワーク（Spring Boot）で作られた、非常に人気のあるサンプルJavaアプリケーションです。

まずはPetClinicリポジトリをクローンし、そして、アプリケーションをコンパイル、ビルド、パッケージ、テストしていきます。

git clone https://github.com/spring-projects/spring-petclinic

spring-petclinic ディレクトリに移動します:

cd spring-petclinic

PetClinic が使用する MySQL データベースを起動します:

docker run -d -e MYSQL_USER=petclinic -e MYSQL_PASSWORD=petclinic -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=petclinic -p 3306:3306 docker.io/biarms/mysql:5.7

そして、Splunk版のOpenTelemetry Java APMエージェントをダウンロードしておきましょう。

curl -L https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar \
-o splunk-otel-javaagent.jar

次に、mavenコマンドを実行してPetClinicをコンパイル/ビルド/パッケージ化します:

./mvnw package -Dmaven.test.skip=true

そして、以下のコマンドでアプリケーションを実行することができます:

java -javaagent:./splunk-otel-javaagent.jar \
-Dserver.port=8083 \
-Dotel.service.name=$(hostname).service \
-Dotel.resource.attributes=deployment.environment=$(hostname),version=0.314 \
-Dsplunk.profiler.enabled=true \
-Dsplunk.profiler.memory.enabled=true \
-Dsplunk.metrics.enabled=true \
-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql

アプリケーションが動作しているかどうかは、http://<VM_IP_ADDRESS>:8083 にアクセスして確認することができます。 次に、トラフィックを生成し、クリックしまくり、エラーを生成し、ペットを追加するなどしてください。

• -Dotel.service.name=$(hostname).service では、アプリケーションの名前を定義しています。サービスマップ上のアプリケーションの名前等に反映されます。
• -Dotel.resource.attributes=deployment.environment=$(hostname),version=0.314 では、Environmentと、versionを定義しています。
  • deployment.environment=$(hostname) は、Splunk APM UIの上部「Environment」に反映されます。
  • version=0.314 はここでは、アプリケーションのバージョンを示しています。トレースをドリルダウンしたり、サービスマップの Breakdown の機能で分析したり、Tag Spotlightを開くと version 毎のパフォーマンス分析が使えます。
• -Dsplunk.profiler.enabled=true および splunk.profiler.memory.enabled=true では、CPUとメモリのプロファイリングを有効にしています。Splunk APM UIから、AlwaysOn Profilingを開いてみてください。
• -Dsplunk.metrics.enabled=true では、メモリやスレッドなどJVMメトリクスの送信を有効にしています。Dashboardsから、APM java servicesを開いてみてください。

その後、Splunk APM UIにアクセスして、それぞれのテレメトリーデータを確認してみましょう！

次のセクションではカスタム計装を追加して、OpenTelemetryでは何ができるのか、さらに見ていきます。

マニュアル計装

1. 依存ライブラリを追加する

前のセクション足したような、プロセス全体に渡る属性は便利なのですが、ときにはさらに、リクエストの内容に応じた状況を知りたくなるかもしれません。 心配ありません、OpenTelemetryのAPIを通じてそれらを計装し、データを送り、Splunk Observabilityで分析できるようになります。

最初に、JavaアプリケーションがOpenTelemetryのAPIを使えるように、ライブラリの依存を追加していきます。 もちろん、vimなどのお好みのエディタをお使い頂いても大丈夫です！

アプリケーションが起動中であれば、一旦停止しましょう。ターミナルで Ctrl-c を押すと、停止することができます。

nano pom.xml

そして、<dependencies> セクションの中（33行目）に↓を追加してください。 ファイル修正後、 ctrl-O のあとに Enter で、ファイルを保存します。次に ctrl-X で、nanoを終了します。

    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
    </dependency>

念のため、コンパイルできるか確かめてみましょう:

./mvnw package -Dmaven.test.skip=true

git checkout pom.xml

これで、JavaのアプリケーションでOpenTelemetryのAPIが使う準備ができました。

2. Javaのコードにマニュアル計装を追加する

では、アプリケーションコードをちょっと変更して、リクエストのコンテキストのデータをスパン属性に追加してみましょう。

ここでは Pet Clinic アプリケーションの中で Find Owners が使われたときに、どのような検索文字列が指定されたのかを調査できるようにしていきます。 検索条件によってパフォーマンスが劣化してしまうケース、よくありませんか？そんなときは OwnerController に計装を追加していきましょう！

nano src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java

このコードを 変更するのは2箇所 です。

まず、import jakarta.validation.Valid; の下、37行目付近に↓を足します:

import io.opentelemetry.api.trace.Span;

次に、 // find owners by last name のコメントがある箇所（おそらく95行目付近にあります）の下に、次のコードを足していきましょう:

                Span span = Span.current();
                span.setAttribute("lastName", owner.getLastName());

このコードで、Last Nameとして指定された検索条件が、スパン属性 lastName としてSplunk Observabilityに伝えるようになりました。

アプリケーションをコンパイルし直ししますが、Javaコードを多少汚してしまったかもしれません。 spring-javaformat:apply を指定しながらコンパイルしてみましょう。

./mvnw spring-javaformat:apply package -Dmaven.test.skip=true

アプリケーションを起動します。せっかくなので、バージョンを一つあげて version=0.315 としましょう。

java -javaagent:./splunk-otel-javaagent.jar \
-Dserver.port=8083 \
-Dotel.service.name=$(hostname).service \
-Dotel.resource.attributes=deployment.environment=$(hostname),version=0.315 \
-Dsplunk.profiler.enabled=true \
-Dsplunk.profiler.memory.enabled=true \
-Dsplunk.metrics.enabled=true \
-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql

http://<VM_IP_ADDRESS>:8083 にアクセスして、オーナー検索をいくつか試してましょう。そしてSplunk APM UIからExploreを開き、アプリケーションのトレースを見ていきます。

検証が完了したら、ターミナルで Ctrl-c を押すと、アプリケーションを停止することができます。

次のセクションでは、RUMを使ってブラウザ上のパフォーマンスデータを収集してみましょう。

Real User Monitoring

1. RUMを有効にする

Real User Monitoring (RUM)計装のために、Open Telemetry Javascript https://github.com/signalfx/splunk-otel-js-web スニペットをページ内に追加します。再度ウィザードを使用します Data Management → Add Integrationボタン → Monitor user experience（画面上部タブ） → Browser Instrumentationを開きます。

ドロップダウンから設定済みの RUM ACCESS TOKEN を選択し、Next をクリックします。以下の構文で App name とEnvironment を入力します：

次に、ワークショップのRUMトークンを選択し、 App nameとEnvironmentを定義します。ウィザードでは、ページ上部の <head> セクションに配置する必要のある HTML コードの断片が表示されます。この例では、次のように記述していますが、ウィザードでは先程入力した値が反映されてるはずです。

• Application Name: <hostname>-petclinic-service
• Environment: <hostname>-petclinic-env

ウィザードで編集済みコードスニペットをコピーするか、以下のスニペットをコピーして適宜編集してください。ただし：

• [hostname]-petclinic-service - [hostname] をお使いのホスト名に書き換えてください
• [hostname]-petclinic-env - [hostname] をお使いのホスト名に書き換えてください

  <script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
  <script>
  SplunkRum.init({
      beaconUrl: "https://rum-ingest.<REALM>.signalfx.com/v1/rum",
      rumAuth: "<RUM_ACCESS_TOKEN>",
      app: "<hostname>.service",
      environment: "<hostname>"
    });
  </script>

Spring PetClinicアプリケーションでは、1つのHTMLページを「レイアウト」ページとして使用し、アプリケーションのすべてのページで再利用しています。これは、Splunk RUM計装ライブラリを挿入するのに最適な場所であり、すべてのページで自動的に読み込まれます。

では、レイアウトページを編集してみましょう：

nano src/main/resources/templates/fragments/layout.html

そして、上で生成したスニップをページの <head> セクションに挿入してみましょう。さて、アプリケーションを再構築して、再び実行する必要があります。

2. PetClinicを再ビルドする

mavenコマンドを実行して、PetClinicをコンパイル/ビルド/パッケージ化します：

./mvnw package -Dmaven.test.skip=true

そして、アプリケーションを動かしてみましょう。バージョンを version=0.316 とするのをお忘れなく。

java -javaagent:./splunk-otel-javaagent.jar \
-Dserver.port=8083 \
-Dotel.service.name=$(hostname).service \
-Dotel.resource.attributes=deployment.environment=$(hostname),version=0.316 \
-Dsplunk.profiler.enabled=true \
-Dsplunk.profiler.memory.enabled=true \
-Dsplunk.metrics.enabled=true \
-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql

次に、より多くのトラフィックを生成するために、アプリケーションに再度アクセスしてみましょう。 http://<VM_IP_ADDRESS>:8083 にアクセスすると、今度はRUMトレースが報告されるはずです。

RUMにアクセスして、トレースとメトリクスのいくつかを見てみましょう。左のメニューから RUM を選ぶと、Spring Pet Clinicでのユーザー（あなたです！）が体験したパフォーマンスが表示されます。

Log Observer

このセクションでは、Spring PetClinicアプリケーションをファイルシステムのファイルにログを書き込むように設定し、 Splunk OpenTelemetry Collectorがそのログファイルを読み取り（tail）、Splunk Observability Platformに情報を報告するように設定していきます。

1. FluentDの設定

Splunk OpenTelemetry Collectorを、Spring PetClinicのログファイルをtailし Splunk Observability Cloudエンドポイントにデータを報告するように設定する必要があります。

Splunk OpenTelemetry Collectorは、FluentDを使用してログの取得/報告を行い、 Spring PetClinicのログを報告するための適切な設定を行うには、 デフォルトディレクトリ（/etc/otel/collector/fluentd/conf.d/）にFluentDの設定ファイルを追加するだけです。

以下は、サンプルのFluentD設定ファイル petclinic.conf を新たに作成し、

sudo nano /etc/otel/collector/fluentd/conf.d/petclinic.conf

ファイル /tmp/spring-petclinic.logを読み取るよう設定を記述します。

<source>
  @type tail
  @label @SPLUNK
  tag petclinic.app
  path /tmp/spring-petclinic.log
  pos_file /tmp/spring-petclinic.pos_file
  read_from_head false
  <parse>
    @type none
  </parse>
</source>

このとき、ファイル petclinic.conf のアクセス権と所有権を変更する必要があります。

sudo chown td-agent:td-agent /etc/otel/collector/fluentd/conf.d/petclinic.conf
sudo chmod 755 /etc/otel/collector/fluentd/conf.d/petclinic.conf

ファイルが作成されたら、FluentDプロセスを再起動しましょう。

sudo systemctl restart td-agent

3. Logbackの設定

Spring Pet Clinicアプリケーションは、いくつかのJavaログライブラリを使用することができます。 このシナリオでは、logbackを使ってみましょう。

リソースフォルダに logback.xml という名前のファイルを作成して…

nano src/main/resources/logback.xml

以下の設定を保存しましょう:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xml>
<configuration scan="true" scanPeriod="30 seconds">
  <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator">
      <resetJUL>true</resetJUL>
  </contextListener>
  <logger name="org.springframework.samples.petclinic" level="debug"/>
  <appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>/tmp/spring-petclinic.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>springLogFile.%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>5</maxHistory>
      <totalSizeCap>1GB</totalSizeCap>
    </rollingPolicy>
    <encoder>
      <pattern>
      %d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} service.name=%property{otel.resource.service.name}, deployment.environment=%property{otel.resource.deployment.environment} %n
      </pattern>
    </encoder>
  </appender>
  <root level="debug">
    <appender-ref ref="file" />
  </root>
</configuration>

その後、アプリケーションを再構築して再度実行していきます。

./mvnw package -Dmaven.test.skip=true

java -javaagent:./splunk-otel-javaagent.jar \
-Dserver.port=8083 \
-Dotel.service.name=$(hostname).service \
-Dotel.resource.attributes=deployment.environment=$(hostname),version=0.317 \
-Dsplunk.profiler.enabled=true \
-Dsplunk.profiler.memory.enabled=true \
-Dsplunk.metrics.enabled=true \
-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql

これまで通り、アプリケーション http://<VM_IP_ADDRESS>:8083 にアクセスしてトラフィックを生成すると、ログメッセージが報告されるようになります。

左側のLog Observerアイコンをクリックして、ホストとSpring PetClinicアプリケーションからのログメッセージのみを選択するためのフィルタを追加できます。

1. Add Filter → Field → host.name → <あなたのホスト名>
2. Add Filter → Field → service.name → <あなたのホスト名>.service

4. まとめ

これでワークショップは終了です。 これまでに、Splunk Observability Cloudにメトリクス、トレース、ログ、データベースクエリのパフォーマンス、コードプロファイリングが報告されるようになりました。 おめでとうございます！