Merge pull request #433 from gentksb/translate/1-automatic-discovery

Japanese Translation: NINJA-Workshop/1-automatic-discovery

Author: rcastley

content/ja/ninja-workshops/1-automatic-discovery/1-petclinic-monolith/1-otel-collector.md

@@ -0,0 +1,76 @@
+---
+title: OpenTelemetry Collector のインストール
+linkTitle: 1. OpenTelemetry Collector
+weight: 1
+---
+
+Splunk OpenTelemetry Collector は、インフラストラクチャとアプリケーションの計装における中核コンポーネントです。その役割は以下のデータを収集して送信することです：
+
+* インフラストラクチャメトリクス（ディスク、CPU、メモリなど）
+* Application Performance Monitoring (APM) トレース
+* プロファイリングデータ
+* ホストおよびアプリケーションのログ
+
+{{% notice title="既存の OpenTelemetry Collector の削除" style="warning" %}}
+Splunk IM ワークショップを完了している場合は、続行する前に Kubernetes で実行中の Collector を削除してください。以下のコマンドを実行して削除できます：
+
+``` bash
+helm delete splunk-otel-collector
+```
+
+EC2 インスタンスには、古いバージョンの Collector がすでにインストールされている場合があります。Collector をアンインストールするには、以下のコマンドを実行してください：
+
+``` bash
+curl -sSL https://dl.signalfx.com/splunk-otel-collector.sh > /tmp/splunk-otel-collector.sh
+sudo sh /tmp/splunk-otel-collector.sh --uninstall
+```
+
+{{% /notice %}}
+
+インスタンスが正しく設定されていることを確認するために、このワークショップに必要な環境変数が正しく設定されているか確認する必要があります。ターミナルで以下のコマンドを実行してください：
+
+``` bash
+. ~/workshop/petclinic/scripts/check_env.sh
+```
+
+出力で、以下のすべての環境変数が存在し、値が設定されていることを確認してください。不足している場合は、インストラクターに連絡してください：
+
+```text
+ACCESS_TOKEN
+REALM
+RUM_TOKEN
+HEC_TOKEN
+HEC_URL
+INSTANCE
+```
+
+これで Collector のインストールに進むことができます。インストールスクリプトには、いくつかの追加パラメータが渡されます：
+
+* `--with-instrumentation` - Splunk ディストリビューションの OpenTelemetry Java からエージェントをインストールします。これにより、PetClinic Java アプリケーションの起動時に自動的にロードされます。設定は不要です！
+* `--deployment-environment` - リソース属性 `deployment.environment` を指定された値に設定します。これは UI でビューをフィルタリングするために使用されます。
+* `--enable-profiler` - Java アプリケーションのプロファイラを有効にします。これによりアプリケーションの CPU プロファイルが生成されます。
+* `--enable-profiler-memory` - Java アプリケーションのプロファイラを有効にします。これによりアプリケーションのメモリプロファイルが生成されます。
+* `--enable-metrics` - Micrometer メトリクスのエクスポートを有効にします
+* `--hec-token` - Collector が使用する HEC トークンを設定します
+* `--hec-url` - Collector が使用する HEC URL を設定します
+
+``` bash
+curl -sSL https://dl.signalfx.com/splunk-otel-collector.sh > /tmp/splunk-otel-collector.sh && \
+sudo sh /tmp/splunk-otel-collector.sh --realm $REALM -- $ACCESS_TOKEN --mode agent --without-fluentd --with-instrumentation --deployment-environment $INSTANCE-petclinic --enable-profiler --enable-profiler-memory --enable-metrics --hec-token $HEC_TOKEN --hec-url $HEC_URL
+```
+
+次に、Collector にパッチを適用して、AWS インスタンス ID ではなくインスタンスのホスト名を公開するようにします。これにより、UI でのデータのフィルタリングが容易になります：
+
+``` bash
+sudo sed -i 's/gcp, ecs, ec2, azure, system/system, gcp, ecs, ec2, azure/g' /etc/otel/collector/agent_config.yaml
+```
+
+`agent_config.yaml` にパッチを適用したら、Collector を再起動する必要があります：
+
+``` bash
+sudo systemctl restart splunk-otel-collector
+```
+
+インストールが完了したら、**Hosts with agent installed** ダッシュボードに移動して、ホストからのデータを確認できます。**Dashboards → Hosts with agent installed** の順に移動してください。
+
+ダッシュボードフィルタを使用して `host.name` を選択し、ワークショップインスタンスのホスト名を入力または選択してください（これはターミナルセッションのコマンドプロンプトから取得できます）。ホストのデータが流れていることを確認したら、APM コンポーネントの作業を開始する準備が整いました。

