エラーハンドラー

Mule で発生するエラーは、次の 2 つの主要カテゴリのいずれかに分類されます。

システムエラー

システムレベルで例外が発生し、Mule イベントが関係していない場合、システムエラーがスローされます。システムエラーハンドラーは、次の状況で発生した例外を管理します。

  • アプリケーションの起動中。

  • 外部システムへの接続が失敗した場合。

システムエラーが発生すると、Mule は、登録されているリスナーにエラー通知を送信し、エラーを記録し、エラーが接続の失敗によるものであれば再接続戦略を実行します。

システムエラーハンドラーは、Mule では設定できません。

メッセージングエラー

Mule イベントと Mule イベントに含まれるメッセージを処理する Mule アプリケーションのフロー内で問題が発生すると、Mule はメッセージングエラー (​Mule エラー​) をスローします。

Mule メッセージングエラーは複数の方法で処理できます。

  • デフォルトのエラー処理​メカニズムを使用できます。

  • フロー内では、フローの組み込み Error Handler コンポーネント内で ​On-Error コンポーネント​ (On Error Continue および On Error Propagate) をセットアップできます。これらのコンポーネントには、エラーを処理するための任意の数のコンポーネントを含めることができます。

    次の図は、イベントプロセッサー (HTTP Request 操作やデータベース操作など) でエラーがスローされたときの動作を示しています。

    error handling 39be7
  • フロー外では、​Error Handler​ コンポーネントをセットアップし、そのコンポーネントを他のエラーハンドラー設定から参照できます。グローバルエラーハンドラーには、On Error コンポーネントとそのコンテンツを含めることもできます。

  • エラー処理は、フローに存在する ​Try スコープ​内からセットアップすることもできます。スコープ内には組み込みエラーハンドラーが含まれ、その中で On Error コンポーネントとそのコンテンツを設定できます。

メッセージのデフォルトエラー処理の使用

デフォルトでは、未処理のメッセージングエラーは記録され、伝達されます。フローで処理されている Mule メッセージでエラーが発生すると、フローの通常の実行は停止し、プロセスがフローのデフォルトのエラーハンドラーに転送され、そのエラーハンドラーでエラーが伝達されます。

次の例は、エラーを管理するように明示的に設定したエラー処理コンポーネントを使用するのではなく、デフォルトのエラー処理を使用する簡単な Mule アプリケーション設定を示しています。

デフォルトのエラー処理メッセージ

デフォルトのエラー処理の例の XML は次のようになります。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
  <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<http:request-config name="HTTP_Request_configuration" doc:name="HTTP Request configuration" >
  <http:request-connection host="jsonplaceholder.typicode.com" port="80" />
</http:request-config>
<flow name="error-handlers-example" >
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/users"/>
  <http:request method="GET" doc:name="Request" config-ref="HTTP_Request_configuration" path="/somebadrequest"/>
</flow>

