MessageLogging ポリシー

概要

API ランタイム環境の問題を探し当てる最善の方法の 1 つは、メッセージを記録することです。独自のメッセージを、ローカル ディスク(Edge for Private Cloud のみ)、または Syslog に記録するため、API に MessageLogging ポリシーを接続して構成できます。

サンプル

Syslog

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

MessageLogging ポリシータイプの一般的な使用法は、Syslog アカウントにログを記録することです。Syslog 用に構成すると、API プロキシはログメッセージを Apigee Edge からリモート Syslog サーバーに転送します。使用可能な Syslog サーバーが必要です。ない場合は、Splunk、Sumo Log、Loggly などの公開ログ管理サービスを利用できます。詳細については、サードパーティのログ管理サービスの構成をご覧ください。

たとえば、API がコンシューマ アプリから受け取る各リクエスト メッセージに関する情報を記録する必要があるとします。値 3f509b58 は、Loggly サービスに固有の Key-Value を表します。Loggly アカウントをお持ちの場合は、Loggly キーを代わりに使用してください。生成されるログメッセージには、次の 4 つの値が代入されます。組織、API プロキシ、トランザクションに関連付けられた環境名、リクエスト メッセージのクエリパラメータの値。

Edge for Private Cloud をデプロイしている場合は、ログメッセージをファイルに書き込むこともできます。

Syslog over TLS / SSL

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

<SSLInfo> ブロックを追加すると、TLS / SSL 経由でサードパーティのメッセージ ロギング プロバイダにメッセージを送信できます。

ファイル ローテーション: サイズ

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

ファイルサイズに基づいたファイル ローテーション。

ファイル ローテーション: 時間

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

時間に基づいたファイル ローテーション。

ファイル ローテーション: 時間とサイズ

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

時間とサイズに基づいたファイル ローテーション。

ストリーム対応

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

ストリーム対応のメッセージ ロギング


要素リファレンス

MessageLogging のポリシータイプを構成するには、次の要素を使用します。

フィールド名 フィールドの説明

File

ローカル ファイルの宛先(ファイル ロギングは、Edge for Private Cloud デプロイでのみサポートされます)。ファイルの保存場所については、Edge for Private Cloud のログファイルの場所をご覧ください。

Message ログファイルに送信するメッセージを作成し、テキストと変数を組み合わせて必要な情報を取得します。サンプルをご覧ください。
FileName メッセージが記録されるログファイルの名前。
FileRotationOptions
rotateFileOnStartup

属性。有効な値: true/false

true に設定すると、メッセージング エンジンが再起動するたびにログファイルがローテートされます。

FileRotationType ログファイルのローテーション ポリシー(size または time)を指定します。
MaxFileSizeInMB (ローテーション タイプとして [size] を選択した場合)サーバーによるログメッセージの別のファイルへの移動をトリガーするログファイルのサイズを指定します。ログファイルが指定されたサイズに達すると、サーバーは現在のログファイルの名前を変更します。
RotationFrequency (ローテーション タイプとして [time] を選択した場合)サーバーによるログメッセージの別のファイルへの移動をトリガーする時間を分単位で指定します。指定した時間が経過すると、現在のログファイルの名前が変更されます。
MaxFilesToRetain

ローテーション設定のコンテキストで保持するファイルの最大数を指定します。

0(ゼロ)を指定すると、ログファイルは無制限に保持され、ファイルのローテーション設定に従いますが、ファイルの削除や名前の変更は行われません。したがって、将来のディスクフル エラーを回避するには、これをゼロより大きい値に設定するか、古い保持ログファイルを定期的にパージまたはアーカイブする自動化されたシステムを実装します。

BufferMessage

プロキシで HTTP ストリーミングが有効になっている場合、リクエスト/レスポンス メッセージはバッファリングされません。フロー メッセージの解析が必要なコンテンツを記録する場合は、BufferMessage を true に設定します。「ストリーム対応」サンプルタブの例を参照してください。デフォルト: false

