Skip to content

Commit 161b9a9

Browse files
rcastleyrcastley
authored
Merge pull request #161 from katzchang/instrumentation-workshop
Pet Clinic Instrumentation workshop - Japanese
2 parents d62e7e8 + f290fad commit 161b9a9

File tree

8 files changed

+515
-0
lines changed

8 files changed

+515
-0
lines changed

‎content/ja/other/_index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
archetype: "home"
3+
title: さらなるワークショップ
4+
weight: 19
5+
---
6+
7+
{{%children containerstyle="div" style="h3" description="true" %}}

‎content/ja/other/pet-clinic/_index.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Pet Clinic Java ワークショップ
3+
alwaysopen: false
4+
weight: 1
5+
description: JavaアプリケーションをつかったSplunk Oservabilityのワークショップです
6+
---
7+
8+
このワークショップでは、Splunk Observabilityプラットフォームの以下のコンポーネントを構成するための、基本的なステップを体験できます：
9+
10+
* Splunk Infrastructure Monitoring (IM)
11+
* Splunk APM
12+
* Endpoint Performance
13+
* Database Query Performance
14+
* AlwaysOn Profiling
15+
* Splunk Real User Monitoring (RUM)
16+
* Splunk LogObserver
17+
18+
ワークショップの中では、Javaのサンプルアプリケーション（Spring Pet Clinic）をクローン（ダウンロード）し、アプリケーションのコンパイル、パッケージ、実行していきます。
19+
20+
アプリケーションを起動すると、OpenTelemetry Javaエージェントを通じて、Splunk APMでメトリクスとトレースが即座に表示されるようになります。
21+
22+
その後、Splunk OpenTelemetry Javascript Libraries (RUM)を使用して、Pet Clinicのエンドユーザーインターフェース（アプリケーションによってレンダリングされるHTMLページ）を計装し、エンドユーザーが実行する個々のクリックとページロードのすべてについて、RUMトレースを生成していきます。
23+
24+
{{% notice title="前提条件" style="info" %}}
25+
このワークショップは、ホスト/インスタンスが提供されるSplunk実行ワークショップ **または** 自前のホスト/[Multipassインスタンス](https://github.com/splunk/observability-workshop/tree/main/multipass) で行う、自己主導型のワークショップです。
26+
27+
ご自身のシステムには、以下のものがインストールされ、有効になっている必要があります：
28+
29+
1. JDK 17
30+
2. ポート `8080` が開いていること（インバウンド/アウトバウンド）
31+
{{% /notice %}}
32+
33+
![PetClinic Exercise](images/petclinic-exercise.png)

‎content/ja/other/pet-clinic/docs/apm.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: OpenTelemetry Javaエージェントをインストールする
3+
linkTitle: 2. Javaエージェント
4+
weight: 2
5+
---
6+
7+
## 1. Spring PetClinic アプリケーションを動かす
8+
9+
APMをセットアップするためにまず必要なのは...そう、アプリケーションです！この演習では、Spring PetClinicアプリケーションを使用します。これはSpringフレームワーク（Spring Boot）で作られた、非常に人気のあるサンプルJavaアプリケーションです。
10+
11+
まずはPetClinicリポジトリをクローンし、そして、アプリケーションをコンパイル、ビルド、パッケージ、テストしていきます。
12+
13+
```bash
14+
git clone https://github.com/spring-projects/spring-petclinic
15+
```
16+
17+
`spring-petclinic` ディレクトリに移動します:
18+
19+
```bash
20+
cd spring-petclinic
21+
```
22+
23+
PetClinic が使用する MySQL データベースを起動します:
24+
25+
```bash
26+
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/mysql:5.7.8
27+
```
28+
29+
そして、Splunk版のOpenTelemetry Java APMエージェントをダウンロードしておきましょう。
30+
31+
```bash
32+
curl -L https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar \
33+
-o splunk-otel-javaagent.jar
34+
```
35+
36+
次に、mavenコマンドを実行してPetClinicをコンパイル/ビルド/パッケージ化します:
37+
38+
```bash
39+
./mvnw package -Dmaven.test.skip=true
40+
```
41+
42+
{{% notice title="情報" style="info" %}}
43+
実際にアプリをコンパイルする前に、mavenが多くの依存ライブラリをダウンロードするため、初回実行時には数分かかるでしょう。2回目以降の実行はもっと短くなります。
44+
{{% /notice %}}
45+
46+
そして、以下のコマンドでアプリケーションを実行することができます:
47+
48+
49+
```bash
50+
java -javaagent:./splunk-otel-javaagent.jar \
51+
-Dotel.service.name=$(hostname).service \
52+
-Dotel.resource.attributes=deployment.environment=$(hostname),version=0.314 \
53+
-Dsplunk.profiler.enabled=true \
54+
-Dsplunk.profiler.memory.enabled=true \
55+
-Dsplunk.metrics.enabled=true \
56+
-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql
57+
```
58+
59+
60+
アプリケーションが動作しているかどうかは、`http://<VM_IP_ADDRESS>:8080` にアクセスして確認することができます。
61+
次に、トラフィックを生成し、クリックしまくり、エラーを生成し、ペットを追加するなどしてください。
62+
63+
* `-Dotel.service.name=$(hostname).service` では、アプリケーションの名前を定義しています。サービスマップ上のアプリケーションの名前等に反映されます。
64+
* `-Dotel.resource.attributes=deployment.environment=$(hostname),version=0.314` では、Environmentと、versionを定義しています。
65+
- `deployment.environment=$(hostname)` は、Splunk APM UIの上部「Environment」に反映されます。
66+
- `version=0.314` はここでは、アプリケーションのバージョンを示しています。トレースをドリルダウンしたり、サービスマップの Breakdown の機能で分析したり、Tag Spotlightを開くと `version` 毎のパフォーマンス分析が使えます。
67+
* `-Dsplunk.profiler.enabled=true` および `splunk.profiler.memory.enabled=true` では、CPUとメモリのプロファイリングを有効にしています。Splunk APM UIから、AlwaysOn Profilingを開いてみてください。
68+
* `-Dsplunk.metrics.enabled=true` では、メモリやスレッドなどJVMメトリクスの送信を有効にしています。Dashboardsから、APM java servicesを開いてみてください。
69+
70+
その後、Splunk APM UIにアクセスして、それぞれのテレメトリーデータを確認してみましょう！
71+
72+
73+
{{% notice title="Troubleshooting MetricSetsを追加する" style="info" %}}
74+
サービスマップやTab Spotlightで、 `version` などのカスタム属性で分析できるようにするためには、Troubleshooting MetricSetsの設定をあらかじめ追加する必要があります。
75+
左メニューの **Settings → APM MetricSets** で、設定を管理することができます。 もしお使いのアカウントで分析できなければ、設定を追加してみましょう。
76+
{{% /notice %}}
77+
78+
79+
次のセクションではカスタム計装を追加して、OpenTelemetryでは何ができるのか、さらに見ていきます。

‎content/ja/other/pet-clinic/docs/imt.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: OpenTelemetry Collectorをインストールする
3+
linkTitle: 1. OpenTelemetry Collector
4+
weight: 1
5+
---
6+
7+
## 1. はじめに
8+
9+
OpenTelemetry Collectorは、インフラストラクチャーとアプリケーションを計装するためのコアコンポーネントです。 その役割は収集と送信です：
10+
11+
* インフラストラクチャーのメトリクス（ディスク、CPU、メモリなど）
12+
* アプリケーションパフォーマンスモニタリング（APM）のトレース情報
13+
* プロファイリングに関するデータ
14+
* ホストおよびアプリケーションのログ
15+
16+
Splunk Observability Cloudでは、インフラストラクチャーとアプリケーションの両方で Collector のセットアップを案内するウィザードを提供しています。デフォルトでは、ウィザードはコレクターのインストールのみを行うコマンドのみを提供します。
17+
18+
## 2. 環境変数を設定する
19+
20+
すでに **Splunk IM** ワークショップを終了している場合は、既存の環境変数を利用することができます。そうでない場合は、`ACCESS_TOKEN`と`REALM`の環境変数を設定して、OpenTelemetry Collectorのインストールコマンドを実行していきます。
21+
22+
例えば、Realmが `us1` の場合、`export REALM=us1` と入力し、`eu0` の場合は `export REALM=eu0` と入力します。
23+
24+
{{< tabs >}}
25+
{{% tab name="ACCESS TOKENを環境変数に設定する" %}}
26+
27+
``` bash
28+
export ACCESS_TOKEN="<replace_with_O11y-Workshop-ACCESS_TOKEN>"
29+
```
30+
31+
{{% /tab %}}
32+
{{< /tabs >}}
33+
34+
{{< tabs >}}
35+
{{% tab name="REALMを環境変数に設定する" %}}
36+
37+
``` bash
38+
export REALM="<replace_with_REALM>"
39+
```
40+
41+
{{% /tab %}}
42+
{{< /tabs >}}
43+
44+
{{% notice title="既存のOpenTelemetryコレクターをすべて削除する" style="warning" %}}
45+
同じVMインスタンスにSplunk IM ワークショップのセットアップをしている場合、Otel Collectorをインストールする前に Kubernetes で実行中の Collector を削除していることを確認してください。これは、以下のコマンドを実行することで行うことができます：
46+
47+
``` bash
48+
helm delete splunk-otel-collector
49+
```
50+
51+
{{% /notice %}}
52+
53+
## 3. OpenTelemetry Collectorをインストールする
54+
55+
次に、Collectorをインストールします。インストールスクリプトに渡される追加のパラメータは `--deployment-environment` です。
56+
57+
``` bash
58+
curl -sSL https://dl.signalfx.com/splunk-otel-collector.sh > /tmp/splunk-otel-collector.sh && \
59+
sudo sh /tmp/splunk-otel-collector.sh --deployment-environment $(hostname)-petclinic --realm $REALM -- $ACCESS_TOKEN
60+
```
61+
62+
{{% notice style="info" title="AWS/EC2インスタンスの場合" %}}。
63+
AWS/EC2インスタンス上でこのワークショップを行う場合、インスタンスのホスト名を公開するためにコレクターにパッチを適用する必要があります：
64+
65+
``` bash
66+
sudo sed -i 's/gcp, ecs, ec2, azure, system/system, gcp, ecs, ec2, azure/g' /etc/otel/collector/agent_config.yaml
67+
```
68+
69+
`agent_config.yaml` にパッチを適用したあと、Collector を再起動してください：
70+
71+
``` bash
72+
sudo systemctl restart splunk-otel-collector
73+
```
74+
75+
{{% /notice %}}
76+
77+
インストールが完了したら、Splunk Observabilityの **Hosts with agent installed** ダッシュボードに移動して、**Dashboards → Hosts with agent installed** からホストのデータを確認してみましょう。
78+
79+
ダッシュボードのフィルタを使用して `host.name`を選択し、仮想マシンのホスト名を入力または選択します。ホストのデータが表示されたら、APMコンポーネントを使用する準備が整いました。

‎content/ja/other/pet-clinic/docs/logobserver.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Log Observer
3+
linktitle: 5. Log Observer
4+
weight: 5
5+
---
6+
7+
このセクションでは、Spring PetClinicアプリケーションをファイルシステムのファイルにログを書き込むように設定し、
8+
Splunk OpenTelemetry Collectorがそのログファイルを読み取り（tail）、Splunk Observability Platformに情報を報告するように設定していきます。
9+
10+
## 1. FluentDの設定
11+
12+
Splunk OpenTelemetry Collectorを、Spring PetClinicのログファイルをtailし
13+
Splunk Observability Cloudエンドポイントにデータを報告するように設定する必要があります。
14+
15+
Splunk OpenTelemetry Collectorは、FluentDを使用してログの取得/報告を行い、
16+
Spring PetClinicのログを報告するための適切な設定を行うには、
17+
デフォルトディレクトリ（`/etc/otel/collector/fluentd/conf.d/`）にFluentDの設定ファイルを追加するだけです。
18+
19+
以下は、サンプルのFluentD設定ファイル `petclinic.conf` を新たに作成し、
20+
21+
```bash
22+
sudo nano /etc/otel/collector/fluentd/conf.d/petclinic.conf
23+
```
24+
25+
26+
ファイル `/tmp/spring-petclinic.log`を読み取るよう設定を記述します。
27+
28+
```
29+
<source>
30+
@type tail
31+
@label @SPLUNK
32+
tag petclinic.app
33+
path /tmp/spring-petclinic.log
34+
pos_file /tmp/spring-petclinic.pos_file
35+
read_from_head false
36+
<parse>
37+
@type none
38+
</parse>
39+
</source>
40+
```
41+
42+
43+
このとき、ファイル `petclinic.conf` のアクセス権と所有権を変更する必要があります。
44+
45+
```bash
46+
sudo chown td-agent:td-agent /etc/otel/collector/fluentd/conf.d/petclinic.conf
47+
sudo chmod 755 /etc/otel/collector/fluentd/conf.d/petclinic.conf
48+
```
49+
50+
ファイルが作成されたら、FluentDプロセスを再起動しましょう。
51+
52+
```bash
53+
sudo systemctl restart td-agent
54+
```
55+
56+
57+
## 3. Logbackの設定
58+
59+
Spring Pet Clinicアプリケーションは、いくつかのJavaログライブラリを使用することができます。
60+
このシナリオでは、logbackを使ってみましょう。
61+
62+
リソースフォルダに `logback.xml` という名前のファイルを作成して…
63+
64+
```bash
65+
nano src/main/resources/logback.xml
66+
```
67+
68+
69+
以下の設定を保存しましょう:
70+
71+
```xml
72+
<?xml version="1.0" encoding="UTF-8"?>
73+
<!DOCTYPE xml>
74+
<configuration scan="true" scanPeriod="30 seconds">
75+
<contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator">
76+
<resetJUL>true</resetJUL>
77+
</contextListener>
78+
<logger name="org.springframework.samples.petclinic" level="debug"/>
79+
<appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
80+
<file>/tmp/spring-petclinic.log</file>
81+
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
82+
<fileNamePattern>springLogFile.%d{yyyy-MM-dd}.log</fileNamePattern>
83+
<maxHistory>5</maxHistory>
84+
<totalSizeCap>1GB</totalSizeCap>
85+
</rollingPolicy>
86+
<encoder>
87+
<pattern>
88+
%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
89+
</pattern>
90+
</encoder>
91+
</appender>
92+
<root level="debug">
93+
<appender-ref ref="file" />
94+
</root>
95+
</configuration>
96+
```
97+
98+
その後、アプリケーションを再構築して再度実行していきます。
99+
100+
101+
```bash
102+
./mvnw package -Dmaven.test.skip=true
103+
```
104+
105+
```bash
106+
java -javaagent:./splunk-otel-javaagent.jar \
107+
-Dotel.service.name=$(hostname).service \
108+
-Dotel.resource.attributes=deployment.environment=$(hostname),version=0.317 \
109+
-Dsplunk.profiler.enabled=true \
110+
-Dsplunk.profiler.memory.enabled=true \
111+
-Dsplunk.metrics.enabled=true \
112+
-jar target/spring-petclinic-*.jar --spring.profiles.active=mysql
113+
```
114+
115+
116+
これまで通り、アプリケーション `http://<VM_IP_ADDRESS>:8080` にアクセスしてトラフィックを生成すると、ログメッセージが報告されるようになります。
117+
118+
左側のLog Observerアイコンをクリックして、ホストとSpring PetClinicアプリケーションからのログメッセージのみを選択するためのフィルタを追加できます。
119+
120+
1. Add Filter → Field → host.name → <あなたのホスト名>
121+
2. Add Filter → Field → service.name → <あなたのホスト名>.service
122+
123+
124+
## 4. まとめ
125+
126+
これでワークショップは終了です。
127+
これまでに、Splunk Observability Cloudにメトリクス、トレース、ログ、データベースクエリのパフォーマンス、コードプロファイリングが報告されるようになりました。
128+
おめでとうございます！

0 commit comments

Comments
 (0)