この設定で Mule アプリケーションを開始し、​http://0.0.0.0:8081/users​ を (たとえばブラウザーなどに) 読み込むことで HTTP リスナーをトリガーすると、フローは、存在しないファイルに対して HTTP 要求 (​http://jsonplaceholder.typicode.com:80/somebadrequest​) を実行します。結果として、Anypoint Studio コンソールでエラーが記録されて Web ブラウザーに伝達されます。

  • Anypoint Studio コンソールログ

    Studio コンソールはエラーメッセージを出力します。このメッセージは、HTTP GET 要求から返された 404 エラーがデフォルトハンドラー (​OnErrorPropagateHandler​) により伝達されていることを示します。Mule はこのエラーを HTTP:NOT_FOUND​ として識別します。

    ERROR 2021-01-19 18:48:50,392
      [[error-handlers-example].http.requester.HTTP_Request_configuration.11 SelectorRunner]
      [processor: error-handlers-example/processors/0; event: 1d3baf11-5aa0-11eb-b96f-a483e7abe2b5] org.mule.runtime.core.internal.exception.OnErrorPropagateHandler:
    ********************************************************************************
    Message               : HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest' failed: not found (404).
    Element               : error-handlers-example/processors/0 @ error-handlers-example:error-handlers-example.xml:15 (Request)
    Element DSL           : <http:request method="GET" doc:name="Request" config-ref="HTTP_Request_configuration" path="/somebadrequest"></http:request>
    Error type            : HTTP:NOT_FOUND
    FlowStack             : at error-handlers-example(error-handlers-example/processors/0 @ error-handlers-example:error-handlers-example.xml:15 (Request))
    
      (set debug level logging or '-Dmule.verbose.exceptions=true' for everything)
    ********************************************************************************

    Studio コンソールのエラーログは次の情報を表します。

    • Message (メッセージ)​: エラーの説明

    • Element (要素)​: 実行を失敗させ、エラーの原因となった XML 要素

    • Element DSL (要素 DSL)​: 実行を失敗させ、エラーの原因となった XML 要素。DSL 形式で表現されます。

    • Error type (エラー種別)​: Mule アプリケーションで発生した Mule エラーの種別

    • Flowstack (フロースタック)​: フロースタックトレースのエラーログ

      この項目には、Mule イベントを処理した各フローと、イベントを次のフローに送信したプロセッサーのエントリがリストされます。最後のエントリには、イベントの処理中に失敗したフローとプロセッサーが示されます。

      Mule 4.3.0 以降、フロースタックエントリはデフォルトで有効になっています。フロースタックログを無効にするには、​mule.flowTrace​ 設定プロパティを ​false​ に設定することができます。

  • Web ブラウザーへのエラーの伝達

    HTTP:NOT_FOUND​ エラーの説明は、リスナーをトリガーするために使用したブラウザータブに表示されます。

    HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest'
    failed: not found (404).

    この Mule エラーの説明は、次の 2 つの理由でブラウザーに表示されます。

    • デフォルトのエラーハンドラーで On Error Propagate プロセス (​OnErrorPropagateHandler​) を使用しています。

      On Error Propagate コンポーネントによって、フローが失敗し、HTTP リスナーで、見つからないファイルに関連付けられる ​404​ エラーのエラー応答が準備されます。

    • HTTP リスナーでデフォルトのエラー (​error.description​) および成功 (​payload​) 応答を使用してメッセージ本文を返しています。

      カスタム応答が設定されていないため、ブラウザーにエラーの説明が表示されます。

On-Error コンポーネントを使用したメッセージングエラーの処理

デフォルトのエラー処理メカニズムを使用する代わりに ​On-Error コンポーネント​ (On Error Continue および On Error Propagate) を組み込みまたは外部の Error Handler コンポーネント内で使用できます。

次の例は、HTTP リスナーがトリガーされたときに HTTP 要求の結果を返すように Studio で設定された簡単なフローを示しています。​デフォルトのエラー処理の例​とは異なり、この例では、On Error Continue (​on-error-continue​) がフローの組み込み Error Handler (​error-handler​) コンポーネント内で設定され、On Error Continue には、エラーの説明を書き込む Logger が含まれます。

mruntime on error continue

この例の XML は次のようになります。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
  <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<http:request-config name="HTTP_Request_configuration" doc:name="HTTP Request configuration" >
  <http:request-connection host="jsonplaceholder.typicode.com" port="80" />
</http:request-config>
<flow name="error-handlers-normalFlow" >
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/users"/>
  <http:request method="GET" config-ref="HTTP_Request_configuration" path="/somebadrequest"/>
  <logger level="INFO" doc:name="Logger" />
  <error-handler>
    <on-error-continue enableNotifications="true" logException="true" doc:name="On Error Continue" >
      <logger level="ERROR" doc:name="Logger" message="#[error.description]"/>
    </on-error-continue>
  </error-handler>
</flow>

デフォルトのエラー処理の例と同様に、要求されたページが見つからないため、フローは 404 エラーを返し、Mule はこのエラーを HTTP:NOT_FOUND​ エラーとして識別します。 ただし、このケースでは、エラーが伝達されないため、HTTP リスナーをトリガーするために使用したブラウザーのタブは空白になります。On Error Continue を使用すると、例のフローは、ページが見つからなくても、GET 要求の 200 と共に正常終了したかのように処理されます。HTTP リスナーはデフォルトの成功応答の動作 (メッセージ本文として ​payload​ コンテンツを返す) を実行します。ページが見つからなかったため、ブラウザーに表示するコンテンツはありません。このため、ブラウザータブは空白になります。

Studio コンソールには、​OnErrorContinueHandler​ がエラーを処理していることを示すエラーメッセージ (以下の 1 番目の ERROR メッセージ) も出力されます。また、Mule エラーについて説明する (​error.description​。​「Mule エラーのセレクター式」​を参照)、ロガーからの ERROR メッセージ (以下の 2 番目の ERROR) が出力されます。

