• 1．Spring Boot Actuatorとは？
• 2．Spring Boot Actuatorを使うための準備
• 3．追加されるエンドポイント
• 4．Spring Boot Actuatorの使い方
• 5．Spring Boot Actuatorを使ううえでの注意事項

アプリケーションは開発したら終わりではなく、次のステップとして「運用」が待ち構えています。
その運用する際に役立つ機能を提供するのが「Spring Boot Actuator」です。

本記事では、運用における「Spring Boot Actuator」の活用について解説します。

1．Spring Boot Actuatorとは？

Spring Boot Actuatorは、Spring Bootで開発したアプリケーションの監視や管理といった機能を提供する、「運用向け」のSpringライブラリです。

Actuator（アクチュエータ）は、元々機械や電気といった世界で利用される、機械や電気回路を駆動させ動作を制御する「駆動装置」を指します。

Spring Boot Actuatorは、Spring Bootで開発したアプリケーションを外部から制御させることを目的として利用します。

2．Spring Boot Actuatorを使うための準備

まずは、Spring Boot Actuatorを利用するための準備からはじめましょう。

①前提条件

前提条件として、Spring Bootのプロジェクトが作成済みであることとします。

既存のプロジェクトがない場合には、Spring Initializr等を利用してWebアプリのひな型を作成しましょう。

②依存関係を定義する

Spring Boot Actuatorは、対応する依存関係を追加するだけで簡単に有効化できます。

Spring Bootの場合、MavenかGradleを利用しているので、利用しているプロジェクトに応じて追加してください。

依存関係を追加したうえでSpring Bootアプリを実行するだけで、Spring Boot Actuatorのエンドポイントが利用できます。

Mavenの場合

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

Gradleの場合

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

3．追加されるエンドポイント

Spring Boot Actuatorを有効化することで、Spring Bootアプリに「エンドポイント」が追加されます。

アプリケーションのURLとエンドポイントを組み合わせることで、そのエンドポイントへアクセスできるようになるのです。

例えば、「beans」というエンドポイントを利用したい場合には、以下のURLにアクセスします。

http://localhost:8080/actuator/beans

ここでは、有効化されるエンドポイントのうち、利用率の高いエンドポイントを紹介します。

①health

healthエンドポイントを利用することで、アプリが正常に起動しているかを確認できます。

アプリが正常に動作するかを確認するシンプルなエンドポイントで、デフォルトで有効化されています。

②beans

beansエンドポイントを利用することで、SpringがDIコンテナ上で管理しているBeanの情報を確認できます。

自動で生成されたBeanも含みすべてのBeanが一覧で取得できるので、アプリケーションをデバッグする際に役に立ちます。

③env

envエンドポイントを利用すると、Spring Bootが実行するマシンや仮想環境に設定されている環境変数を取得できます。

本番環境と開発環境で異なるデータベースを利用する場合には、環境変数で接続先を変更することもあるでしょう。
その場合には、envエンドポイントを利用することで、正しい環境変数が利用されているかを確認できます。

④loggers

loggersエンドポイントを利用することで、アプリのログを取得できます。

実際にコンソールに出力される内容がそのまま取得されるので、エラーが発生した場合のスタックトレースも簡単に取得できます。

⑤metrics

metricsエンドポイントを利用することで、アプリケーションに関するメトリクス情報を取得できます。

メトリクスには、JVMのCPUやメモリの使用率、ディスクの使用量といった情報が含まれています。

DataDogやElasticsearchといったモニタリングシステムと連携することで、より高い監視の実現も可能です。

4．Spring Boot Actuatorの使い方

Spring Boot Actuatorにはどのような機能が存在するかを確認したところで、実際の使い方を見てみましょう。

①エンドポイントの有効化/無効化

Spring Boot Actuatorの導入直後には、セキュリティの観点から一部のエンドポイントしか有効化されていません。

application.propertiesに必要なエンドポイント名を指定することで、そのエンドポイントが利用可能となります。

例えば、以下の例だとbeanとenv、そしてhealthを有効化しています。

management.endpoints.web.exposure.include=beans,env,health

また、ワイルドカードである「*」を指定することで、すべてのエンドポイントが有効化されます。

management.endpoints.web.exposure.include=*

詳しくは後述しますが、すべてのエンドポイントを有効化するのは推奨されていません。あくまでも、「どんなエンドポイントが存在するのか確認する」という目的のためだけに利用しましょう。

②ログレベルの取得・変更

