はじめに
本記事では、Ubuntu 22.04環境でInstana AgentとInstana Trace SDKを計装したSpring Bootベースのデモアプリケーションをセットアップし、Instana SaaSバックエンドでアプリケーションのトレース、メトリクス、コールグラフを確認する手順を紹介します。
対象読者
- Instanaの基本的な使い方を学びたい方
- APM(Application Performance Monitoring)ツールに興味がある方
- Spring BootアプリケーションのObservabilityを向上させたい方
環境
- OS: Ubuntu 22.04 LTS
- Java: OpenJDK 11
- Maven: Apache Maven 3.6.3以上
- MySQL: MySQL 8.0
- Instana: Instana Agent (最新版)
1. 前提条件の確認とインストール
1.1 システムアップデート
sudo apt update && sudo apt upgrade -y
1.2 Java 11のインストール
sudo apt install openjdk-11-jdk -y
java -version
出力例:
openjdk version "11.0.x" 2023-xx-xx
OpenJDK Runtime Environment (build 11.0.x+x-Ubuntu-xxubuntu22.04)
OpenJDK 64-Bit Server VM (build 11.0.x+x-Ubuntu-xxubuntu22.04, mixed mode, sharing)
1.3 Mavenのインストール
sudo apt install maven -y
mvn -version
出力例:
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 11.0.x, vendor: Ubuntu, runtime: /usr/lib/jvm/java-11-openjdk-amd64
1.4 Gitのインストール
sudo apt install git -y
2. プロジェクトのクローン
GitHubからデモプロジェクトをクローンします。
cd ~
git clone https://github.com/GSSJacky/springboot-instana-demo.git
cd springboot-instana-demo
3. MySQLのセットアップ
3.1 MySQLのインストール
sudo apt install mysql-server -y
3.2 MySQLサービスの起動と確認
sudo systemctl start mysql
sudo systemctl enable mysql
sudo systemctl status mysql
3.3 MySQLのセキュリティ設定
sudo mysql_secure_installation
以下の質問に答えます:
-
VALIDATE PASSWORD COMPONENT:
No(開発環境のため) -
root password:
password123!を設定 -
Remove anonymous users:
Yes -
Disallow root login remotely:
Yes -
Remove test database:
Yes -
Reload privilege tables:
Yes
3.4 データベースとユーザーの作成
MySQLにrootユーザーでログインします:
sudo mysql -u root -p
パスワード password123! を入力後、以下のSQLを実行します:
-- データベースの作成
CREATE DATABASE IF NOT EXISTS instana_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- アプリケーション用のrootユーザーのパスワード設定(既に設定済みの場合はスキップ)
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password123!';
-- Instana Agent監視用ユーザー (user1) の作成と権限付与
CREATE USER 'user1'@'localhost' IDENTIFIED BY 'password123!';
GRANT ALL PRIVILEGES ON *.* TO 'user1'@'localhost';
GRANT SELECT, PROCESS, SHOW DATABASES, SUPER, REPLICATION CLIENT ON *.* TO 'user1'@'localhost';
FLUSH PRIVILEGES;
-- 確認
SELECT user, host FROM mysql.user WHERE user IN ('root', 'user1');
-- 終了
EXIT;
3.5 データベース接続の確認
mysql -u root -p -e "SHOW DATABASES;"
instana_demo データベースが表示されることを確認します。
4. アプリケーション設定の確認
プロジェクトの src/main/resources/application.properties ファイルを確認します:
cat src/main/resources/application.properties
以下の設定が含まれていることを確認:
spring.datasource.url=jdbc:mysql://localhost:3306/instana_demo
spring.datasource.username=root
spring.datasource.password=password123!
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
server.port=8081
注意: パスワードが異なる場合は、このファイルを編集してください:
nano src/main/resources/application.properties
5. Instana Agentのインストール
5.1 Instana Agent(One-liner)のインストール
Instana SaaSバックエンドから取得したOne-linerコマンドを実行します。
例(実際のコマンドはInstanaダッシュボードから取得してください):
curl -o setup_agent.sh https://setup.instana.io/agent && sudo bash setup_agent.sh -a <YOUR_AGENT_KEY> -t dynamic -e <YOUR_BACKEND_URL>:443 -s
パラメータ説明:
-
-a <YOUR_AGENT_KEY>: Instanaから提供されるエージェントキー -
-t dynamic: 動的モード(推奨) -
-e <YOUR_BACKEND_URL>:443: Instanaバックエンドのエンドポイント -
-s: セキュアモード(HTTPS)
5.2 Instana Agentサービスの確認
sudo systemctl status instana-agent
正常に起動していることを確認します。
6. Instana Agent設定ファイルの編集
6.1 設定ファイルの場所
sudo nano /opt/instana/agent/etc/instana/configuration.yaml
6.2 設定内容の追加
ファイルの末尾に以下を追加します:
# Hardware & Zone
com.instana.plugin.generic.hardware:
enabled: true
availability-zone: 'Ubuntu-Demo'
# MySQL Configuration
com.instana.plugin.mysql:
user: 'user1'
password: 'password123!'
enabled: true
# Java Trace SDK Configuration
com.instana.plugin.javatrace:
instrumentation:
sdk:
packages:
- 'com.example.instana'
設定の説明:
-
availability-zone: ホストの識別名(任意の名前) -
com.instana.plugin.mysql: MySQL監視の有効化とユーザー情報 -
com.instana.plugin.javatrace: カスタムトレース用のパッケージ指定
6.3 Instana Agentの再起動
sudo systemctl restart instana-agent
sudo systemctl status instana-agent
7. アプリケーションのビルド
プロジェクトディレクトリでMavenビルドを実行します:
cd ~/springboot-instana-demo
mvn clean package -DskipTests
ビルドが成功すると、target/instana-demo-0.0.1-SNAPSHOT.jar が生成されます。
確認:
ls -lh target/*.jar
8. MySQLサービスの起動確認
sudo systemctl status mysql
起動していない場合は起動します:
sudo systemctl start mysql
9. アプリケーションの起動
9.1 JARファイルの実行
java -jar target/instana-demo-0.0.1-SNAPSHOT.jar
起動ログに以下のようなメッセージが表示されます:
Started InstanaDemoApplication in X.XXX seconds
Tomcat started on port(s): 8081 (http)
9.2 バックグラウンド実行(オプション)
バックグラウンドで実行する場合:
nohup java -jar target/instana-demo-0.0.1-SNAPSHOT.jar > app.log 2>&1 &
プロセス確認:
ps aux | grep instana-demo
停止する場合:
pkill -f instana-demo
10. アプリケーションへのアクセス
10.1 ブラウザでアクセス
ブラウザで以下のURLにアクセスします:
http://localhost:8081
または、リモートからアクセスする場合:
http://<Ubuntu_Server_IP>:8081
10.2 ログイン
ログイン画面が表示されたら、以下の認証情報を入力します:
-
Username:
user1 -
Password:
password123!
10.3 商品(Inventory)の追加
- ログイン後、「Add New Product」ボタンをクリック
- 以下の情報を入力:
-
Product Name:
ノートパソコン -
Description:
高性能ビジネスノートPC -
Price:
150000 -
Quantity:
10
-
Product Name:
- 「Save」ボタンをクリック
10.4 複数の操作を実行
トレースデータを生成するため、以下の操作を複数回実行します:
- 商品の追加(3〜5件)
- 商品一覧の表示(複数回リロード)
- 商品の編集
- ログアウト・ログイン
11. Instana SaaSバックエンドでの確認
11.1 アプリケーションの確認
-
Instana SaaSダッシュボードにログイン
-
左メニューから 「Applications」 を選択
-
「SpringBoot-instana-demo」 アプリケーションを探す(事前に["Zone名前"-instana-demo]というServiceのApplicationを作成していただければ。)
確認できる情報:
- 呼び出し回数(Calls): HTTPリクエストの総数
- エラー率(Error Rate): エラーが発生したリクエストの割合
- 平均レスポンスタイム(Latency): リクエストの平均処理時間
11.2 トレース(Trace)の確認
トレース詳細で確認できる情報:
-
HTTP リクエスト:
POST /inventory/save,GET /inventoryなど -
データベースクエリ:
INSERT INTO product,SELECT * FROM productなど -
カスタムスパン:
calculatePrice,determineDiscount,ComplexDiscountLogic
カスタムスパンの確認方法:
- トレース詳細画面で
calculatePriceというスパン名を探す - これは
PricingService.javaの@Spanアノテーションで計装されたメソッド
11.3 コールグラフ(Call Graph)の確認
- アプリケーション詳細画面で 「Dependencies」 または 「Service Map」 を選択
- 以下のコンポーネント間の依存関係が表示されます:
[Browser] → [JackyWindows-instana-demo (Java)] → [instana_demo (MySQL)]
確認できる情報:
- サービス間の呼び出し関係: アプリケーションからMySQLへの接続
- 呼び出し回数: 各エンドポイントへのリクエスト数
- レスポンスタイム: 各コンポーネントの処理時間
11.4 インフラストラクチャの確認
- 左メニューから 「Infrastructure」 を選択
- 「Hosts」 でUbuntuホストを探す
- ホスト名をクリックして詳細を表示
確認できる情報:
- CPU使用率
- メモリ使用率
- ディスクI/O
- ネットワークトラフィック
- 実行中のプロセス(Java、MySQL)
11.5 MySQLメトリクスの確認
- 「Infrastructure」 → 「Databases」 を選択
- MySQLインスタンスをクリック
確認できる情報:
- 接続数(Connections)
- クエリ実行数(Queries per second)
- スロークエリ(Slow Queries)
- テーブルロック(Table Locks)
12. トラブルシューティング
12.1 アプリケーションが起動しない
エラー: Access denied for user 'root'@'localhost'
解決策:
# MySQLにログインしてパスワードを再設定
sudo mysql -u root
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password123!';
FLUSH PRIVILEGES;
EXIT;
12.2 Instana Agentがデータを送信しない
確認事項:
# Agentログの確認
sudo tail -f /opt/instana/agent/data/log/agent.log
# Agentの再起動
sudo systemctl restart instana-agent
12.3 MySQLが監視されない
確認事項:
-
configuration.yamlの設定が正しいか確認 - user1ユーザーの権限が正しいか確認:
mysql -u user1 -p -e "SHOW GRANTS FOR 'user1'@'localhost';"
12.4 カスタムスパンが表示されない
確認事項:
-
configuration.yamlにcom.instana.plugin.javatraceの設定があるか確認 - Instana Agentを再起動
- アプリケーションを再起動
補足: Instana Java Trace SDKの計装ポイント
Instana自動計装とSDKの使い分け
Instanaエージェントは、主要なフレームワークやライブラリを自動的に計装します。つまり、多くの場合、コード変更なしでトレースが取得できます。しかし、特定のケースではInstana Java Trace SDKを使用した手動計装が必要になります。
自動計装されるフレームワーク・ライブラリ(SDKなし)
Instanaエージェントは以下のフレームワークとライブラリをコード変更なしで自動的にトレースします:
Webフレームワーク
- ✅ Spring Boot / Spring MVC -
@RestController,@Controller - ✅ Spring WebFlux - リアクティブWebアプリケーション
- ✅ Jakarta EE / Java EE - Servlet API, JAX-RS, JAX-WS
- ✅ Netty - 非同期イベント駆動型ネットワークフレームワーク
- ✅ Vert.x - リアクティブアプリケーション
- ✅ Play Framework - Scala/Javaフレームワーク
- ✅ Grails - Groovyベースのフレームワーク
データベース・永続化
- ✅ JDBC - すべてのJDBCドライバー
- ✅ Spring Data JPA / Hibernate - ORM
- ✅ MyBatis - SQLマッパー
- ✅ MongoDB - NoSQLデータベース
- ✅ Cassandra - 分散NoSQLデータベース
- ✅ Redis - インメモリデータストア
- ✅ Elasticsearch - 検索エンジン
メッセージング
- ✅ Apache Kafka - 分散ストリーミングプラットフォーム
- ✅ RabbitMQ - メッセージブローカー
- ✅ JMS (Java Message Service) - メッセージング標準
- ✅ Amazon SQS - AWSメッセージキュー
- ✅ Google Pub/Sub - GCPメッセージング
HTTPクライアント
- ✅ Apache HttpClient - HTTP通信ライブラリ
- ✅ OkHttp - HTTPクライアント
- ✅ Spring RestTemplate - REST API呼び出し
- ✅ Spring WebClient - リアクティブHTTPクライアント
- ✅ Java HttpURLConnection - 標準HTTPクライアント
その他
- ✅ gRPC - RPCフレームワーク
- ✅ GraphQL - クエリ言語
- ✅ Quartz Scheduler - ジョブスケジューラー
- ✅ Spring Batch - バッチ処理フレームワーク
📚 完全なリスト: Instana公式ドキュメント - Instrumented Frameworks and Libraries
本プロジェクトで自動計装されているもの
ブラウザ → [Spring MVC Controller] → [Service Layer] → [Spring Data JPA] → [MySQL JDBC]
これらのステップはすべて自動的に1つのトレースとして結合されます。
Instana Java Trace SDKが必要なケース
自動計装でカバーされない以下のケースでは、Instana Java Trace SDKを使用した手動計装が必要です:
ケース1: カスタム・独自フレームワーク
自社開発のHTTPフレームワークや、Instanaがサポートしていないマイナーなフレームワークを使用している場合。
例:
- 独自開発のRPCフレームワーク
- 社内専用の通信プロトコル
- レガシーシステムとの独自インターフェース
解決策: SDK Tracing APIを使用してエントリーポイントとエグジットポイントを計装
import com.instana.sdk.annotation.Span;
@Span(type = Span.Type.ENTRY, value = "customFrameworkHandler")
public Response handleRequest(Request request) {
// カスタムフレームワークの処理
return processRequest(request);
}
📚 詳細: Tutorial: Instrumenting a custom Java HTTP framework with the Instana Tracing SDK
ケース2: 内部の重い処理(CPU集約的な計算)
メモリ内で複雑な計算やロジックを実行するメソッドは、外部システム(DB/HTTP)を呼び出さないため、デフォルトではスパンが作成されません。
症状: コントローラーのスパンが長時間かかっているが、その内部で何が時間を消費しているか不明
解決策: @Span アノテーションを使用
@Span(type = Span.Type.INTERMEDIATE, value = "calculatePrice")
public BigDecimal calculatePrice(BigDecimal basePrice) {
// 複雑な価格計算ロジック(100ms以上かかる処理)
return basePrice.multiply(new BigDecimal("1.1"));
}
本プロジェクトでの実装: PricingService.calculatePrice メソッド
ケース3: カスタムスレッド/非同期処理
手動でスレッドを生成する場合(例: new Thread(() -> ...).start())や、カスタムExecutorServiceを使用する場合、Instanaの自動コンテキスト伝播が失われる可能性があります。
症状: トレースがスレッド開始時点で終了し、新しいスレッドでの作業が失われるか、無関係なトレースとして表示される
解決策: @Span アノテーションまたは SpanSupport を使用
@Async
@Span(type = Span.Type.INTERMEDIATE, value = "asyncProcessing")
public CompletableFuture<String> processAsync() {
// 非同期処理
return CompletableFuture.completedFuture("完了");
}
注意: Spring の @Async は自動計装されますが、カスタムExecutorServiceの場合はSDKが必要です。
ケース4: ビジネスコンテキストの追加
可視化されている場合でも、ビジネス上重要な情報(ユーザーID、注文金額、顧客タイプなど)をトレースに追加したい場合があります。
目的:
- トレースの検索性向上
- ビジネスメトリクスとの相関分析
- 特定顧客の問題調査
解決策: SpanSupport.annotate() を使用してカスタムタグを追加
import com.instana.sdk.annotation.Span;
import com.instana.sdk.support.SpanSupport;
public void processOrder(Order order) {
// ビジネスコンテキストをトレースに追加
SpanSupport.annotate(Span.Type.INTERMEDIATE, "customer.id", order.getCustomerId());
SpanSupport.annotate(Span.Type.INTERMEDIATE, "order.amount", order.getTotalAmount().toString());
SpanSupport.annotate(Span.Type.INTERMEDIATE, "customer.tier", order.getCustomerTier());
// 注文処理ロジック
}
本プロジェクトでの実装: PricingService.determineDiscount メソッド
ケース5: 設定ベースの計装(Configuration-based SDK)
コードを変更せずに、設定ファイルで計装ポイントを指定したい場合。
メリット:
- ソースコード変更不要
- デプロイ後の計装ポイント変更が可能
- レガシーコードへの適用が容易
設定例: configuration.yaml
com.instana.plugin.javatrace:
instrumentation:
sdk:
packages:
- 'com.example.instana'
methods:
- class: 'com.example.service.PaymentService'
method: 'processPayment'
span:
type: 'INTERMEDIATE'
name: 'payment.processing'
本プロジェクトでの実装例
実装例1: PricingService.calculatePrice
ファイル: src/main/java/com/example/instana/service/PricingService.java
@Span(type = Span.Type.INTERMEDIATE, value = "calculatePrice")
public BigDecimal calculatePrice(BigDecimal basePrice) {
// 複雑な価格計算エンジンをシミュレート
try {
Thread.sleep(100); // 処理時間をシミュレート
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
return basePrice.multiply(new BigDecimal("1.1"));
}
理由: これは複雑な価格計算エンジンをシミュレートしています。@Span がない場合、この処理は InventoryController.saveProduct 内の見えない時間として扱われます。@Span を使用することで、Instanaのウォーターフォールビューで明確なバーとして表示されます。
実装例2: PricingService.determineDiscount
public BigDecimal determineDiscount(String userCategory) {
SpanSupport.annotate(Span.Type.INTERMEDIATE, "user.category", userCategory);
if ("VIP".equals(userCategory)) {
return new BigDecimal("0.20"); // 20%割引
}
return new BigDecimal("0.05"); // 5%割引
}
理由: ビジネスコンテキスト(ユーザーカテゴリ)をトレースに追加し、後で検索やフィルタリングに使用できます。
SDK使用の判断フローチャート
計装が必要な処理がある
↓
[Q1] 使用しているフレームワークは?
├─ Spring MVC/Boot → 自動計装 ✅ SDKなし
├─ JDBC/JPA → 自動計装 ✅ SDKなし
├─ Kafka/RabbitMQ → 自動計装 ✅ SDKなし
└─ カスタム/独自 → SDK必要 ⚠️
↓
[Q2] 処理の種類は?
├─ 外部システム呼び出し(HTTP/DB) → 自動計装 ✅ SDKなし
├─ CPU集約的な内部処理 → SDK必要 ⚠️
└─ カスタムスレッド/非同期 → SDK必要 ⚠️
↓
[Q3] ビジネスコンテキストの追加が必要?
├─ Yes → SDK必要 ⚠️
└─ No → 自動計装で十分 ✅
SDK使用の判断基準一覧表
| シナリオ | SDK必要? | 理由 | 実装方法 |
|---|---|---|---|
| Spring MVC/Boot | 不要 ✅ | 自動計装対象 | - |
| JDBC/JPA/Hibernate | 不要 ✅ | 自動計装対象 | - |
| RestTemplate/WebClient | 不要 ✅ | 自動計装対象 | - |
| Kafka/RabbitMQ/JMS | 不要 ✅ | 自動計装対象 | - |
| カスタムHTTPフレームワーク | 必要 ⚠️ | エージェントが認識しない | @Span(type=ENTRY) |
| CPU集約的な計算処理 | 必要 ⚠️ | I/O呼び出しがない | @Span(type=INTERMEDIATE) |
| カスタムスレッドプール | 必要 ⚠️ | コンテキスト伝播が失われる |
@Span + SpanSupport |
| 独自プロトコル | 必要 ⚠️ | エージェントが認識しない | @Span(type=EXIT) |
| ビジネスタグ追加 | 必要 ⚠️ | 検索性・分析性向上 | SpanSupport.annotate() |
| レガシーコード | 必要 ⚠️ | コード変更が困難 | Configuration-based SDK |
トレースの可視化の違い
SDKなしの場合:
[HTTP POST /inventory/save ---------------------------- 500ms]
[JDBC INSERT ---------------- 50ms]
(450msの「待機時間」が説明されていない)
SDKありの場合:
[HTTP POST /inventory/save ---------------------------- 500ms]
[CustomSpan: calculatePrice ------- 400ms] ← SDKがこれを明らかにする!
[JDBC INSERT ---------------- 50ms]
Instana Java Trace SDKの主要API
1. @Span アノテーション
メソッドレベルでスパンを作成します。
import com.instana.sdk.annotation.Span;
@Span(type = Span.Type.INTERMEDIATE, value = "myCustomOperation")
public void myMethod() {
// 処理
}
パラメータ:
-
type: スパンのタイプ(ENTRY,EXIT,INTERMEDIATE,LOCAL) -
value: スパン名(Instanaダッシュボードに表示される)
2. SpanSupport クラス
プログラマティックにスパンを操作します。
import com.instana.sdk.support.SpanSupport;
// タグの追加
SpanSupport.annotate(Span.Type.INTERMEDIATE, "key", "value");
// 現在のスパンIDの取得
String spanId = SpanSupport.getSpanId();
String traceId = SpanSupport.getTraceId();
3. スパンタイプの説明
| タイプ | 説明 | 使用例 |
|---|---|---|
ENTRY |
サービスへの入口 | HTTPリクエストの受信 |
EXIT |
外部サービスへの呼び出し | データベースクエリ、外部API呼び出し |
INTERMEDIATE |
内部処理 | ビジネスロジック、計算処理 |
LOCAL |
ローカル処理 | ヘルパーメソッド |
Instanaダッシュボードでの確認方法
-
Unbounded Analyticsで検索:
span.name:calculatePrice -
トレース詳細で確認:
- カスタムスパン名(
calculatePrice,determineDiscount)が表示される - スパンの処理時間が可視化される
- カスタムタグ(
user.category: VIP)が表示される
- カスタムスパン名(
-
サービスマップで確認:
- アプリケーション内部の処理フローが可視化される