ERROR 2021-01-19 18:42:04,583
  [[error-handlers-example].http.requester.HTTP_Request_configuration.11 SelectorRunner]
  [processor: error-handlers-normalFlow/processors/0; event: 2a95eaa1-5a9f-11eb-b96f-a483e7abe2b5] org.mule.runtime.core.internal.exception.OnErrorContinueHandler:
********************************************************************************
Message               : HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest' failed: not found (404).
Element               : error-handlers-normalFlow/processors/0 @ error-handlers-example:error-handlers-example.xml:15
Element DSL           : <http:request method="GET" config-ref="HTTP_Request_configuration" path="/somebadrequest"></http:request>
Error type            : HTTP:NOT_FOUND
FlowStack             : at error-handlers-normalFlow(error-handlers-normalFlow/processors/0 @ error-handlers-example:error-handlers-example.xml:15)

  (set debug level logging or '-Dmule.verbose.exceptions=true' for everything)
********************************************************************************

ERROR 2021-01-19 18:42:04,586
  [[error-handlers-example].http.requester.HTTP_Request_configuration.11 SelectorRunner]
  [processor: error-handlers-normalFlow/errorHandler/0/processors/0; event: 2a95eaa1-5a9f-11eb-b96f-a483e7abe2b5] org.mule.runtime.core.internal.processor.LoggerMessageProcessor:
  HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest' failed: not found (404).

On Error Continue (​on-error-continue​) の代わりに On Error Propagate (​on-error-propagate​) を使用して同じ Mule アプリケーションを作成した場合、同じエラーメッセージが Studio コンソールに表示されますが、記録されたエラーメッセージがブラウザーにも表示されます。この動作はデフォルトのエラー処理動作と同じです。どちらも On Error Propagate を使用するためです。

各 On Error コンポーネント内で、定義するエラーパスには任意の数のイベントプロセッサーを組み込むことができるため、特定のエラー種別を必要なだけ正確に処理できます。On-Error コンポーネントで処理する特定の Mule エラーを選択できます。Error Handler コンポーネントは、エラーに一致する最初の On Error コンポーネントにエラーを転送します。

フローレベルでのより複雑なエラー処理設定については、​「Mule 4 の概要: エラーハンドラー」​を参照してください。 On Error Continue および On Error Propagate についての詳細は、​「On-Error コンポーネント」​を参照してください。

グローバルエラーハンドラーの参照

グローバルエラーハンドラーは、同じ方法でエラーを処理する複数のフローまたは Try スコープが必要な場合に役立つ可能性があります。エラーハンドラーへの参照を提供することで、再利用設定を作成できます。

グローバルエラー処理設定の定義

次の XML 設定では、​<configuration doc:name="Configuration" defaultErrorHandler-ref="allErrorHandler" />​ を使用して ​<error-handler name="allErrorHandler"/>​ 設定を参照するデフォルトのエラー処理設定を定義します。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
  <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<http:request-config name="HTTP_Request_configuration" doc:name="HTTP Request configuration" >
  <http:request-connection host="json.typicode.com/" port="80" />
</http:request-config>
<configuration doc:name="Configuration" defaultErrorHandler-ref="allErrorHandler" />
<flow name="someFlow" >
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/users"/>
  <http:request method="GET" doc:name="Request" config-ref="HTTP_Request_configuration" path="/somebadrequest"/>
</flow>
<error-handler name="allErrorHandler" >
  <on-error-continue enableNotifications="true" logException="true" doc:name="On Error Continue" >
    <set-payload value="#[error.description]" doc:name="Set Payload" />
  </on-error-continue>
</error-handler>

Studio UI では、グローバルエラー処理の例は次のようになります。

error handlers global

この例には、エラーを処理するための 2 つの主要なコンポーネントが含まれます。Studio キャンバスに表示される埋め込みコンポーネントを含む Error Handler (​error-handler​) と、キャンバスに表示されないグローバルエラー処理設定です。 UI の例のフロー (​someFlow​) は、Error Handler コンポーネントが Mule アプリケーションのフローの外側にあることを示しています。

要求により HTTP:NOT_FOUND​ エラーが生成されるため、Studio コンソールには、​OnErrorContinueHandler​ がエラーを処理していることを示すエラーメッセージが出力されます。 On Error Continue 設定では、処理するエラーが伝達されません (​On-Error コンポーネントを使用したメッセージングエラーの処理​ を参照)。