Syslog 宛先

Splunk、Sumo Log、Loggly に Syslog を送信するには、サードパーティのログ管理サービスの構成をご覧ください。

Message

Syslog に送るメッセージを作成し、テキストと変数を組み合わせて必要な情報を取得します。サンプルをご覧ください。

注: レスポンス変数は、エラーフローをフォローする PostClientFlow では使用できません。メッセージ変数を使用して、エラー時と成功時の両方のレスポンス情報を記録します。使用上の注意もご覧ください。

Host Syslog を送信するサーバーのホスト名または IP アドレス。この要素を指定しない場合、デフォルトは localhost です。
Port Syslog が実行されているポート。この要素を含めない場合、デフォルトは 514 です。
Protocol TCP または UDP(デフォルト)。UDP の方が性能が優れていますが、TCP プロトコルは Syslog サーバーへのメッセージログ配信を保証します。TLS / SSL 経由で Syslog メッセージを送信する場合、使用できるのは TCP だけです。
FormatMessage

true または false(デフォルト)

オプションですが、<FormatMessage>true</FormatMessage> は Loggly で使用する場合は必須です。

この要素を使用すると、メッセージに付加される Apigee 生成コンテンツの形式を制御できます。true に設定すると、Syslog メッセージの先頭に一定の文字数が付加され、メッセージからその情報を除外できます。固定フォーマットの例を次に示します。

<14>1 2016-02-23T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee-Edge - - - Message starts here

Apigee によって生成される情報には、以下が含まれます。

  • <14> - メッセージのログレベルと施設レベルに基づく優先値スコア(Syslog プロトコルを参照)。
  • 1 - 現在の Syslog のバージョン。
  • UTC オフセット(UTC = +0000)の日付。
  • Message Processor UUID。
  • "Apigee Edge - - - "

false(デフォルト)に設定すると、メッセージに固定文字が付加されません。

PayloadOnly

true または false(デフォルト)

この要素では、FormatMessage で指定された先頭の文字を含めず、Syslog メッセージの本文のみを含めるように Apigee で生成されるメッセージの形式を設定します。

この要素を含めない場合、または空のままにした場合、デフォルト値は false です。

FormatMessage をご覧ください。

SSLInfo

SSL / TLS でのメッセージ記録を可能にします。サブ要素 <Enabled>true</Enabled> で使用します。

この要素を含めないか、空のままにすると、デフォルト値は false(TLS / SSL なし)になります。


<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

API プロキシ構成リファレンスで記述されているように、双方向の TLS / SSL を有効にすることを含めて、TargetEndpoint の場合と同様に <SSLInfo> タグを設定できます。TCP プロトコルのみがサポートされます。

logLevel

省略可。

有効な値: INFO(デフォルト)、ALERTWARNERROR

メッセージログに含める特定のレベルの情報を設定します。

FormatMessage 要素(true に設定)を使用している場合、logLevel の設定は、メッセージに追加される Apigee で生成される情報で計算された優先度スコア(山かっこ内の数)に影響します。

スキーマ


使用上の注意

MessageLogging ポリシーを API プロキシフローに接続するときは、PostClientFlow という特殊なフローで ProxyEndpoint レスポンスに配置することを検討してください。PostClientFlow は、レスポンスがリクエスト元のクライアントに送信された後に実行され、すべての指標がログに記録されるようにします。PostClientFlow の使用方法について詳しくは、API プロキシ構成リファレンスをご覧ください。

PostClientFlow は以下の 2 点で特殊です。

  1. レスポンス フローの一部としてのみ実行されます。
  2. プロキシがエラー状態に入った後で実行される唯一のフローです。

PostClientFlow はプロキシの成否に関係なく実行されるため、PostClientFlow に Message Logging ポリシーを含めると、MessageLogging ポリシーは必ず実行されます。

以下の Trace 画像は、DefaultFaultRule の実行後に、MessageLogging ポリシーが PostClientFlow の一部として実行されることを示しています。