アプリの実行ログには「ログレベル」が存在しますが、一般的には本番環境や検証環境では出力するログレベルをINFO以上とすることが多いです。

しかしながら、一時的な調査のためにデバッグ用のログを出力したい場合もあります。

そんな場合には、loggersエンドポイントに対してログレベルを送信することで、アプリの再起動をせずに出力するログレベルを変更できます。

ログレベルを変更する

デバッグのため、すべてのログを取得できるようにログレベルを「TRACE」へ変更してみましょう。

ログレベルを変更するためには、Webアプリケーションの「loggers」エンドポイントに対し、POSTでデータを送信します。

Windowsの場合は、PowerShellを用いて以下のコマンドを実行することでデータを送信できます。

Invoke-RestMethod -Method Post -Uri　http://localhost:8080/actuator/loggers/org.springframework -Headers @{"Content-type"="application/json"} -Body '{"configuredLevel": "TRACE"}'

このとき、POSTで送信する内容に「‘{“configuredLevel”: “TRACE”}’」指定することで、アプリが出力するログレベルをTRACEへ変更できます。

ログレベルを取得する

変更が完了したら、loggersエンドポイントへアクセスして設定内容を取得します。

以下のようにGETリクエストを送信し、設定内容を確認しましょう。

Invoke-RestMethod -Method Get -Uri http://localhost:8080/actuator/loggers/org.springframework

すると、以下のように現在の設定内容が取得できます。

configuredLevel effectiveLevel
--------------- --------------
TRACE           TRACE

③ヘルスチェック

healthエンドポイントにアクセスした際に、アプリが正常に動作している場合には以下のように「UP」が取得されます。

{"status":"UP"}

アプリが正常に動作しているかを外部から確認することを「ヘルスチェック」と呼びます。

実際の運用において、この「ヘルスチェック」は非常に重要です。

ヘルスチェックを定期的に実行し、サーバーの動作の安定性や停止していないかを確認します。

もしヘルスチェックに失敗した場合には、「何かしらの問題が発生している」ことが検知できるので、いち早く障害発生を検知できるのです。

5．Spring Boot Actuatorを使ううえでの注意事項

Spring Boot Actuatorは便利な反面、外部からアプリを制御できるため思わぬ障害を生み出す可能性も。

例として、以下のようなことが発生する可能性があります。

・開発者の誤操作によりアプリが停止した

・Actuatorのエンドポイントに対してDDoS攻撃された

・悪意のある第三者にアプリのログを盗まれた

Spring Boot Actuatorはアプリ自体の動作に作用する機能を多く有しています。

特に本番環境については、間違った操作による誤動作や、外部からの攻撃を最小限に抑えるように気をつけましょう。

Spring Boot Actuatorを導入する際に注意すべき点を解説していきます。

①実際に使うエンドポイントのみ公開する

公開するエンドポイントは必要最低限にしましょう。

エンドポイントは、家や建物においては「入口」に例えることができます。

エンドポイントが多いということは、第三者からすると「攻撃しやすい（ピッキングしやすい）入口が多い」と同義です。

入口がなければ攻撃されるリスクも低くなり、開発者が間違って入ることもなくなります。

場合によっては、本番環境ではエンドポイントをすべて無効化することも考えると良いでしょう。

②本番環境で使用する場合はアクセス制御をつける

本番環境はすべてのエンドポイントを無効化することでリスクを最小限に抑えることはできますが、監視するにあたってはログやメトリクスなどの情報が必要です。

とはいえ、これらの情報は漏洩するとセキュリティ事故に直結する場合もあります。

本番環境でエンドポイントを公開する場合には、必ずアクセス制御を設けましょう。

Spring Securityと組み合わせることで、アクセス元やユーザーに応じた適切なアクセス権を付与できます。

③脆弱性の高いバージョンは利用しない

Spring Boot Actuatorに限らず、ライブラリには脆弱性が発見されることがあります。

この脆弱性を放置してしまうこと、簡単にアプリケーションやサーバーが乗っ取られ、機密情報が漏洩するという可能性もあるのです。

エンドポイントの制限やアクセス制御を適切に設定したとしても、この脆弱性を利用することで予期しない攻撃を受ける場合があります。

Spring Bootを含むすべてのライブラリに脆弱性が発見されていないかを確認し、脆弱性があるバージョンを利用しているようであればただちにバージョンアップしましょう。

常に適切なバージョンのライブラリを利用するよう、心がけることが重要です。

※掲載された社名、製品名は、各社の商標及び登録商標です。