このページは 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>
この要素には、すべてのポリシーに共通する次の属性があります。
| 属性 | デフォルト | 必須かどうか | 説明 |
|---|---|---|---|
name |
なし | 必須 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
continueOnError |
false | 省略可 | ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
|
enabled |
true | 省略可 | ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。 |
async |
false | 非推奨 | この属性は非推奨となりました。 |
次の表は、<MessageLogging> の子要素の概要をまとめたものです。
| フィールド名 | フィールドの説明 |
|---|---|
CloudLogging |
Cloud Logging に記録されるようにメッセージを構成します。 |
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 のようになります。
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 |
はい |
ログに記録されるメッセージ。このメッセージには属性 |
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 |
はい |
ログに記録されるメッセージ。このメッセージには属性 |
Host |
いいえ | Syslog を送信するサーバーのホスト名または IP アドレス。この要素を指定しない場合、デフォルトは localhost です。 |
Port |
いいえ | Syslog が実行されているポート。この要素を含めない場合、デフォルトは 514 です。 |
Protocol |
いいえ | TCP または UDP(デフォルト)。UDP の方が性能が優れていますが、TCP プロトコルは Syslog サーバーへのメッセージログ配信を保証します。TLS / SSL 経由で Syslog メッセージを送信する場合は、TCP のみがサポートされます。 |
FormatMessage |
いいえ(Loggly で使用するには <FormatMessage>true</FormatMessage> が必要) |
この要素を使用すると、メッセージに付加される Apigee 生成コンテンツの形式を制御できます。true に設定すると、Syslog メッセージの先頭に一定の文字数が付加され、メッセージからその情報を除外できます。固定フォーマットの例を次に示します。
Apigee で生成される情報は、以下のとおりです。
false(デフォルト)に設定すると、メッセージに固定文字は付加されません。 |
PayloadOnly |
いいえ |
この要素を使用すると、FormatMessage で指定された先頭の文字を含めず、Apigee で生成されるメッセージの形式を Syslog メッセージの本文のみを含むように設定されます。 この要素を含めないか、空白にした場合、デフォルト値は FormatMessage をご覧ください。 |
DateFormat |
いいえ |
各ログ メッセージのタイムスタンプのフォーマットに使用するフォーマット テンプレート文字列。デフォルトでは、Apigee は |
SSLInfo |
いいえ |
SSL / TLS でのメッセージ記録を可能にします。サブ要素 この要素を含めないか、空白にした場合、デフォルト値は 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 ポリシーは、メモリに記録されたメッセージをバッファに書き込みます。メッセージ ロガーは、バッファからメッセージを読み取り、設定した宛先に書き込みます。各宛先には独自のバッファがあります。
バッファへの書き込み速度が読み取り速度を超えて増加すると、バッファがオーバーフローし、ロギングが失敗します。この場合、ログファイルに次のいずれかのメッセージが表示されることがあります。
<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)を増やします。
メッセージ テンプレートでの変数のデフォルト値
デフォルト値は、メッセージ テンプレートの各変数に対して個別に指定できます。たとえば、変数 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 的待处理请求超过 2500 个时,会抛出此错误。2500 限制适用于每个 Apigee 运行时 pod。例如,如果流量分布在 Apigee 运行时 pod 的两个实例上,则有效限制为 5000 个请求。 |
部署错误
在您部署包含此政策的代理时,可能会发生这些错误。
| 错误名称 | 原因 | 修复 |
|---|---|---|
InvalidProtocol |
如果 <Protocol> 元素中指定的协议无效,则 MessageLogging 政策的部署会失败,并显示此错误。有效协议为 TCP 和 UDP。对于通过 TLS/SSL 发送 syslog 消息,系统仅支持 TCP。 |
build |
InvalidPort |
如果未在 <Port> 元素中指定端口号或者此端口无效,则 MessageLogging 政策的部署会失败,并显示此错误。端口号必须是大于零的整数。 |
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.failedmessagelogging.{stepdefinition-name}.failed
関連トピック
- Apigee によって公開されている変数: フロー変数リファレンス