content/ja/ninja-workshops/1-automatic-discovery/1-petclinic-monolith/2-building-petclinic.md

@@ -0,0 +1,55 @@
+---
+title: Spring PetClinic アプリケーションのビルド
+linkTitle: 2. PetClinic のビルド
+weight: 2
+---
+
+APM をセットアップするために最初に必要なのは...そう、アプリケーションです。この演習では、Spring PetClinic アプリケーションを使用します。これは、Spring フレームワーク（Springboot）で構築された非常に人気のあるサンプル Java アプリケーションです。
+
+まず、PetClinic の GitHub リポジトリをクローンし、その後アプリケーションのコンパイル、ビルド、パッケージ化、テストを行います：
+
+```bash
+git clone https://github.com/spring-projects/spring-petclinic
+```
+
+`spring-petclinic` ディレクトリに移動します：
+
+<!--
+```bash
+cd spring-petclinic && git checkout 276880e
+```
+-->
+
+```bash
+cd spring-petclinic
+git checkout b26f235250627a235a2974a22f2317dbef27338d
+```
+
+Docker を使用して、PetClinic が使用する MySQL データベースを起動します：
+
+```bash
+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
+```
+
+次に、PetClinic アプリケーションにシンプルなトラフィックを生成する Locust を実行する別のコンテナを起動します。Locust は、Web アプリケーションにトラフィックを生成するために使用できるシンプルな負荷テストツールです。
+
+```bash
+docker run --network="host" -d -p 8090:8090 -v ~/workshop/petclinic:/mnt/locust docker.io/locustio/locust -f /mnt/locust/locustfile.py --headless -u 1 -r 1 -H http://127.0.0.1:8083
+```
+
+次に、`maven` を使用して PetClinic をコンパイル、ビルド、パッケージ化します：
+
+```bash
+./mvnw package -Dmaven.test.skip=true
+```
+
+> [!INFO]
+> 初回実行時は数分かかり、アプリケーションをコンパイルする前に多くの依存関係をダウンロードします。以降のビルドはより高速になります。
+
+ビルドが完了したら、実行しているインスタンスのパブリック IP アドレスを取得する必要があります。以下のコマンドを実行して取得できます：
+
+```bash
+curl http://ifconfig.me
+```
+
+IP アドレスが返されます。アプリケーションが実行されていることを確認するために必要になるので、この IP アドレスをメモしておいてください。

content/ja/ninja-workshops/1-automatic-discovery/1-petclinic-monolith/3-auto-discovery.md

