MessageLogging ポリシー

概要

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

サンプル

<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 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>

<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 のポリシータイプを構成するには、次の要素を使用します。

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

スキーマ

使用上の注意

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 要素を設定します。

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

• Splunk（プロダクト バージョンを選択）
  Apigee コミュニティの投稿（https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html）もご覧ください。
• Sumo Logic
  • この Apigee コミュニティの投稿（https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html）もご覧ください。
  • ログサービスとして Sumo Logic を使用した完全な例については、次の Apigee コミュニティの記事を参照してください。このソリューションでは、1 つの JavaScript ポリシーを使用して、Sumo Logic HTTP Source Collector に HTTP POST リクエストを送信します（https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html）
• Loggly
  Loggly を使用している場合は、<Syslog> 要素の子としてポリシーで <FormatMessage>true</FormatMessage> が必要です。
  Loggly へのメッセージ ロギングの詳細については、Apigee コミュニティの投稿（https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html）をご覧ください。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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

関連トピック

• Edge によって公開される変数: 変数リファレンス