MessageLogging ポリシー

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

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

概要

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>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

次の表は、<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>api</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 のようになります。

注: Host 要素と Port 要素は変数を参照できません。静的な値を含む必要があります。

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 に記録します。

注: <CloudLogging> を使用するには、Google Cloud プロジェクトで Cloud Logging API を有効にする必要があります。Google Cloud プロジェクトに対して API を有効にするには、サービスの有効化と無効化をご覧ください。MessageLogging ポリシーの <CloudLogging> 要素は、Apigee と Apigee ハイブリッドのバージョン v1.7.0 以降で使用できます。

フィールド名	必須かどうか	説明
LogName	はい	ログの名前。ログの名前は projects/{PROJECT_ID}/logs/{LOG_ID} の形式にします。{PROJECT_ID} と {LOG_ID} の代わりに変数を使用できます。 注: LogName には、ログエントリを送信する Cloud Logging ログのリソース名を指定します。MessageLogging ポリシーでは、変数を使用して、LogName エントリごとに異なる一意の名前値を動的に挿入できます。ただし、この方法はおすすめしません。リクエストごとに値が変更される一意のログ名を動的に作成すると、カーディナリティの問題が発生する可能性があるためです。代わりに、LogName には固定された名前のセットから固定された意味のある名前を使用することをおすすめします。
Message	はい	ログに記録されるメッセージ。このメッセージには属性 contentType があり、その値は、テキスト メッセージと JSON メッセージでそれぞれ text/plain または application/json のいずれかになります。サンプルをご覧ください。 注: レスポンス変数は、エラーフローをフォローする PostClientFlow では使用できません。message を使用します。エラーと成功の両方に関するレスポンス情報をログに記録します。使用上の注意もご覧ください。 注: <Message> 要素は、メッセージ テンプレートという動的文字列置換機能をサポートしています。
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 権限を持つロールが必要です。よりきめ細かい制御が必要な場合を除き、サービス アカウントにはより包括的な事前定義ロール roles/logging.logWriter を使用することをおすすめします。<CloudLogging> の Identity and Access Management（IAM）ロールの詳細については、アクセス制御ガイドをご覧ください。

Apigee ハイブリッドでのプロキシのデプロイ

Apigee ハイブリッドを使用している場合、Apigee ハイブリッド用に作成したランタイム サービス アカウントは、プロキシ サービス アカウントの権限を借用して、その代わりに認証された呼び出しを行う必要があります。そのため、Apigee ハイブリッド ランタイム サービス アカウントには、プロキシ サービス アカウントの iam.serviceAccountTokenCreator ロールが必要です。

<Syslog>

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

フィールド名	必須かどうか	フィールドの説明
Message	はい	ログに記録されるメッセージ。このメッセージには属性 contentType があり、その値は、テキスト メッセージと JSON メッセージでそれぞれ text/plain または application/json のいずれかになります。サンプルをご覧ください。 注: <Message>> 要素は、メッセージ テンプレートという動的文字列置換機能をサポートしています。 注: レスポンス変数は、エラーフローに続く PostClientFlow では使用できません。message を使用します。エラーと成功の両方に関するレスポンス情報をログに記録します。使用上の注意もご覧ください。
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（デフォルト）に設定すると、メッセージに固定文字は付加されません。 注: <FormatMessage>false</FormatMessage> を設定した場合でも、ログメッセージに優先度スコアと日付は含まれたままです。メッセージ本文のみを含むようにログメッセージの形式を設定するには、<PayloadOnly>true</PayloadOnly> を設定します。 PayloadOnly をご覧ください。
PayloadOnly	いいえ	true または false（デフォルト）。 この要素を使用すると、FormatMessage で指定された先頭の文字を含めず、Apigee で生成されるメッセージの形式を Syslog メッセージの本文のみを含むように設定されます。 この要素を含めないか、空白にした場合、デフォルト値は false です。 FormatMessage をご覧ください。 注: <PayloadOnly>true</PayloadOnly> の設定は、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（デフォルト）、ALERT、WARN、ERROR です。

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

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