@@ -0,0 +1,64 @@
+---
+title: Java 向け自動ディスカバリーおよび設定
+linkTitle: 3. 自動ディスカバリー
+weight: 3
+---
+
+以下のコマンドでアプリケーションを起動できます。`mysql` プロファイルをアプリケーションに渡していることに注目してください。これにより、先ほど起動した MySQL データベースを使用するようアプリケーションに指示します。また、`otel.service.name` と `otel.resource.attributes` をインスタンス名を使用した論理名に設定しています。これらは UI でのフィルタリングにも使用されます：
+
+```bash
+java \
+-Dserver.port=8083 \
+-Dotel.service.name=$INSTANCE-petclinic-service \
+-Dotel.resource.attributes=deployment.environment=$INSTANCE-petclinic-env \
+-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql
+```
+
+`http://<IP_ADDRESS>:8083`（`<IP_ADDRESS>` を先ほど取得した IP アドレスに置き換えてください）にアクセスして、アプリケーションが実行されていることを確認できます。
+
+Collector をインストールした際、**AlwaysOn Profiling** と **Metrics** を有効にするように設定しました。これにより、Collector はアプリケーションの CPU およびメモリプロファイルを自動的に生成し、Splunk Observability Cloud に送信します。
+
+PetClinic アプリケーションを起動すると、Collector がアプリケーションを自動的に検出し、トレースとプロファイリングのために計装するのが確認できます。
+
+{{% tab title="出力例" %}}
+
+``` text {wrap="false"}
+Picked up JAVA_TOOL_OPTIONS: -javaagent:/usr/lib/splunk-instrumentation/splunk-otel-javaagent.jar
+OpenJDK 64-Bit Server VM warning: Sharing is only supported for boot loader classes because bootstrap classpath has been appended
+[otel.javaagent 2024-08-20 11:35:58:970 +0000] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: splunk-2.6.0-otel-2.6.0
+[otel.javaagent 2024-08-20 11:35:59:730 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger - -----------------------
+[otel.javaagent 2024-08-20 11:35:59:730 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger - Profiler configuration:
+[otel.javaagent 2024-08-20 11:35:59:730 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -                  splunk.profiler.enabled : true
+[otel.javaagent 2024-08-20 11:35:59:731 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -                splunk.profiler.directory : /tmp
+[otel.javaagent 2024-08-20 11:35:59:731 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -       splunk.profiler.recording.duration : 20s
+[otel.javaagent 2024-08-20 11:35:59:731 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -               splunk.profiler.keep-files : false
+[otel.javaagent 2024-08-20 11:35:59:732 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -            splunk.profiler.logs-endpoint : null
+[otel.javaagent 2024-08-20 11:35:59:732 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -              otel.exporter.otlp.endpoint : null
+[otel.javaagent 2024-08-20 11:35:59:732 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -           splunk.profiler.memory.enabled : true
+[otel.javaagent 2024-08-20 11:35:59:732 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -        splunk.profiler.memory.event.rate : 150/s
+[otel.javaagent 2024-08-20 11:35:59:732 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -      splunk.profiler.call.stack.interval : PT10S
+[otel.javaagent 2024-08-20 11:35:59:733 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -  splunk.profiler.include.internal.stacks : false
+[otel.javaagent 2024-08-20 11:35:59:733 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger -      splunk.profiler.tracing.stacks.only : false
+[otel.javaagent 2024-08-20 11:35:59:733 +0000] [main] INFO com.splunk.opentelemetry.profiler.ConfigurationLogger - -----------------------
+[otel.javaagent 2024-08-20 11:35:59:733 +0000] [main] INFO com.splunk.opentelemetry.profiler.JfrActivator - Profiler is active.
+```
+
+{{% /tab %}}
+
+Splunk APM UI にアクセスして、アプリケーションコンポーネント、トレース、プロファイリング、DB Query パフォーマンス、メトリクスを確認できます。左側のメニューから **APM** をクリックし、**Environment** ドロップダウンをクリックして、ご自身の環境（例：`<INSTANCE>-petclinic`、`<INSTANCE>` は先ほどメモした値に置き換えてください）を選択します。
+
+検証が完了したら、`Ctrl-c` を押してアプリケーションを停止できます。
+
+リソース属性は、報告されるすべてのスパンに追加できます。例えば `version=0.314` のように指定します。カンマ区切りのリソース属性リストも定義できます（例：`key1=val1,key2=val2`）。
+
+新しいリソース属性を使用して PetClinic を再度起動しましょう。実行コマンドにリソース属性を追加すると、Collector のインストール時に定義された内容が上書きされることに注意してください。新しいリソース属性 `version=0.314` を追加しましょう：
+
+```bash
+java \
+-Dserver.port=8083 \
+-Dotel.service.name=$INSTANCE-petclinic-service \
+-Dotel.resource.attributes=deployment.environment=$INSTANCE-petclinic-env,version=0.314 \
+-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql
+```
+
+Splunk APM UI に戻り、最近のトレースをドリルダウンすると、スパン内に新しい `version` 属性が表示されます。

content/ja/ninja-workshops/1-automatic-discovery/1-petclinic-monolith/4-rum.md

