MessageLogging 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

MessageLogging 政策允许您将自定义消息记录到 Cloud Logging 或 syslog。您可以将日志中的信息用于各种任务，例如跟踪 API 运行时环境中的问题。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

您可以通过以下两种方式使用 MessageLogging 政策：

• <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	无	必需	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <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>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 服务的键值对。如果您有 Loggly 账号，请使用您的 Loggly 密钥。生成的日志消息将填充四个值：与事务关联的组织、API 代理和环境名称，以及请求消息中查询参数的值。 时间戳的格式将类似于 230704-13:42:17.376，与 DateFormat 元素中指定的格式相符。

注意：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 Hybrid v1.7.0 及更高版本中可用。

字段名称	是否必需？	说明
LogName	是	日志的名称。主题名称应采用 projects/{PROJECT_ID}/logs/{LOG_ID} 格式。您可以使用变量代替 {PROJECT_ID} 和 {LOG_ID}。 注意：LogName 指定要将日志条目发送到的 Cloud Logging 日志的资源名称。通过使用变量，MessageLogging 政策允许您为每个 LogName 条目动态插入不同的唯一名称值；不过，我们不建议您采用这种做法，并建议您不要动态创建值可以随请求而变化的唯一日志名称，因为这可能会导致基数过高的问题。相反，我们建议您从一组固定的名称中为 LogName 选择使用有意义的固定名称。
Message	是	要记录的消息。该消息具有 contentType 属性，该属性的值可以是 text/plain 或 application/json，分别用于文本和 JSON 消息。查看示例。 注意：在完成错误流后，PostClientFlow 中将不提供响应变量。请使用 message。 以记录错误和成功情形下的响应信息。另请参阅使用说明。 注意：<Message> 元素支持名为消息模板的动态字符串替换功能。
Label	否	要附加到日志消息的标签（如有）。 它们将采用键值对的形式，如下所示： <Label> <Key>key1</Key> <Value>value1</Value> </Label>
ResourceType	否（默认为全球）	表示正在生成日志的受监控的资源。

Cloud Logging 身份验证

如需使用 <CloudLogging> 元素，您必须部署您的 API 代理以使用 Google 身份验证。Apigee 将使用与发送到 Cloud Logging 的出站请求中指定的服务账号身份对应的凭据。如需了解详情，请参阅使用 Google 身份验证。

您在部署时附加到 API 代理的服务账号必须拥有包含 logging.logEntries.create 权限的角色。除非您需要更精细的控制，否则我们建议您为服务账号使用包含更多权限的预定义角色 roles/logging.logWriter。如需详细了解 <CloudLogging> 的 Identity and Access Management (IAM) 角色，请参阅访问权限控制指南。

Apigee Hybrid 中的代理部署

如果您使用的是 Apigee Hybrid，则为 Apigee Hybrid 创建的运行时服务账号必须模拟代理服务账号，才能代表该账号进行经过身份验证的调用。因此，Apigee Hybrid 运行时服务账号必须拥有代理服务账号的 iam.serviceAccountTokenCreator 角色。

<Syslog>

使用 <Syslog> 元素配置要记录到 syslog 的消息。使用 <Syslog> 时，API 代理会将日志消息从 Apigee 转发到远程 syslog 服务器。要使用此方法，您必须拥有 syslog 服务器。如果您没有该服务器，也可以使用 Splunk、Sumo Logic 和 Loggly 等公共日志管理服务。请参阅配置第三方日志管理服务。

字段名称	是否必需？	字段说明
Message	是	要记录的消息。该消息具有 contentType 属性，该属性的值可以是 text/plain 或 application/json，分别用于文本和 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)。 消息处理器 UUID。 "Apigee - - - " 如果设置为 false（默认），则消息不会附加这些固定字符。 注意：如果您设置了 <FormatMessage>false</FormatMessage>，则日志消息仍会包含优先级分数和日期。如需将日志消息的格式设置为仅包含消息正文，请设置 <PayloadOnly>true</PayloadOnly>。 请参阅 PayloadOnly。
PayloadOnly	否	true 或 false（默认） 此元素会设置 Apigee 生成的消息的格式，使其仅包含 syslog 消息的正文，不带 FormatMessage 指定的附加字符。 如果您不添加此元素或将其留空，则默认值为 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> 您可以配置 <SSLInfo> 标记，方式与在 TargetEndpoint 上相同，包括启用双向 TLS/SSL，如 API 代理配置参考文档中所述。系统仅支持 TCP 协议。

