MessageLogging 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

跟踪 API 运行时环境问题的最佳方法之一是记录消息。您可以在 API 上附加和配置 MessageLogging 政策，以便将自定义消息记录到 本地磁盘（仅适用于私有云的 Edge）或导出到 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 地址，依此类推。Edge 日志消息 异步呈现，这意味着不会引入因屏蔽出价邀约而造成的延迟 。

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

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

Log message size exceeded. Increase the max message size setting

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

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

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

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

控制日志消息 Edge 中的时间戳（适用于私有云）

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

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

可以使用 DateFormat 元素。有关此模板的行为，请参见 Java 的 SimpleDateFormat 类文档。根据该定义，yyyy 将被替换为 的年份为 4 位数，MM 将替换为 2 位数的月份数，依此类推。 上述格式可能会导致生成以下形式的字符串：

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

您可以使用 conf_system_apigee.syslogger.dateFormat 属性来控制该格式。例如，将消息 格式设置为：

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

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

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

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

1. 打开 message-processor.properties 文件 编辑器。如果该文件不存在，请创建：
   &gt;六 /opt/apigee/customer/application/message-processor.properties
2. 根据需要设置属性：
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd&#39;T&#39;HH:mm:ss.SSSZ
3. 保存更改。
4. 确保属性文件归“apigee”所有用户：
   &gt; chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. 重启边缘消息处理器：
   &gt; /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge 中私有云的日志文件位置

适用于私有云 4.16.01 及更高版本的 Edge

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

/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，因为 系统会将其注释掉请参阅将 标记了解详情。

如果您想以平面文件结构存储日志文件，以便将所有日志文件 请将 conf/message-logging.properties+enable.flat.directory.structure 设置为 true。邮件存储在 上述属性，文件名采用 {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}。

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

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

适用于私有云 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。

如果您想以平面文件结构存储日志文件，以便将所有日志文件 请将 enable.flat.directory.structure 属性设置为 在 Message 的 message-logging.properties 文件中为 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 公开的变量：变量参考