メッセージログポリシー

ポリシー名

メッセージログ

概要

受信した要求からの情報、バックエンドからの応答、または同じ API エンドポイントに適用されている他のポリシーからの情報を使用してカスタムメッセージを記録する

カテゴリ

トラブルシューティング

使用可能な最小 Flex Gateway バージョン

v1.0.0

返される状況コード

このポリシーの戻りコードは存在しません

概要

メッセージログポリシーは、受信した要求からの情報、バックエンドからの応答、または同じ API エンドポイントに適用されている他のポリシーからの情報を使用してカスタムメッセージを記録します。

前提条件

Anypoint Platform 組織のシステム管理者ロールか、API を作成または管理するための権限が必要です。

ポリシーのパラメーターの設定

Flex Gateway のローカルモード

ローカルモードでは、宣言型の設定ファイルを使用してメッセージログポリシーを API に適用します。以下のポリシー定義とパラメーターの表を参照してください。

- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration: <array>
      - itemName: <string> // REQUIRED
        itemData: //REQUIRED
          message: <dataweave> // REQUIRED
          conditional: <dataweave> // OPTIONAL
          category: <string> // OPTIONAL
          level: <string> // REQUIRED
          firstSection: <bool> // OPTIONAL
          secondSection: <bool> // OPTIONAL

パラメーター必須または省略可能デフォルト値説明

パラメーター	必須または省略可能	デフォルト値	説明
`loggingConfiguration`	必須	なし	設定の配列
`loggingConfiguration.itemName`	必須	なし	設定名。
`loggingConfiguration.itemData.message`	必須	なし	メッセージログに解決される DataWeave 式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。
`loggingConfiguration.itemData.conditional`	省略可能	`true`	メッセージをログに記録するかどうかに解決される DataWeave 式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。
`loggingConfiguration.itemData.category`	省略可能	デフォルトカテゴリ	ログが実行されたパッケージとクラスを示すログメッセージプレフィックス。
`loggingConfiguration.itemData.level`	必須	なし	記録するメッセージのレベル (`INFO (情報)`、`WARN (警告)`、`ERROR` (エラー)、`DEBUG (デバッグ)`) を定義します。詳細は、メッセージログの重要度レベルを参照してください。
`loggingConfiguration.itemData.firstSection`	省略可能	`false`	このポリシーが適用される順序を考慮して、API エンドポイントがコールされる前にメッセージが記録されるかどうかを示す Boolean (ブール)。
`loggingConfiguration.itemData.secondSection`	省略可能	`false`	このポリシーが適用される順序を考慮して、API エンドポイントがコールされた後にメッセージを記録するかどうかを示す Boolean (ブール)。

loggingConfiguration

必須

なし

設定の配列

loggingConfiguration.itemName

必須

なし

設定名。

loggingConfiguration.itemData.message

必須

なし

メッセージログに解決される DataWeave 式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。

loggingConfiguration.itemData.conditional

省略可能

true

メッセージをログに記録するかどうかに解決される DataWeave 式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。

loggingConfiguration.itemData.category

省略可能

デフォルトカテゴリ

ログが実行されたパッケージとクラスを示すログメッセージプレフィックス。

loggingConfiguration.itemData.level

必須

なし

記録するメッセージのレベル (INFO (情報)、WARN (警告)、ERROR (エラー)、DEBUG (デバッグ)) を定義します。
詳細は、メッセージログの重要度レベルを参照してください。

loggingConfiguration.itemData.firstSection

省略可能

false

このポリシーが適用される順序を考慮して、API エンドポイントがコールされる前にメッセージが記録されるかどうかを示す Boolean (ブール)。

loggingConfiguration.itemData.secondSection

省略可能

false

このポリシーが適用される順序を考慮して、API エンドポイントがコールされた後にメッセージを記録するかどうかを示す Boolean (ブール)。

リソースの設定例

- policyRef:
    name: message-logging-flex
  config:
    loggingConfiguration:
      - itemName: "Config 1"
        itemData:
          message: "#[payload]"
          conditional: "#[attributes.queryParams['QueryParam']=='someValue']"
          level: "ERROR"
          firstSection: true
      - itemName: "Config 2"
        itemData:
          message: "#['literal string']"
          level: "WARN"
          secondSection: true
          firstSection: true

Flex Gateway の接続モード

UI を使用してメッセージログポリシーを API に適用する場合は、以下のパラメーターを設定できます。

パラメーター	説明	必須?
Message (メッセージ)	ログに記録するメッセージを抽出する DataWeave 式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。	必須
条件付き	メッセージをログに記録するかどうかを指定する DataWeave ブール式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。	省略可能
カテゴリ	ログが実行されたパッケージとクラスを示すログメッセージのプレフィックス。	省略可能
レベル	記録するメッセージのレベル (INFO (情報)、WARN (警告)、ERROR (エラー)、DEBUG (デバッグ))。詳細は、メッセージログの重要度レベルを参照してください。	必須
Before Calling API (API のコール前)	このポリシーが適用される順序を考慮して、API エンドポイントがコールされる前にメッセージを記録するようにログポリシーを設定します。	省略可能
After Calling API (API のコール後)	このポリシーが適用される順序を考慮して、API エンドポイントがコールされた後にメッセージを記録するようにログポリシーを設定します。	省略可能

