MessageLogging 政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

跟踪 API 运行时环境问题的最佳方法之一是记录消息。您可以在 API 上附加并配置 MessageLogging 政策，以将自定义消息记录到本地磁盘（仅适用于 Private Cloud）或 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>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

<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>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

元素参考

请使用以下元素配置 MessageLogging 政策类型。

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

架构

使用说明

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

PostClientFlow 有以下两种特别之处：

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

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

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

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

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

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

Edge 会以简单文本形式记录消息，并且您可以将日志记录配置为包含各种变量，例如接收请求或响应时的日期和时间、请求中的用户身份、发送请求的来源 IP 地址等。边缘以异步方式记录消息，这意味着您的 API 中不会引入可能因阻塞调用而造成的延迟。

MessageLogging 政策将内存中记录好的消息写入缓冲区。消息日志记录器从缓冲区读取消息，然后写入您配置的目标。每个目标都有自己的缓冲区。

如果缓冲区的写入速率高于读取速率，则缓冲区将溢出，日志记录将失败。如果发生这种情况，您可能会在日志文件中看到包含以下内容的消息：

Log message size exceeded. Increase the max message size setting

如果您在适用于 Private Cloud 4.15.07 及更低版本的 Edge 中遇到此问题，请找到 message-logging.properties 文件并使用此解决方案：

在 message-logging.properties 文件中增加 max.log.message.size.in.kb 属性（默认值 = 128 KB）。

对于适用于私有云的 Edge 4.16.01 及更高版本，请在 /opt/apigee/customer/application/message-processor.properties 文件中设置 conf_message-logging_max.log.message.size.in.kb 属性，然后重启消息处理器。

注意：错误流中不提供 Edge 中的响应消息变量。如果前面的流是错误流，则 PostClientFlow 中也不提供这些变量。如果要记录来自 PostClientFlow 的响应信息，请使用 message 对象。无论是否出错，您都可以使用此对象从响应中获取标头和其他信息。如需了解详情并查看示例，请参阅消息变量。

在 Edge 中控制私有云的日志消息时间戳

默认情况下，所有日志消息中的时间戳都采用以下格式：

yyyy-MM-dd'T'HH:mm:ss.SSSZ

可以使用 DateFormat 元素替换 syslog 目标的这一系统级默认值。Java 的 SimpleDateFormat 类文档中介绍了此模板的行为。根据该定义，yyyy 将替换为 4 位数的年份，MM 将替换为 2 位数的月份数字，依此类推。上述格式可能会导致以下形式的字符串：

2022-09-28T22:38:11.721+0000

您可以使用 Edge 消息处理器上的 conf_system_apigee.syslogger.dateFormat 属性来控制该格式。例如，将消息格式更改为：

yy/MM/dd'T'HH:mm:ss.SSSZ

将短划线替换为斜杠并缩短为 2 位数年份，系统将记录以下形式的时间戳：

22/09/28T22:38:11.721+0000

如需更改格式，请执行以下操作：

1. 在编辑器中打开 message-processor.properties 文件。如果该文件不存在，请创建：
   > vi /opt/apigee/customer/application/message-processor.properties
2. 根据需要设置属性：
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. 保存更改。
4. 请确保属性文件归“apigee”用户所有：
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. 重启 Edge Message Processor：
   > /opt/apigee/apigee-service/bin/apigee-serviceedge-message-processor restart

Edge for Private Cloud 中的日志文件位置

Edge for Private Cloud 4.16.01 及更高版本

默认情况下，Private Cloud 消息日志位于消息处理器节点上的以下目录中：

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

您可以通过修改消息处理器上的 message-logging.properties 文件中的属性来更改默认日志位置：

• bin_setenv_data_dir - 设置日志文件存储的根路径。例如 bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir - 如果将其设置为相对路径（例如 conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.）
  
  如果将其设置为绝对路径（例如 conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages），则消息日志将存储在 /opt/apigee/var/log/messages/messagelog/ 中。绝对路径优先于 bin_setenv_data_dir。
  
  请注意，您必须以 conf/message-logging.properties+log.root.dir 的形式引用该属性，因为默认情况下该属性会被注释掉。如需了解详情，请参阅设置当前被注释掉的令牌。

如果要以平面文件结构存储日志文件，以便将所有日志文件放在同一目录中，请在 message-logging.properties 文件中将 conf/message-logging.properties+enable.flat.directory.structure 设置为 true。消息存储在上述属性指定的目录中，且文件名采用 {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename} 格式。

如需设置这些属性，请执行以下操作：

1. 在编辑器中打开 message-processor.properties 文件。如果该文件不存在，请创建：
   > vi /opt/apigee/customer/application/message-processor.properties
2. 根据需要设置属性：
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. 保存更改。
4. 请确保属性文件归“apigee”用户所有：
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. 重启 Edge 组件：
   > /opt/apigee/apigee-service/bin/apigee-serviceedge-message-processor restart

适用于 Private Cloud 4.15.07 及更低版本的 Edge

默认情况下，消息日志位于消息处理器上的以下位置：

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

您可以通过修改消息处理器上 message-logging.properties 文件中的以下属性来更改默认日志位置：

• data.dir - 设置日志文件存储的根路径。例如 data.dir=/opt/apigee4/var/log
• log.root.dir - 如果将此属性设置为相对路径（例如 log.root.dir=custom/folder/），则该路径附加到 data.dir 位置。

例如，这两个属性的组合会将日志记录目录设置为 /opt/apigee4/var/log/custom/folder/messagelog/（请注意，系统会自动添加 /messagelog）。

如果将其设置为绝对路径（例如 log.root.dir=/opt/apigee4/var/log/messages），消息日志将存储在 /opt/apigee4/var/log/messages/messagelog/。log.root.dir 中的绝对路径优先于 data.dir。

如果要以平面文件结构存储日志文件，以便将所有日志文件放在同一目录中，请在消息处理器上的 message-logging.properties 文件中将 enable.flat.directory.structure 属性设置为 true。消息存储在上述属性指定的目录中，且文件名采用 {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}。

消息模板中变量的默认值

可以为消息模板中的每个变量单独指定默认值。例如，如果无法解析变量 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 社区帖子：https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • 另请参阅以下 Apigee 社区帖子： https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • 如需查看使用 Sumo Logic 作为日志记录服务的完整示例，请参阅以下 Apigee 社区帖子。该解决方案使用单个 JavaScript 政策向 Sumo Logic HTTP Source Collector 发出 HTTP POST 请求：https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  使用 Loggly 时，政策中需要将 <FormatMessage>true</FormatMessage> 用作 <Syslog> 元素的子元素。
  如需详细了解 Loggly 的消息日志记录，另请参阅 Apigee 社区帖子：https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

错误参考信息

本部分介绍了在此政策触发错误时返回的错误代码和错误消息，以及 Edge 设置的故障变量。 在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

故障变量

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

错误响应示例

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

相关主题

• Edge 公开的变量：变量参考文档