この例では、キーが無効なため Verify API Key ポリシーによって障害が生じています。

以下は、PostClientFlow を含む ProxyEndpoint 定義です。

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

Edge はメッセージを単純なテキストとして記録し、リクエストまたはレスポンスが受信された日時、リクエストのユーザー ID、リクエストが送信された送信元 IP アドレスなどの変数を含めるようにロギングを構成できます。Edge はメッセージを非同期でログに記録します。つまり、コールアウトをブロックすることによるレイテンシが API に導入されることはありません。

メッセージ ロギング ポリシーは、メモリに記録されたメッセージをバッファに書き込みます。メッセージ ロガーは、バッファからメッセージを読み取り、設定した宛先に書き込みます。各宛先には独自のバッファがあります。

バッファへの書き込み速度が読み取り速度を超えて増加すると、バッファがオーバーフローし、ロギングが失敗します。このような場合に、ログファイルに次の内容を含むメッセージが表示されることがあります。

Log message size exceeded. Increase the max message size setting

Edge for Private Cloud 4.15.07 以前でこの問題が発生した場合は、message-logging.properties ファイルを見つけて次のソリューションを使用してください。

message-logging.properties ファイルの max.log.message.size.in.kb プロパティ(デフォルト値: 128 KB)を増やします。

Edge for Private Cloud 4.16.01 以降では、/opt/apigee/customer/application/message-processor.properties ファイルで conf_message-logging_max.log.message.size.in.kb プロパティを設定し、Message Processor を再起動します。

注: Edge のレスポンス メッセージ変数は、エラーフローからは使用できません。これらの変数は、前のフローがエラーフローであった場合、PostClientFlow では使用できません。PostClientFlow からのレスポンス情報をログに記録する場合は、message オブジェクトを使用します。このオブジェクトを使用すると、エラーの有無にかかわらず、ヘッダーやその他の情報をレスポンスから取得できます。詳細と例については、メッセージ変数をご覧ください。

Edge for Private Cloud のログ メッセージ タイムスタンプの制御

デフォルトでは、ログメッセージのタイムスタンプの形式は次のとおりです。

yyyy-MM-dd'T'HH:mm:ss.sssZ

例:

2017-05-08T13:33:00.000+0000

Edge Message Processor の conf_system_apigee.syslogger.dateFormat プロパティを使用して、その形式を制御できます。たとえば、メッセージ形式を次のように変更します。

yy/MM/dd'T'HH:mm:ss.sssZ

次の形式でタイムスタンプを記録します。

17/09/01T22:38:11.011+0000

形式の変更方法:

  1. エディタで message-processor.properties ファイルを開きます。ファイルが存在しない場合は作成します。
    > vi /opt/apigee/customer/application/message-processor.properties
  2. 必要に応じてプロパティを設定します。
    conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.sssZ
  3. 変更を保存します。
  4. プロパティ ファイルの所有者を「apigee」ユーザーにします。
    > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  5. Edge Message Processor を再起動します。
    > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud のログファイルの場所

Edge for Private Cloud 4.16.01 以降

デフォルトでは、Private Cloud のメッセージログは、Message Processor ノードの以下のディレクトリにあります。

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

Message Processor の message-logging.properties ファイルのプロパティを変更すると、デフォルトのログの場所を変更できます。

  • bin_setenv_data_dir - ログ ファイル ストレージのルートパスを設定します。例: bin_setenv_data_dir=/opt/apigee/var/log
  • conf_message-logging_log.root.dir - これを相対パス(例: conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.)に設定した場合、

    これを絶対パス(例: conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages)に設定した場合、メッセージログは /opt/apigee/var/log/messages/messagelog/ に保存されます。絶対パスは bin_setenv_data_dir よりも優先されます。

    デフォルトではコメントアウトされるため、プロパティを conf/message-logging.properties+log.root.dir として参照する必要があります。詳しくは、コメントアウトされているトークンの設定をご覧ください。

