MessageLogging ポリシー

このページは ApigeeApigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

ポリシー アイコン

What

MessageLogging ポリシーでは、カスタム メッセージを Cloud Logging または syslog にロギングできます。これらのログ中の情報は、API ランタイム環境の問題の追跡など、さまざまなタスクに使用できます。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

MessageLogging ポリシーを使用するには、次の 2 つの方法があります。

  • <CloudLogging> 要素は、メッセージを Cloud Logging に記録します。この方法を使用するには、Google Cloud プロジェクトで Cloud Logging API を有効にする必要があります。Google Cloud プロジェクトの API を有効にする方法については、サービスの有効化と無効化をご覧ください。
  • <Syslog> 要素は、システムログまたはイベント メッセージを特定のサーバーに送信するための標準プロトコルである syslog にメッセージを記録します。この方法を使用するには、syslog サーバーを使用できる必要があります。使用できない場合は、Splunk、Sumo Logic、Loggly などの公開ログ管理サービスを使用できます。サードパーティのログ管理サービスの構成をご覧ください。

注: 同じポリシーで <CloudLogging> 要素と <Syslog> 要素の両方を使用することはできません。

<MessageLogging> 要素

<MessageLogging> ポリシーを定義します。

デフォルト値 下記の [デフォルト ポリシー] タブをご覧ください。
必須かどうか 必須
種類 種類
親要素 該当なし
子要素 <CloudLogging>
<Syslog>
<logLevel>

<MessageLogging> 要素の構文は次のとおりです。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

この要素には、すべてのポリシーに共通する次の属性があります。

属性 デフォルト 必須かどうか 説明
name なし 必須

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

continueOnError false 省略可 ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性は非推奨となりました。

次の表は、<MessageLogging> の子要素の概要をまとめたものです。

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

Cloud Logging に記録されるようにメッセージを構成します。

Syslog

syslog に記録されるようにメッセージを構成します。

サンプル

CloudLogging

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
</MessageLogging>

この例では、メッセージ テンプレートの使用方法を示しています。Message 要素にフロー変数が含まれています。

{"{message.queryparam.key}": "{message.queryparam.value}"}

誰かが message.queryparam.key = "fruit"message.queryparam.value = "apple" の値を使用してプロキシを呼び出すと、ログエントリは {"fruit": "apple"} になります。

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>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

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

TLS / SSL 経由の 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>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

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

子要素のリファレンス

以降のセクションでは、<MessageLogging> の子要素について説明します。

<CloudLogging>

<CloudLogging> 要素を使用して、メッセージを Cloud Logging に記録します。

フィールド名 必須かどうか 説明
LogName はい ログの名前。ログの名前は projects/{PROJECT_ID}/logs/{LOG_ID} の形式にします。{PROJECT_ID}{LOG_ID} の代わりに変数を使用できます。
Message はい

ログに記録されるメッセージ。このメッセージには属性 contentType があり、その値は、テキスト メッセージと JSON メッセージでそれぞれ text/plain または application/json のいずれかになります。サンプルをご覧ください。

Label いいえ ログメッセージに添付されるラベル(存在する場合)。これらは、次のような Key-Value ペアの形式になります。

<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>
ResourceType いいえ(デフォルトはグローバル) ログを生成しているモニタリング対象リソースを表します。

Cloud Logging の認証

<CloudLogging> 要素を使用するには、Google 認証を使用するように API プロキシをデプロイする必要があります。Apigee は、Cloud Logging へのアウトバウンド リクエストで指定されたサービス アカウントの ID に対応する認証情報を使用します。詳細については、Google 認証システムの使用をご覧ください。デプロイ時に API プロキシに接続するサービス アカウントには、logging.logEntries.create 権限を持つロールが必要です。<CloudLogging> の Identity and Access Management(IAM)ロールの詳細については、アクセス制御ガイドをご覧ください。

<Syslog>

