MessageLogging 政策

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

内容

跟踪 API 运行时环境问题的最佳方法之一是记录消息。您可以在 API 上附加和配置 MessageLogging 政策,以便将自定义消息记录到 本地磁盘(仅适用于私有云的 Edge)或导出到 syslog。

<ph type="x-smartling-placeholder">

示例

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 政策类型的常见用途是记录至 syslog 账号。时间 syslog,API 代理会将日志消息从 Apigee Edge 转发到远程 Syslog 服务器。您必须已经拥有一个 syslog 服务器。如果没有,则也可以使用 Splunk、Sumo Logic 和 Loggly 等公共日志管理服务。请参阅配置第三方日志管理服务

例如,假设您需要记录 API 从使用方应用收到的每个请求消息的相关信息。值 3f509b58 表示特定于 Loggly 服务的键值对。如果您有 Loggly 账号,请使用您的 Loggly 密钥。生成的日志消息将填充四个值:与事务关联的组织、API 代理和环境名称,以及请求消息中查询参数的值。

如果您有用于私有云部署的 Edge,则还可以将日志消息写入 文件。

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

您可以通过添加 <SSLInfo> 块,通过 TLS/SSL 向第三方消息日志记录提供商发送消息。

文件轮替:大小

<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 政策类型。

字段名称 字段说明

File

本地文件目标位置。(只有 Edge for Private Cloud 才支持文件日志记录) deployments.)有关文件的存储位置的信息,请参阅日志文件 位置

Message 构建要发送到日志文件的消息, 和变量来捕获所需信息。请参阅示例
FileName 记录消息的日志文件的名称。
FileRotationOptions
rotateFileOnStartup

属性。有效值:true/false

如果设置为 true,则每次消息传递引擎都会轮播日志文件 重启。

FileRotationType 指定轮替政策(sizetime)。
MaxFileSizeInMB (选择“size”作为轮播类型时) 指定触发服务器将日志消息移动到 一个单独的文件。当日志文件达到指定的大小后,服务器会重命名该 当前日志文件中。
RotationFrequency (选择“time”作为轮播类型时) 指定触发服务器将日志消息移至单独的 文件。超过指定的时间间隔后,将重命名当前日志文件。
MaxFilesToRetain

指定在轮替环境中可保留的文件数量上限 设置。默认值为 8

如果您指定零 (0),日志文件会无限期保留,但受文件限制 但系统不会删除或重命名任何文件。因此,为了避免 可设置为大于零的值,也可以实施常规 用于清除或归档较旧的已保留日志文件的自动化系统。

BufferMessage

如果 HTTP 流式传输 启用,则请求/响应消息不会进行缓冲。如果您想 需要解析流消息的日志内容,然后将 BufferMessage 设置为 true。 请参阅“已启用信息流”“示例”标签页中查看示例。默认值:false

Syslog

Syslog 目标。要将 Syslog 发送到 Splunk、Sumo Logic 或 Loggly, 请参阅配置第三方日志管理服务

Message

构建将发送至 syslog 的消息,其中将文字与变量相结合,以捕获您想要的信息。查看示例

注意:在完成错误流后,PostClientFlow 中将不提供响应变量。针对错误和成功情况,使用消息变量记录响应信息。另请参阅使用说明

Host 应将 syslog 发送到的服务器的主机名或 IP 地址。如果您不添加此元素,则默认为 localhost。
Port syslog 运行的端口。如果您未添加此元素,则默认为 514。
Protocol TCP 或 UDP(默认)。虽然 UDP 的性能更高,但 TCP 协议可保证将消息日志传送至 syslog 服务器。对于通过 TLS/SSL 发送 syslog 消息,系统仅支持 TCP。
FormatMessage

truefalse(默认)

可选,但 Loggly 需要使用 <FormatMessage>true</FormatMessage>

借助此元素,您可控制附加到消息的 Apigee 所生成内容的格式。如果设置为 true,则 syslog 消息将附加固定数量的字符,让您可过滤掉消息中的信息。以下是固定格式的示例:

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee-Edge - - - Message starts here

Apigee 生成的信息包括:

  • <14> - 基于消息的日志级别和设施级别的优先级分数(请参阅 Syslog 协议)。
  • 1 - 当前 syslog 版本。
  • 带世界协调时间 (UTC) 偏移量的日期 (UTC = +0000)。
  • 消息处理器 UUID。
  • “Apigee-Edge - - -”

如果设置为 false(默认),则消息不会附加这些固定字符。

PayloadOnly

truefalse(默认)

此元素会设置 Apigee 生成的消息的格式,使其仅包含 syslog 消息的正文,不带 FormatMessage 指定的附加字符。

如果您不添加此元素或将其留空,则默认值为 false

请参阅 FormatMessage

DateFormat

可选。

用于设置每个日志消息的时间戳格式的格式模板字符串。 默认情况下,Apigee 使用 yyyy-MM-dd'T'HH:mm:ss.SSSZ。行为 具体说明请参阅 Java 的 SimpleDateFormat 类

SSLInfo

允许您通过 SSL/TLS 记录消息。与子元素 <Enabled>true</Enabled> 搭配使用。

如果您不添加此元素或将其留空,则默认值为 false(无 TLS/SSL)。

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

您可以配置 <SSLInfo> 标记,方式与在 TargetEndpoint 上相同,包括启用双向 TLS/SSL,如 API 代理配置参考文档中所述。系统仅支持 TCP 协议。

logLevel

可选。

有效值:INFO(默认)、ALERTWARNERROR

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

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

架构


使用说明

在将 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 元素。

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

错误参考信息

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

运行时错误

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

故障代码 HTTP 状态 原因
steps.messagelogging.StepDefinitionExecutionFailed 500 请参阅故障字符串。

部署错误

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

错误名称 原因 修复
InvalidProtocol 如果在 <Protocol> 元素中指定的协议无效,则 MessageLogging 政策的部署可能会失败,并出现此错误。有效协议为 TCP 和 UDP。对于通过 TLS/SSL 发送 syslog 消息,系统仅支持 TCP。
InvalidPort 如果未在 <Port> 元素中指定端口号或者此端口无效,则 MessageLogging 政策的部署可能会失败,并出现此错误。端口号必须是大于零的整数。

故障变量

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

变量 地点 示例
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.failed
  • messagelogging.{stepdefinition-name}.failed

相关主题