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 に設定します。関連情報:
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 のようになります。

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> の子要素について説明します。

<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（デフォルト）、ALERT、WARN、ERROR です。

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

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 にレイテンシは発生しません。エラーが返されずにログが書き込まれないことがありますが、このような場合はまれです。

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

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

  • 使用中: <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 メッセージを送信できます。これらのサービスの 1 つに Syslog を送信する場合は、そのサービスのドキュメントを参照してサービスのホスト、ポート、およびプロトコルを構成し、それに応じてこのポリシーの Syslog 要素を設定します。

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

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、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

エラー レスポンスの例

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

関連トピック