XML マークアップで設定を記述する代わりに Studio UI でグローバルエラー処理の例をセットアップする方法は、次のとおりです。

  1. [Error Handler] コンポーネントを ​[Mule Palette (Mule パレット)]​ から Studio キャンバスにドラッグし、​「allErrorHandler」​という名前を付けます。

    このコンポーネントはどのフローにも含まれません。

  2. [On Error Continue] コンポーネントを [Error Handler] コンポーネントにドラッグします。

  3. [Set Payload] コンポーネントを [On Error Continue] コンポーネントにドラッグします。

    [Set Payload] コンポーネントは 1 つの例です。Logger など、他のコンポーネントを使用して、そのコンポーネント内で独自のエラーメッセージを記述することができます。Set Payload の例では、エラーの説明に Mule 変数を使用します (詳細は、​「定義済み変数」​の ​error​ 変数を参照)。

  4. Studio でグローバルエラー処理参照を作成します。

    1. [Global Elements (グローバル要素)]​ をクリックして ​[Global Configuration Elements (グローバル設定要素)]​ を開きます。

      [Global Elements (グローバル要素)]​ は Studio キャンバスの下にあります。

    2. [Global Configuration Elements (グローバル設定要素)]​ で ​[Create (作成)]​ をクリックして ​[Choose Global Type (グローバル種別の選択)]​ ダイアログを開きます。

      error handling global type
    3. ダイアログから ​[Global Configuration (グローバル設定)]​ -→ ​[Configuration (設定)]​ を選択し、​[OK]​ をクリックして、​[Configuration (設定)]​ ダイアログを開きます。

      error handling global config
    4. [Configuration (設定)]​ ダイアログから、​[Default Error Handler (デフォルトのエラーハンドラー)]​ 項目で ​[allErrorHandler]​ を選択し、​[OK]​ をクリックします。

  5. XML で記述された値を使用して、HTTP Listener および HTTP Request コンポーネントをセットアップします。

  6. (Studio キャンバスの下にある) ​[Configuration XML (設定 XML)]​ をクリックして、XML 設定が正しいことを確認します。

フローからのエラー処理設定の参照

この例の一部の要素の設定は XML のみです。

フローは、フローの外側にあるグローバルエラーハンドラーを参照できます。フローはそのすべてのエラーを、参照を介して記録します。

例: アプリケーションの XML 設定
<error-handler name="loggingErrorHandler">
    <on-error-continue>
        <logger message="#['Error: ' ++ error.description]"/>
    </on-error-continue>
</error-handler>

<flow name="withSharedHandler">
    <http:request url="http://example.com"/>
    <error-handler ref="loggingErrorHandler"/>
</flow>

この XML の例では、グローバルエラーハンドラーは、​loggingErrorHandler​ という名前の ​<error-handler/>​ 要素を介して設定されます。フローは ​<error-handler ref="loggingErrorHandler"/>​ を使用してエラーハンドラーを参照します。

Studio でフローからグローバルエラーハンドラー設定を参照する手順は、次のとおりです。

  1. Studio で、​[Error Handler]​ コンポーネントを ​[Mule Palette (Mule パレット)]​ からキャンバスにドラッグし、UI を使用してそのコンポーネントを設定します。

  2. Mule アプリケーションで、(Studio キャンバスの下にある) ​[Configuration XML (設定 XML)]​ をクリックします。

  3. (XML のみの設定) ​<flow/>​ 要素内で、参照の XML を入力します (例: <error-handler ref="loggingErrorHandler"/>​)。

次の例では、​<error-handler/>​ 要素内の ​<on-error ref="loggingErrorHandler"/>​ を使用してグローバル On Error Continue 要素 (​<on-error-continue/>​) を参照します。 どちらも、UI ではなく、​[Configuration XML (設定 XML)]​ を介した手動設定が必要です。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
	<http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<on-error-continue name="loggingErrorHandler">
    <logger message="#['Error: ' ++ error.description]" level="INFO"/>
</on-error-continue>

<flow name="withSharedHandler">
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/"/>
  <http:request url="http://jsonplaceholder.typicode.com/badrequestbad" method="GET"/>
  <error-handler >
    <on-error ref="loggingErrorHandler"/>
  </error-handler>
</flow>