MessageLogging ポリシー

概要

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

サンプル

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 サーバーが必要です。Syslog サーバーがない場合は、Splunk、Sumo Logic、Loggly などのパブリックログ管理サービスを利用できます。サードパーティのログ管理サービスの設定を参照してください。

たとえば、API がコンシューマ アプリから受け取る各リクエストメッセージに関する情報を記録する必要があるとします。値 3f509b58 は、loggly サービスに固有のキー値を表します。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 ログファイルのローテーション ポリシー( sizetime )を指定します。
MaxFileSizeInMB (ローテーション タイプを size とした場合)サーバーがログメッセージを別のファイルに移動するトリガーになるログファイルのサイズを指定します。ログファイルが指定されたサイズに達すると、サーバーは現在のログファイルの名前を変更します。
RotationFrequency (ローテーション タイプを time とした場合)サーバーがログメッセージを別のファイルに移動させるトリガーになる時間を分単位で指定します。指定した時間が経過すると、現在のログファイルの名前が変更されます。
MaxFilesToRetain

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

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

BufferMessage

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

Syslog 宛先

Splunk、Sumo Logic、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(デフォルト)に設定すると、メッセージに固定文字が付加されません。

SSLInfo

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

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


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

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

logLevel

省略可

有効な値: INFO(default)、ALERTWARNERROR

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

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

スキーマ


使用上の注意

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

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

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

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

以下の Trace 画像は、DefaultFaultRule の実行後に、Message Logging ポリシーが 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 以降のバージョンでは、conf_message-logging_max.log.message.size.in.kb プロパティを /opt/apigee/customer/application/message-processor.properties ファイルに設定し、Message Processor を再起動します。

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

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

サードパーティのログ管理サービスの設定

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

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

エラー リファレンス

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

ランタイム エラー

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

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

デプロイエラー

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

エラー名 原因 修正
InvalidProtocol <Protocol> 要素に無効なプロトコルが指定されていると、このエラーが発生し、MessageLogging ポリシーのデプロイに失敗する場合があります。有効なプロトコルは TCP と UDP です。TLS / SSL 経由で Syslog メッセージを送信する場合、使用できるのは TCP だけです。 build
InvalidPort <Port> 要素にポート番号が指定され、これが無効であると、このエラーが発生し、MessageLogging ポリシーのデプロイに失敗する場合があります。ポート番号は 1 以上の整数にする必要があります。 build

障害変数

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

変数 説明
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

関連トピック