---

<logLevel>

<logLevel> 元素的有效值包括：INFO（默认）、ALERT、WARN、ERROR。

设置要包含在消息日志中的特定信息级别。

如果您使用 <logLevel> 元素（将其设置为 true），您的设置会影响在附加到消息的 Apigee 生成的信息中计算得出的优先级值（尖括号内的数字）。

使用说明

在将 MessageLogging 政策附加到 API 代理流时，请考虑将其放置在名为 PostClientFlow 的特殊流的 ProxyEndpoint 响应中。PostClientFlow 会在将响应请求发送到发出请求的客户端后执行，可确保所有指标都可供日志记录。如需详细了解如何使用 PostClientFlow，请参阅 API 代理配置参考文档。

注意：务必注意，处理进入错误状态后，PostClientFlow 中不提供响应流变量。相反，您可以使用消息变量在 PostClientFlow 的 MessageLogging 政策中设置值，从而确保无论错误状态是否为先前上下文都设置它们。如需了解详情和示例，请参阅流变量参考文档。

PostClientFlow 有以下两种特别之处：

1. 它仅会作为响应流的一部分执行。
2. 它是在代理进入错误状态后执行的唯一流。

由于无论代理是成功还是失败，系统都会执行它，因此您可以将 MessageLogging 政策放在 PostClientFlow 中，并保证它们始终执行。

以下调试图像显示在 DefaultFaultRule 执行后作为 PostClientFlow 一部分执行的 MessageLogging 政策：

在此示例中，由于 API 密钥无效，Verify API Key 政策导致故障。

下面显示了包括 PostClientFlow 的 ProxyEndpoint 定义：

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

Apigee 将消息记录为简单文本，您可以将日志记录配置为包含变量，例如接收请求或响应的日期和时间、请求中的用户身份、从中发送请求的来源 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 政策允许您将 syslog 消息发送到第三方日志管理服务，例如 Splunk、Sumo Logic 和 Loggly。如果要将 syslog 发送到其中一个服务，请参阅该服务的文档以配置服务的主机、端口和协议，然后相应地设置此政策的 Syslog 元素。

如需了解第三方日志管理配置，请参阅以下文档：

• Splunk（选择产品版本）
  另请参阅以下 Apigee 社区帖子：将消息记录到 Splunk
• Sumo Logic
  • 另请参阅此 Apigee 社区帖子：使用 Sumo Logic 设置 Logging
  • 如需查看使用 Sumo Logic 作为日志记录服务的完整示例，请参阅以下 Apigee 社区帖子。该解决方案使用单项 JavaScript 政策向 Sumo Logic HTTP Source Collector 发出 HTTP POST 请求：使用 JavaScript 和 HTTP 记录到 Sumo Logic
• Loggly
  使用 Loggly 时，政策中需要将 <FormatMessage>true</FormatMessage> 用作 <Syslog> 元素的子元素。
  另请参阅以下 Apigee 社区帖子，详细了解 Loggly 的消息日志记录：“将消息记录到 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。
InvalidPort	如果未在 <Port> 元素中指定端口号或者此端口无效，则 MessageLogging 政策的部署会失败，并显示此错误。端口号必须是大于零的整数。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

注意：日志记录失败后，代理调用会成功

政策错误与消息记录错误之间存在差异。仅当政策本身发生故障时，才会填充流变量，而不是在消息日志记录失败时。因为消息日志记录首先会写入缓冲区，因此即使消息日志记录最终失败（例如，当外部 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 公开的变量：流变量参考文档