MessageLogging ポリシー

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

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` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`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 のようになります。

注: 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}` の代わりに変数を使用できます。
`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 権限を持つロールが必要です。<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` のいずれかになります。サンプルをご覧ください。注: `<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 プロキシ構成リファレンスをご覧ください。

PostClientFlow は、次の 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 要素を設定します。

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

Splunk（プロダクトのバージョンを選択）
Apigee コミュニティの投稿（Splunk へのログメッセージ）もご覧ください。
Sumo Logic
- Apigee コミュニティの投稿（Sumo Logic を使用した Logging の設定）もご覧ください。
- ロギングサービスとして 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 より大きい整数である必要があります。

障害変数

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

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

MessageLogging ポリシー

What

<MessageLogging> 要素

サンプル

CloudLogging

Syslog

TLS / SSL 経由の Syslog

子要素のリファレンス

<CloudLogging>

Cloud Logging の認証

<Syslog>

<logLevel>

使用上の注意

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

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

エラー リファレンス

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

フロー変数

関連トピック

`<MessageLogging>` 要素

`<CloudLogging>`

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

エラーリファレンス

ランタイムエラー

エラーレスポンスの例