本番対応機能

ここで説明するアプリケーションモジュール検出にカスタマイズを適用する場合は、カスタマイズがすでに存在している場合を除き、本番ソースに移動して、ここで説明する機能によって考慮されるようにする必要があります。

Spring Modulith は、Spring Boot アクチュエーターエンドポイントとしてシステムに関するアーキテクチャ情報を公開するサポートを提供するほか、メトリクスとトレースをキャプチャーしてアプリケーションモジュール間の相互作用を観測することもできます。本番対応のアプリケーションでは両方が必要になる可能性が高いため、これらの機能をアクティブ化する最も便利な方法は、次のように Spring Modulith Insight スターターを使用することです。

Spring Modulith インサイトスターターの使用

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-starter-insight</artifactId>
  <version>2.1.0</version>
  <scope>runtime</scope>
</dependency>

dependencies {
  runtimeOnly 'org.springframework.modulith:spring-modulith-starter-insight:2.1.0'
}

これには、アクチュエーターと可観測性のサポートに加え、アクチュエーターの一般的なサポートのための Spring Boot のアクチュエーターの起動が含まれます。アプリケーションを Zipkin (英語) 、Wavefront (英語) などの監視ツールに接続するには、通常 OpenTelemetry (英語) または Brave [GitHub] (英語) を介してさらに依存関係を追加する必要があることに注意してください。詳細については、Spring Boot のリファレンスドキュメントの対応するセクションを参照してください。

アプリケーションモジュールアクチュエーター

アプリケーションモジュール構造は、Spring Boot アクチュエーターとして公開できます。アクチュエーターを有効にするには、上記のように spring-modulith-starter-insight をすでに宣言していない限り、プロジェクトに spring-modulith-actuator の依存関係を追加してください。

Spring Modulith アクチュエーターサポートの使用

Maven
Gradle

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-actuator</artifactId>
  <version>2.1.0</version>
  <scope>runtime</scope>
</dependency>

<!-- Spring Boot actuator starter required to enable actuators in general -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
  <version>…</version>
  <scope>runtime</scope>
</dependency>

dependencies {
  runtimeOnly 'org.springframework.modulith:spring-modulith-actuator:2.1.0'
}

<!-- Spring Boot actuator starter required to enable actuators in general -->
dependencies {
  runtimeOnly 'org.springframework.boot:spring-boot-starter-actuator'
}

アプリケーションを実行すると、modulith アクチュエーターリソースが公開されます。

アクチュエーターの HTTP リソースへのアクセス

GET http://localhost:8080/actuator

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "modulith": { (1)
      "href": "http://localhost:8080/actuator/modulith",
      "templated": false
    }
  }
}

1	`modulith` アクチュエーターリソースがアドバタイズされます。

modulith リソースは次の構造に従います。

表 1: アプリケーションモジュールアクチュエーターの JSON 構造
JSONPath	説明
`$.{moduleName}`	アプリケーションモジュールの技術名。`dependencies.target` のモジュール参照のターゲット。
`$.{moduleName}.displayName`	人間が判読できるアプリケーションモジュールの名前。
`$.{moduleName}.basePackage`	アプリケーションモジュールの基本パッケージ。
`$.{moduleName}.parent`	（オプション）親モジュールの名前。詳細については、xref:fundamentals.adoc#modules.nested を参照してください。
`$.{moduleName}.nested`	ネストされたモジュールの名前（存在する場合）。詳細については、xref:fundamentals.adoc#modules.nested を参照してください。
`$.{moduleName}.dependencies[]`	アプリケーションモジュールのすべての送信依存関係
`$.{moduleName}.dependencies[].target`	依存するアプリケーションモジュールの名前。`{moduleName}` への参照。
`$.{moduleName}.dependencies[].types[]`	ターゲットモジュールに対する依存関係の型。`DEFAULT` (単純型依存関係)、`USES_COMPONENT` (Spring Bean 依存関係)、または `EVENT_LISTENER` のいずれかになります。

モジュールの配置例は次のようになります。

アプリケーションモジュールアクチュエーターのレスポンス例

