MessageLogging 政策

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

内容

跟踪 API 运行时环境问题的最佳方法之一是记录消息。您可以在 API 上附加和配置 MessageLogging 政策，以将自定义消息记录到本地磁盘（仅限 Edge for 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 政策类型。

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

<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 地址，等等。Edge 以异步方式记录消息，这意味着，您的 API 没有阻止标注可能会导致的延迟。

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

用户在接收发送到新 syslog 端点的日志消息时可能会遇到延迟。这是由于政策中存在预期的“冷启动”行为。配置新的日志记录目的地后，除了现有日志记录目的地之外，Message Processor (MP) 可能还会先将 1,000 条日志消息加入内存队列，然后再发送这些消息。这可能会导致在低流量环境中出现初始延迟。对于典型的生产工作负载，这种初始延迟是不可察觉的，因为消息应该会快速累积。达到阈值后，日志消息将按预期传送。优雅重启消息处理器还可以触发队列中的消息在从队列中耗尽时进行传送。

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

Log message size exceeded. Increase the max message size setting

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

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

对于 Edge for Private Cloud 4.16.01 及更高版本，请在 /opt/apigee/customer/application/message-processor.properties 文件中设置 conf/message-logging.properties+max. log.message.size.in.kb 属性，然后重启消息处理器。请注意，默认情况下，此属性最初会被注释掉。

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

在 Edge for Private Cloud 中控制日志消息时间戳

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

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

将短划线替换为斜线，并将年份缩写为两位数，以以下格式记录时间戳：

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. 重启边缘消息处理器：
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

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

Edge for Private Cloud 4.16.01 及更高版本

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

/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.
  
  ），则消息日志将存储在 /opt/apigee/var/log/messages/messagelog/ 中。如果您将此值设置为绝对路径（例如 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-service edge-message-processor restart

Edge for Private Cloud 4.15.07 及更低版本

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

/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

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Example fault rule

<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 公开的变量：变量参考文档