使用上の注意

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

注: 処理がエラー状態になると、response フロー変数は PostClientFlow で使用できないということに特に注意してください。代わりに、message 変数を使用して PostClientFlow の MessageLogging ポリシーで値を設定すれば、エラー状態が以前のコンテキストにあるかどうかを設定できます。詳細と例については、フロー変数のリファレンスをご覧ください。

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

注: ロギングが失敗してもプロキシの呼び出しは継続します。

メッセージ ロギングは最初にバッファに書き込まれるため、メッセージ ロギングが最終的に失敗した場合でも（宛先への接続に失敗した場合など）、API プロキシは正常に実行されます。

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

• <CloudLogging> を使用の場合:

  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）を増やします。

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

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

デフォルト値は、メッセージ テンプレートの各変数に対して個別に指定できます。たとえば、変数 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 コミュニティの投稿（Splunk にメッセージをロギングする）もご覧ください。
• Sumo Logic
  • Apigee コミュニティの投稿（Sumo Logic を使用したロギングの設定）もご覧ください。
  • ロギング サービスとして Sumo Logic を使用した完全な例については、次の Apigee コミュニティの記事を参照してください。（JavaScript と HTTP を使用した Sumo Logic へのロギング）。このソリューションでは、単一の JavaScript ポリシーを使用して、Sumo Logic HTTP ソースコレクタに対して HTTP POST リクエストを行います。
• Loggly
  Loggly を使用している場合は、<Syslog> 要素の子としてポリシーで <FormatMessage>true</FormatMessage> が必要です。
  Loggly へのメッセージ ロギングの詳細については、Apigee コミュニティの投稿（Loggly にメッセージをロギングする）もご覧ください。

エラー リファレンス

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

ランタイム エラー

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

障害コード	HTTP ステータス	原因
steps.messagelogging.StepDefinitionExecutionFailed	500	障害文字列をご覧ください。
steps.messagelogging.InvalidGoogleCloudLogName	500	このエラーは、LogName が projects/{project}/logs/{logid} の有効な形式と評価されない場合にスローされます。
steps.messagelogging.InvalidJsonMessage	500	このエラーは、contentType 属性値が application/json として選択されているが、実際のメッセージ値が有効な JSON 文字列でない場合にスローされます。
steps.messagelogging.TooManyPendingLoggingRequest	500	このエラーは、Cloud Logging に書き込まれていない保留中のリクエストが 2,500 件を超えるとスローされます。2,500 件の上限は、Apigee ランタイム Pod ごとに適用されます。たとえば、トラフィックが Apigee ランタイム Pod の 2 つのインスタンスに分散している場合、実際の上限は 5,000 リクエストです。

-

デプロイエラー

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

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

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

障害変数

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

注: ロギングが失敗してもプロキシの呼び出しは継続します。

ポリシーエラーとメッセージ ロギング エラーには違いがあります。ここでのフロー変数は、ポリシー自体が失敗した場合にのみ代入され、メッセージのロギングが失敗した場合には代入されません。メッセージ ロギングは最初にバッファに書き込まれるため、メッセージ ロギングが最終的に失敗した場合でも（外部 Syslog プロバイダへの接続に失敗した場合など）、API プロキシは正常に実行されるからです。ログを定期的に確認して、ロギングが想定どおりに行われていることを確認してください。

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

エラー レスポンスの例

注: ベスト プラクティスとして、エラー処理でエラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

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

注: ロギングが失敗してもプロキシの呼び出しは継続します。

ポリシーエラーとメッセージ ロギング エラーには違いがあります。ここでのフロー変数は、ポリシー自体が失敗した場合にのみ代入され、メッセージのロギングが失敗した場合には代入されません。メッセージ ロギングは最初にバッファに書き込まれるため、メッセージ ロギングが最終的に失敗した場合でも（外部 Syslog プロバイダへの接続に失敗した場合など）、API プロキシは正常に実行されます。ログを定期的に確認して、ロギングが想定どおりに行われていることを確認してください。

---

関連トピック

• Apigee によって公開されている変数: フロー変数リファレンス