すべてのログファイルが同じディレクトリに保存されるように、ログファイルをフラット ファイル構造で保存する場合は、message-logging.properties ファイルで conf/message-logging.properties+enable.flat.directory.structure を true に設定します。メッセージは上記のプロパティで指定したディレクトリに保存され、ファイル名は {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename} の形式になります。

プロパティを設定するには:

  1. エディタで message-processor.properties ファイルを開きます。ファイルが存在しない場合は作成します。
    > vi /opt/apigee/customer/application/message-processor.properties
  2. 必要に応じてプロパティを設定します。
    conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
  3. 変更を保存します。
  4. プロパティ ファイルの所有者を「apigee」ユーザーにします。
    > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  5. Edge コンポーネントを再起動します。
    > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud 4.15.07 以前

デフォルトでは、メッセージログは Message Processor 上の次の場所にあります。

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Message Processor の message-logging.properties ファイルのプロパティを変更すると、デフォルトのログの場所を変更できます。

  • data.dir - ログ ファイル ストレージのルートパスを設定します。たとえば、data.dir=/opt/apigee4/var/log とします。
  • log.root.dir - 相対パス(例: log.root.dir=custom/folder/)に設定した場合、パスが data.dir の場所に追加されます。

たとえば、2 つのプロパティを組み合わせると、/opt/apigee4/var/log/custom/folder/messagelog/ にログ ディレクトリが設定されます(/messagelog は自動的に追加されます)。

これを絶対パス(例: log.root.dir=/opt/apigee4/var/log/messages)に設定した場合、メッセージログは /opt/apigee4/var/log/messages/messagelog/ に保存されます。log.root.dir 内の絶対パスは data.dir よりも優先されます。

すべてのログファイルが同じディレクトリに保存されるように、ログファイルをフラット ファイル構造で保存する場合は、Message Processors の message-logging.properties ファイルで enable.flat.directory.structure property を true に設定します。メッセージは上記のプロパティで指定したディレクトリに保存され、ファイル名は {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename} の形式になります。

メッセージ テンプレートの変数のデフォルト値

デフォルト値は、メッセージ テンプレートの各変数に対して個別に指定できます。たとえば、変数 request.header.id を解決できない場合、その値は unknown 値に置き換えられます。

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Message 要素で defaultVariableValue 属性を設定することによって、未解決のすべての変数に共通のデフォルト値を指定できます。

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

サードパーティのログ管理サービスの構成

MessageLogging ポリシーでは、Splunk、Sumo Logic、Loggly などのサードパーティのログ管理サービスに Syslog メッセージを送信できます。これらのサービスの 1 つに Syslog を送信する場合は、そのサービスのドキュメントを参照してサービスのホスト、ポート、およびプロトコルを構成し、それに応じてこのポリシーの Syslog 要素を設定します。

サードパーティのログ管理の設定については、次のドキュメントをご覧ください。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。 これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因
steps.messagelogging.StepDefinitionExecutionFailed 500 障害文字列をご覧ください。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名 原因 修正
InvalidProtocol <Protocol> 要素内で指定されたプロトコルが有効でない場合、MessageLogging ポリシーのデプロイがこのエラーで失敗する場合があります。有効なプロトコルは TCP と UDP です。TLS / SSL 経由で syslog メッセージを送信する場合は、TCP のみがサポートされます。
InvalidPort <Port> 要素内でポート番号が指定されていない、あるいは有効でない場合、MessageLogging ポリシーのデプロイがこのエラーで失敗する場合があります。ポート番号は 0 より大きい整数である必要があります。

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明
fault.name="fault_name" fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name は、障害が発生したポリシーのユーザー指定の名前です。 messagelogging.ML-LogMessages.failed = true

エラー レスポンスの例

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

障害ルールの例

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>


フロー変数

次の変数は、ポリシーの失敗時に代入されます。

  • messagelogging.failed
  • messagelogging.{stepdefinition-name}.failed

関連トピック