パラメーター

説明

必須?

Message (メッセージ)

ログに記録するメッセージを抽出する DataWeave 式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。

必須

条件付き

メッセージをログに記録するかどうかを指定する DataWeave ブール式。サポートされる DataWeave 式についての詳細は、DataWeave 式のサポートを参照してください。

省略可能

カテゴリ

ログが実行されたパッケージとクラスを示すログメッセージのプレフィックス。

省略可能

レベル

記録するメッセージのレベル (INFO (情報)、WARN (警告)、ERROR (エラー)、DEBUG (デバッグ))。
詳細は、メッセージログの重要度レベルを参照してください。

必須

Before Calling API (API のコール前)

このポリシーが適用される順序を考慮して、API エンドポイントがコールされる前にメッセージを記録するようにログポリシーを設定します。

省略可能

After Calling API (API のコール後)

このポリシーが適用される順序を考慮して、API エンドポイントがコールされた後にメッセージを記録するようにログポリシーを設定します。

省略可能

UI から設定するメッセージログポリシーの例

メッセージログポリシーの使用方法をよく理解できるように、Les Vetments という架空の洋品小売業者を考えてみましょう。E コマースポータルを正常に運営するため、Les Vetments は Web サイト上で実行された要求の状況コードを監査する必要があります。

たとえば、顧客が商品を購入または返品したり、会社がカタログの商品を追加または削除したりした場合には、トランザクションを記録する必要があります。Les Vetments の IT マネージャーは、会社の API にメッセージログポリシーを適用して、コードを変更することなくあらゆるデータやトランザクションの変更を記録して表示できるようにします。

受信および送信 HTTP メッセージの属性を記録するため、Les Vetments では、次の UI 設定でメッセージログポリシーを API に適用します。

Message (メッセージ): #[属性]

ペイロード中の属性を記録する必要があります。
Conditional (条件): 空白

Les Vetments ではすべての属性を必要とするため、メッセージを絞り込むための式は指定しません。
Category (カテゴリ): 空白

ログ文ではプレフィックスは不要です。
Level (レベル): Info (情報)

すべての種別のメッセージを記録します。Info (情報) ログレベルには、Warn (警告)、Error (エラー)、Debug (デバッグ) ログメッセージも含まれます。
Before Calling API (API のコール前): オン

API のコール前に発生したすべてのトランザクションが記録されます。
After Calling API (API のコール後): オン

API のコール後に発生したすべてのトランザクションが記録されます。

この設定後は、顧客が Les Vetments のカタログにアクセスしたり、カートの商品を追加または削除したり、Les Vetments のカタログの商品が追加または削除されたりするたびに、ログが生成されます。

**********************************************************************
* Policy: message-logging-1351146-proxy                              *
* OS encoding: UTF-8, Mule encoding: UTF-8                           *
*                                                                    *
**********************************************************************
21:56:50.147     11/30/2020     Worker-0     [MuleRuntime].uber.06: [message-logging-771181-proxy].771181-message-logging.CPU_LITE @71625864     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpRequestAttributes
{
   Request path=/proxy/1
   Raw request path=/proxy/1
   Method=GET
   Listener path=/proxy/*
   Local Address=/172.25.159.101:8081
   Query String=
   Relative Path=/proxy/1
   Masked Request Path=/1
   Remote Address=/18.191.37.179:21836
   Request Uri=/proxy/1
   Raw request Uri=/proxy/1
   Scheme=http
   Version=HTTP/1.1
   Headers=[
      host=logging-policy.us-e2.cloudhub.io
      x-real-ip=204.14.236.154
      accept=*/*
      user-agent=curl/7.54.0
      x-forwarded-for=204.14.236.154
      x-forwarded-port=80
      x-forwarded-proto=http
      x-sigsci-agentresponse=200
      x-sigsci-mac=7caf3820a5c07d06ef827f1565678167
   ]
   Query Parameters=[]
   URI Parameters=[]
}
21:56:50.254     11/30/2020     Worker-0     [MuleRuntime].uber.07: [logging-policy].proxy.CPU_LITE @f0ce617     INFO
event:184152a0-3370-11eb-b732-0a8c1820c088 org.mule.extension.http.api.HttpResponseAttributes
{
   Status Code=200
   Reason Phrase=OK
   Headers=[
      date=Tue, 01 Dec 2020 00:56:50 GMT
      content-type=application/json; charset=utf-8
      set-cookie=__cfduid=d8afa23a4627ebef39cbc54fea223cb231606784210; expires=Thu, 31-Dec-20 00:56:50 GMT; path=/; domain=.typicode.com; HttpOnly; SameSite=Lax
      x-powered-by=Express
      x-ratelimit-limit=1000
      x-ratelimit-remaining=999
      x-ratelimit-reset=1606784265
      vary=Origin, Accept-Encoding
      access-control-allow-credentials=true
      cache-control=max-age=43200
      pragma=no-cache
      expires=-1
      x-content-type-options=nosniff
      etag=W/"53-hfEnumeNh6YirfjyjaujcOPPT+s"
      via=1.1 vegur
      cf-cache-status=MISS
      accept-ranges=bytes
      cf-request-id=06bd666d0a0000386b7a1fc000000001
      expect-ct=max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
      report-to={"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report?s=qUAIXoQ7qqqvFzjcwGrmK2r2PcSfDZ75jFJd0Gi0BLBUMHAcnC9wJ9I%2FEHJtk%2Bra%2FXWqkA%2F5%2FlzoWoC6YS2Lew%2BqKgjhaphHqx5WrZ0CKHMalhcM9it%2Fks0qzQGwbsRzQg%3D%3D"}],"group":"cf-nel","max_age":604800}
      nel={"report_to":"cf-nel","max_age":604800}
      cf-ray=5fa8d9c1a8c6386b-IAD
   ]
}
12:18:31.770     11/18/2020     Worker-0     agw-policy-set-deployment.01     INFO
Applied policy message-logging-1351146 version 1.0.0 to API testLoggingNew-v1-v1:16481163 (16481163) in application messagelogtext
コンテンツを展開する

