1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Spring BootアプリにInstana Trace SDKを計装して可観測化検証してみた

Last updated at Posted at 2026-01-23

はじめに

本記事では、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!

ログインできたら、下記のような画面でています。
Screenshot 2026-01-23 at 20.12.39.png

10.3 商品(Inventory)の追加

  1. ログイン後、「Add New Product」ボタンをクリック
  2. 以下の情報を入力:
    • Product Name: ノートパソコン
    • Description: 高性能ビジネスノートPC
    • Price: 150000
    • Quantity: 10
  3. 「Save」ボタンをクリック

10.4 複数の操作を実行

トレースデータを生成するため、以下の操作を複数回実行します:

  • 商品の追加(3〜5件)
  • 商品一覧の表示(複数回リロード)
  • 商品の編集
  • ログアウト・ログイン

11. Instana SaaSバックエンドでの確認

11.1 アプリケーションの確認

  1. Instana SaaSダッシュボードにログイン

  2. 左メニューから 「Applications」 を選択

  3. 「SpringBoot-instana-demo」 アプリケーションを探す(事前に["Zone名前"-instana-demo]というServiceのApplicationを作成していただければ。)

  4. アプリケーション名をクリックして詳細を表示
    Screenshot 2026-01-23 at 19.49.42.png

  5. ["Zone名前"-instana-demo]というServiceの画面:
    Screenshot 2026-01-23 at 19.57.22.png

  6. 呼び出し分析画面:
    Screenshot 2026-01-23 at 19.50.10.png

確認できる情報:

  • 呼び出し回数(Calls): HTTPリクエストの総数
  • エラー率(Error Rate): エラーが発生したリクエストの割合
  • 平均レスポンスタイム(Latency): リクエストの平均処理時間

11.2 トレース(Trace)の確認

  1. アプリケーション詳細画面で 「Traces」 タブをクリック
  2. 個別のトレースをクリックして詳細を表示
    Screenshot 2026-01-23 at 19.50.43.png

トレース詳細で確認できる情報:

  • HTTP リクエスト: POST /inventory/save, GET /inventory など
  • データベースクエリ: INSERT INTO product, SELECT * FROM product など
  • カスタムスパン: calculatePrice, determineDiscount, ComplexDiscountLogic

カスタムスパンの確認方法

  • トレース詳細画面で calculatePrice というスパン名を探す
  • これは PricingService.java@Span アノテーションで計装されたメソッド

11.3 コールグラフ(Call Graph)の確認

  1. アプリケーション詳細画面で 「Dependencies」 または 「Service Map」 を選択
  2. 以下のコンポーネント間の依存関係が表示されます:
[Browser] → [JackyWindows-instana-demo (Java)] → [instana_demo (MySQL)]

依存関係画面:
Screenshot 2026-01-23 at 19.49.53.png

確認できる情報:

  • サービス間の呼び出し関係: アプリケーションからMySQLへの接続
  • 呼び出し回数: 各エンドポイントへのリクエスト数
  • レスポンスタイム: 各コンポーネントの処理時間

11.4 インフラストラクチャの確認

  1. 左メニューから 「Infrastructure」 を選択
  2. 「Hosts」 でUbuntuホストを探す
  3. ホスト名をクリックして詳細を表示

確認できる情報:

  • CPU使用率
  • メモリ使用率
  • ディスクI/O
  • ネットワークトラフィック
  • 実行中のプロセス(Java、MySQL)

11.5 MySQLメトリクスの確認

  1. 「Infrastructure」「Databases」 を選択
  2. 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が監視されない

確認事項:

  1. configuration.yaml の設定が正しいか確認
  2. user1ユーザーの権限が正しいか確認:
mysql -u user1 -p -e "SHOW GRANTS FOR 'user1'@'localhost';"

12.4 カスタムスパンが表示されない

確認事項:

  1. configuration.yamlcom.instana.plugin.javatrace の設定があるか確認
  2. Instana Agentを再起動
  3. アプリケーションを再起動

補足: 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'

📚 詳細: Configuration-based Java Trace SDK

本プロジェクトでの実装例

実装例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ダッシュボードでの確認方法

  1. Unbounded Analyticsで検索:

    span.name:calculatePrice
    
  2. トレース詳細で確認:

    • カスタムスパン名(calculatePrice, determineDiscount)が表示される
    • スパンの処理時間が可視化される
    • カスタムタグ(user.category: VIP)が表示される
  3. サービスマップで確認:

    • アプリケーション内部の処理フローが可視化される

参考資料

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?