{
  "a": {
    "basePackage": "example.a",
    "displayName": "A",
    "dependencies": []
  },
  "b": {
    "basePackage": "example.b",
    "displayName": "B",
    "dependencies": [ {
      "target": "a",
      "types": [ "EVENT_LISTENER", "USES_COMPONENT" ]
    } ]
  }
}

アプリケーションモジュールの観測

アプリケーションモジュール間の相互作用をインターセプトすることで、Micrometer スパンが作成され、最終的に Zipkin (英語) や Grafana (英語) などのツールで視覚化できるトレースが生成されます。計測を有効にするには、上記のように spring-modulith-starter-insight をすでに宣言していない限り、プロジェクトに次のランタイム依存関係を追加してください。

Spring Modulith の可観測性サポートの使用

Maven
Gradle

<dependency>
  <groupId>org.springframework.modulith</groupId>
  <artifactId>spring-modulith-observability-core</artifactId>
  <version>2.1.0</version>
  <scope>runtime</scope>
</dependency>

dependencies {
  runtimeOnly 'org.springframework.modulith:spring-modulith-observability-core:2.1.0'
}

アプリケーションイベントの公開用に作成されたメトリクスをカスタマイズする場合は、コンパイルスコープで spring-modulith-observability-api アーティファクトも宣言する必要があります。

可観測性メタデータをパイプするツールに応じて、追加のインフラストラクチャ依存関係を構成する必要があります。詳細については、セットアップにどの依存関係を含めるかについて、対応する Spring Boot ドキュメントを確認してください。

これにより、アプリケーションモジュールの API の一部であるすべての Spring コンポーネントが、呼び出しをインターセプトしてそれらの Micrometer スパンを作成するアスペクトで修飾されます。呼び出しトレースのサンプルを以下に示します。

図 1: サンプルモジュール呼び出しトレース

この特定のケースでは、支払いをトリガーするとオーダーの状態が変更され、オーダー完了イベントがトリガーされます。これは、オーダーの別の状態変更をトリガーするエンジンによって非同期的に取得され、数秒間動作し、順番にオーダーの最終的な状態変更をトリガーします。

観測範囲

モジュールエントリスパン

表 2: タグキー
名前	説明
`module.identifier`	モジュールの識別子。
`module.invocation-type`	呼び出しの種類（「イベントリスナー」または "Bean" ）。
`module.method`	モジュールで実行されるメソッド。
`module.name`	モジュールの名前。

可観測性指標

Spring Modulith は、アプリケーションで公開されるすべてのドメインイベントのデータを 2 つのメトリクスの形式で登録します。

module.events.published – すべてのイベント関連出版物を集計するカウンター。
module.events.published.$moduleIdentifier.$simpleEventTypeName - 個々のイベントをカウントするカウンターであり、ドメイン固有の値でさらに詳細化することができます。

全イベント指標

表 3: カーディナリティの低いキー
名前	説明
`module.event.type`	発行されたイベントの型。
`module.identifier`	モジュールの識別子。
`module.name`	モジュールの名前。

個別イベント指標

表 4: カーディナリティの低いキー
名前	説明
`module.identifier`	モジュールの識別子。
`module.name`	モジュールの名前。

ModulithEventMetricsCustomizer を実装することで、個々のイベントのメトリクスに追加のタグを追加できます。

@Configuration
class ObservabilityConfiguration {

  @Bean
  ModulithEventMetricsCustomizer modulithEventMetricsCustomizer() {

    return metrics -> {

      metrics.customize(MyCustomDomainEvent.class, (event, it) -> {
        it.tags("someTag", event.getValue());
      });
    };
  }
}

個々のドメインイベントを型で参照できること、特定のイベントの値をメトリクスの値に変換できることに注目してください。

規約

Spring Modulith によって作成される指標は、アプリケーション内で Bean として ModulithObservationConvention を指定することでカスタマイズできます。

@Configuration
class ObservabilityConfiguration {

  @Bean
  ModulithObservationConvention observationConvention() {
    return new CustomModulithObservationConvention();
  }
}

デフォルトの実装では、すべての呼び出しを ModulithContext のメソッドに委譲します。