@@ -0,0 +1,78 @@
+---
+title: 3. Real User Monitoring
+weight: 3
+---
+
+Real User Monitoring (RUM) の計装では、ページに OpenTelemetry Javascript スニペット [**https://github.com/signalfx/splunk-otel-js-web**](https://github.com/signalfx/splunk-otel-js-web) を追加します。ウィザードを使用して **Data Management → Add Integration → RUM Instrumentation → Browser Instrumentation** の順に進みます。
+
+インストラクターがドロップダウンから使用するトークンを指示します。**Next** をクリックしてください。以下の形式で **App name** と **Environment** を入力します：
+
+- `<INSTANCE>-petclinic-service` - `<INSTANCE>` を先ほどメモした値に置き換えてください。
+- `<INSTANCE>-petclinic-env` - `<INSTANCE>` を先ほどメモした値に置き換えてください。
+
+ウィザードは、ページの `<head>` セクションの先頭に配置する必要がある HTML コードスニペットを表示します。以下は例です（このスニペットは使用せず、ウィザードが生成したものを使用してください）：
+
+``` html
+/*
+
+IMPORTANT: Replace the <version> placeholder in the src URL with a
+version from https://github.com/signalfx/splunk-otel-js-web/releases
+
+*/
+<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
+<script>
+    SplunkRum.init({
+        realm: "eu0",
+        rumAccessToken: "<redacted>",
+        applicationName: "petclinic-1be0-petclinic-service",
+        deploymentEnvironment: "petclinic-1be0-petclinic-env"
+    });
+</script>
+```
+
+Spring PetClinic アプリケーションは、アプリケーションのすべてのページで再利用される単一の HTML ページを「レイアウト」ページとして使用しています。Splunk RUM 計装ライブラリを挿入するには、すべてのページで自動的に読み込まれるため、この場所が最適です。
+
+それでは、レイアウトページを編集しましょう：
+
+```bash
+vi src/main/resources/templates/fragments/layout.html
+```
+
+次に、上記で生成したスニペットをページの `<head>` セクションに挿入します。コメントは含めず、ソース URL の `<version>` を `latest` に置き換えてください：
+
+```html
+<!doctype html>
+<html th:fragment="layout (template, menu)">
+
+<head>
+<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
+<script>
+    SplunkRum.init({
+        realm: "eu0",
+        rumAccessToken: "<redacted>",
+        applicationName: "petclinic-1be0-petclinic-service",
+        deploymentEnvironment: "petclinic-1be0-petclinic-env"
+    });
+</script>
+...
+```
+
+コード変更が完了したら、アプリケーションを再ビルドして再度実行する必要があります。`maven` コマンドを実行して PetClinic をコンパイル/ビルド/パッケージ化します：
+
+```bash
+./mvnw package -Dmaven.test.skip=true
+```
+
+```bash
+java \
+-Dserver.port=8083 \
+-Dotel.service.name=$INSTANCE-petclinic-service \
+-Dotel.resource.attributes=deployment.environment=$INSTANCE-petclinic-env,version=0.314 \
+-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql
+```
+
+次に、ブラウザを使用してアプリケーション `http://<IP_ADDRESS>:8083` にアクセスし、実際のユーザートラフィックを生成します。
+
+RUM で、上記の RUM スニペットで定義された環境にフィルタリングし、ダッシュボードをクリックして開きます。
+
+RUM トレースをドリルダウンすると、スパン内に APM へのリンクが表示されます。トレース ID をクリックすると、現在の RUM トレースに対応する APM トレースに移動します。

content/ja/ninja-workshops/1-automatic-discovery/1-petclinic-monolith/5-log-observer.md

@@ -0,0 +1,24 @@
+---
+title: 4. Log Observer
+weight: 4
+---
+
+Splunk Log Observer コンポーネントでは、Splunk OpenTelemetry Collector が Spring PetClinic アプリケーションからログを自動的に収集し、OTLP エクスポーターを使用して Splunk Observability Cloud に送信します。その際、ログイベントに `trace_id`、`span_id`、トレースフラグを付与します。
+
+Log Observer は、アプリケーションとインフラストラクチャからのログをリアルタイムで表示します。ログの検索、フィルタリング、分析を行って、問題のトラブルシューティングや環境の監視が可能です。
+
+PetClinic Web アプリケーションに戻り、**Error** リンクを数回クリックしてください。これにより、PetClinic アプリケーションログにいくつかのログメッセージが生成されます。
+
+![PetClinic Error](../images/petclinic-error.png)
+
+左側のメニューから **Log Observer** をクリックし、**Index** が **splunk4rookies-workshop** に設定されていることを確認してください。
+
+次に、**Add Filter** をクリックし、フィールド `service.name` を検索して、値 `<INSTANCE>-petclinic-service` を選択し、`=`（include）をクリックします。これで、PetClinic アプリケーションからのログメッセージのみが表示されるはずです。
+
+PetClinic アプリケーションの **Error** リンクをクリックして生成されたログエントリの1つを選択してください。ログメッセージと、ログメッセージに自動的にインジェクションされたトレースメタデータが表示されます。また、APM と Infrastructure の Related Content が利用可能であることにも注目してください。
+
+![Log Observer](../images/log-observer.png)
+
+これでワークショップは終了です。多くの内容をカバーしました。この時点で、メトリクス、トレース（APM と RUM）、ログ、データベースクエリパフォーマンス、コードプロファイリングが Splunk Observability Cloud に報告されているはずです。しかも、PetClinic アプリケーションのコードを変更することなく実現できました（RUM を除く）。
+
+**おめでとうございます！**