<Syslog> 要素を使用して、メッセージが syslog に記録されるように構成します。<Syslog> を使用すると、API プロキシは Apigee からリモート syslog サーバーにログメッセージを転送します。この方法を使用するには、syslog サーバーを使用できる必要があります。使用できない場合は、Splunk、Sumo Logic、Loggly などの公開ログ管理サービスを使用できます。サードパーティのログ管理サービスの構成をご覧ください。

フィールド名 必須かどうか フィールドの説明
Message はい

ログに記録されるメッセージ。このメッセージには属性 contentType があり、その値は、テキスト メッセージと JSON メッセージでそれぞれ text/plain または application/json のいずれかになります。サンプルをご覧ください。

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

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

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

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee - - - Message starts here

Apigee で生成される情報は、以下のとおりです。

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

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

PayloadOnly いいえ

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

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

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

FormatMessage をご覧ください。

DateFormat いいえ

各ログメッセージのタイムスタンプのフォーマットに使用するフォーマット テンプレート文字列。デフォルトでは、Apigee は yyyy-MM-dd'T'HH:mm:ss.SSSZ を使用します。このテンプレートの動作については、Java の SimpleDateFormat クラスのドキュメントをご覧ください。その定義によれば、フォーマット文字列の yyyy は年の 4 桁の数字に、MM は月の 2 桁の数字に置き換えられる、といった具合です。

SSLInfo いいえ

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

この要素を含めないか、空白にした場合、デフォルト値は false(TLS / SSL なし)です。


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

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


<logLevel>

<logLevel> 要素の有効な値は、INFO(デフォルト)、ALERTWARNERROR です。

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

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

使用上の注意

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

PostClientFlow は、次の 2 つの点で特殊です。

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

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

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

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

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

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

Apigee はメッセージを単純なテキストとして記録し、リクエストまたはレスポンスが受信された日時、リクエストのユーザー ID、リクエストが送信された送信元 IP アドレスなどの変数を含めるようにロギングを構成できます。

Apigee がメッセージを非同期でログに記録します。ログの書き込み中にレスポンスが返されます。その結果、コールアウトをブロックしても API にレイテンシは発生しません。エラーが返されずにログが書き込まれないことがありますが、このような場合はまれです。

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

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

  • <CloudLoggingg> を使用の場合:
    steps.messagelogging.TooManyPendingLoggingRequest
  • <Syslog> を使用の場合:
    Log message size exceeded. Increase the max message size setting

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

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

デフォルト値は、メッセージ テンプレートの各変数に対して個別に指定できます。たとえば、変数 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 メッセージを送信できます。これらのサービスの一つに Syslog を送信する場合は、そのサービスのドキュメントを参照してサービスのホスト、ポート、およびプロトコルを構成し、それに応じてこのポリシーの Syslog 要素を設定します。

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

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code HTTP status Cause
steps.messagelogging.StepDefinitionExecutionFailed 500 See fault string.
steps.messagelogging.InvalidGoogleCloudLogName 500 This error is thrown when the LogName does not evaluate to the valid format of projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage 500 This error is thrown when the contentType attributes value has been chosen as application/json but the actual message value is not a valid JSON string,
steps.messagelogging.TooManyPendingLoggingRequest 500 This error is thrown when there are more than 2500 pending requests that are yet to be written to Cloud Logging. The 2500 limit is for each Apigee runtime pod. For example, if the traffic is distributed over two instances of Apigee runtime pods, the effective limit is 5000 requests.
-

Deployment errors

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

Error name Cause Fix
InvalidProtocol The deployment of the MessageLogging policy can fail with this error if the protocol specified within the <Protocol> element is not valid. The valid protocols are TCP and UDP. For sending syslog messages over TLS/SSL, only TCP is supported.
InvalidPort The deployment of the MessageLogging policy can fail with this error if the port number is not specified within the <Port> element or if it is not valid. The port number must be an integer greater than zero.

Fault variables

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

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. messagelogging.ML-LogMessages.failed = true

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

関連トピック