ヘッダーを記録するため、Les Vetments では [Message (メッセージ)] 項目で次のコードスニペットを使用します。

#[attributes.headers]

イベントや実行したアクションに基づいてログメッセージをカスタマイズするため、Les Vetments では [Message (メッセージ)] 項目で次のコードスニペットを使用します。

#['User ' authentication.clientId ' performed action ' attributes.method ' on ' attributes.requestPath ' with Payload: ' ++ payload]

DataWeave 式のサポート

メッセージログポリシーでは、『Flex Gateway でサポートされる標準の DataWeave 式』と次に挙げた追加の『vars』 DataWeave 式がサポートされています。以下の式の形式は #[vars.<expressions>] となります。

orgId
masterOrgId
envId
apiId
apiName
apiInstanceName
apiVersion
receivedTs (rfc3339)
repliedTs (rfc3339、要求コンテキストでのみ使用可能)
runtimeVersion (例: v1.7.0)
hostId (例: my-host)
remoteAddress
method
requestPath
reqId (traceId)
requestDisposition (PROCESSED または VIOLATION、要求コンテキストでのみ使用可能)
request.headers (すべてのリクエストヘッダー)
violation.clientId (要求コンテキストでのみ使用可能)
violation.clientName (要求コンテキストでのみ使用可能)
violation.policyName (要求コンテキストでのみ使用可能)
violation.violationType (VIOLATION または ERROR、要求コンテキストでのみ使用可能)

ポリシーのしくみ

ポリシーのログ記録は次の順序で実行されます。

要求が API に送信されます。
次の条件を満たす場合は、メッセージがログに記録されます。
- ポリシーに定義されているログのレベルとカテゴリが、設定ファイルに定義されたロガーに含まれている。
- ポリシーの [Conditional (条件付き)] 項目が設定されていないか、または設定されている条件が満たされた。
API 応答が返されます。メッセージログポリシーは、ポリシーやフローの実行に干渉しません。
メッセージがアプリケーションログに表示されます。

ログ形式について

メッセージログの形式は次のとおりです。

<date> [flex-gateway-envoy][<level>] wasm log <policy-name>.default.<api-name>.default.svc main: [req: <request uuid>] [accessLog] <message>

policy-name: ポリシーバインドの名前を表示します。
api-name: API インスタンスの名前を表示します。
request uuid: メッセージをトリガーした要求の一意の識別子を表示します。

イベント中の状態の記録

メッセージのログは、要求フロー中に特定の間隔で発生します。

API フローをログに記録する前:
API フローをログに記録した後:
API フローの後のエラーハンドラー:

メッセージログの重要度レベル

API インスタンスのメッセージログポリシーを設定するときに、重要度レベルを割り当てることができます。ログレポートの各重要度レベルには、特定の情報セットが含まれます。

ログレポートには、選択した重要度レベルと階層の下位のレベルが含まれます。

たとえば、[DEBUG (デバッグ)] を選択した場合、ログレポートには [DEBUG (デバッグ)] 重要度レベルに加えて、[INFO (情報)]、[WARN (警告)]、[ERROR (エラー)] の重要度レベルが含まれます。ただし、[ERROR (エラー)] を選択した場合、ログレポートにはエラーメッセージのみが含まれます。次の表で、各重要度レベルのログに含まれる情報の種別について説明します。

ログの重要度レベル	説明
DEBUG	アプリケーション開発者が使用するトレース情報。
INFO	アプリケーションの進行状況を強調する情報メッセージ。
WARN	潜在的な問題を示す、有害な可能性がある状況。
ERROR	通常のプログラムの実行は妨げられ、アプリケーションの実行は継続できる可能性があるイベント。

ログの重要度レベル

説明

DEBUG

アプリケーション開発者が使用するトレース情報。

INFO

アプリケーションの進行状況を強調する情報メッセージ。

WARN

潜在的な問題を示す、有害な可能性がある状況。

ERROR

通常のプログラムの実行は妨げられ、アプリケーションの実行は継続できる可能性があるイベント。