适配器配置文件结构

适配器配置文件包含要由通用日志适配器运行时实例运行的一组上下文集合。每个上下文都描述如何处理单个日志文件。因为适配器配置文件可以包含这些上下文中的许多上下文,所以适配器可以同时处理许多日志文件。

与特定日志文件相关联的每个上下文都是由一系列组件组成的。每个组件在处理日志文件时都充当一个角色。

下图显示了典型的通用日志适配器配置的结构。

此图显示了具有单一上下文和许多组件的适配器

上下文

上下文按照各组件链接在一起以进行日志文件处理的方式描述这些组件的有序分组。每个日志文件都具有独立的上下文,可以在单个配置中定义多个上下文。通用日志适配器提供了两个上下文实现:

上下文具有下列属性:

属性 类型 行为
描述 string 上下文的文本描述。此值仅由适配器配置编辑器使用。
唯一标识 string 此上下文的唯一标识。上下文引用此字符串以标识要使用哪个组件实例。
是连续操作 boolean 是否应根据“最大空闲时间”和“暂停时间间隔”属性监视此日志文件以获取更改。
最大空闲时间 整数(毫秒) 上下文关闭它本身之前将等待日志文件发生更改的最长时间。
暂停时间间隔 整数(毫秒) 上下文到达日志文件末尾之后再次尝试读取之前等待的时间。
ISO 语言代码 生成日志文件时使用的语言环境的语言代码。这些代码是由 ISO-639 定义的小写双字母代码。您可以在许多网站上找到这些代码的完整列表,例如:http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt。如果未指定此值,就会使用执行通用日志适配器时的当前语言环境的语言。当解析日志文件中的时间戳记时,将使用此值。
ISO 国家或地区代码 生成日志文件时使用的语言环境的国家或地区代码。这些代码是由 ISO-3166 定义的大写双字母代码。您可以在许多网站上找到这些代码的完整列表,例如 http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html。如果未指定此值,就会使用执行通用日志适配器时的当前语言环境的国家或地区。当解析日志文件中的时间戳记时,将使用此值。
编码 要解析的日志文件的字符编码。指定的编码值必须是 IANA 字符集注册表(http://www.iana.org/assignments/character-sets)中列示的值,并且必须受执行通用日志适配器的 JVM 支持。如果未指定此值,则将使用执行通用日志适配器的 JVM 的缺省文件编码来解析日志文件,该编码是在 file.encoding JVM 系统属性中指定的。

传感器

传感器提供了读取日志内容以进行处理的机制。通用日志适配器提供了下列传感器:

下表列示了各种传感器类型共有的属性。

传感器属性

属性名称 类型 行为
传感器类型 字符串 适配器要使用的传感器类型。
描述(必需) 字符串 传感器的文本描述。此值仅由适配器配置编辑器使用。
唯一标识(必需) 字符串 此组件的唯一标识。传感器引用此字符串以标识要使用哪个组件实例。
最大分块(必需) Integer 在转发给抽取程序以进行处理之前传感器读取的最大行数。对于 StaticParserSensor 类型,此字段指示在转发给输出程序以进行处理之前由静态解析器创建的公共基本事件对象的最大数目。
置信度缓冲区 Integer 要保存的文件的最后 n 个字节,用于确定自从上次读取文件以来是否有内容追加至该文件。
页脚大小 Integer 文件中包含静态内容的 n 个字节。一些日志文件会将页脚添加至日志文件的末尾。日志文件的这一部分不会被看作日志数据。在确定自从上次读取文件以来是否有内容追加至文件时将不会使用文件的页脚部分。

下表列示了每种类型的传感器的特定属性。下列属性可通过组件代码了解并且必须完全按照表中指示的那样进行拼写以便组件可以识别并使用它们。

传感器类型 属性 Application
SingleFileSensor
目录(directory,必需)
SinlgeFileSensor 要读取的文件的目录位置。
文件名(fileName,必需)
SingleFileSensor 将要读取的文件的名称。如果应用程序使用日志文件循环使用功能,则可以使用正则表达式来指定文件名。
注意:在解释 fileName 字段时,将考虑大小写。如果要让该字段不区分大小写,请使用正则表达式来指定文件名。
shell
要运行转换器命令的 UNIX shell。仅在 UNIX 平台上使用
converter
用于在启动传感器之前预处理要运行的指令的命令行。
在创建适配器以使用正则表达式规则解析日志文件时使用
StaticParserSensor
目录(directory,必需)
StaticParserSensor 要读取的文件的目录位置。
文件名(fileName,必需)
StaticParserSensor 要读取的文件的名称。
解析器类名(parserClassName,必需)
实现静态解析器的 Java 类的名称。该类必需实现 org.eclipse.hyades.logging.parsers.IParser 接口。
在创建适配器以使用静态解析器 Java 类解析日志文件时使用。

抽取程序

抽取程序采用传感器所提供的一组输入行并将它们分为消息边界。

通用日志适配器提供了下列抽取程序:

下列属性是作为抽取程序的部分配置提供的:

属性 类型 行为
描述 string 抽取程序的文本描述。此值仅由适配器配置编辑器使用。
唯一标识 string 此组件的唯一标识。抽取程序引用此字符串以标识要使用哪个组件实例。
包含换行符 boolean 指示日志文件中的消息是否跨越多行。
替换换行符 boolean 使用另一个字符串段替换此文件中的换行符。替换在抽取程序搜索“开始模式”或“结束模式”之前进行。
注意:使用此选项的副作用是,除非解析器替换规则显式地添加换行符,否则从日志文件中解析的值将不包含换行符。
换行符号 string 要替换换行符的字符串段。仅当“替换换行符”为 true 时使用。
包括开始模式 boolean 是否包括 StartPattern 作为要转发给下一个组件的消息的一部分。如果值为 false,则将舍去消息的匹配部分。
开始模式 字符串或正则表达式 标识消息开始的字符串段。可以始终使用 RegularExpressionExtractor 类。但是,如果开始模式为简单字符串,则 SimpleExtractor 类会产生较少的开销。
包括结束模式 boolean 是否包括“结束模式”作为要转发给下一个组件的消息的一部分。如果值为 false,则将舍去消息的匹配部分。
结束模式 字符串或正则表达式 标识消息结束的字符串段。如果未指定“结束模式”,则将由下一个“开始模式”定界消息。

解析器

解析器接收抽取程序已定界的消息并构建一组字符串值至数据结构的映射。对于通用日志适配器,数据结构为“公共基本事件 1.0.1”

通用日志适配器提供了下列解析器类

解析器有两个执行阶段:

  1. 全局处理阶段,在此阶段针对抽取程序提供的消息执行一组全局正则表达式。
  2. 属性处理阶段,在此阶段执行特定替换规则组以确定要指定给数据结构(公共基本事件 1.0.1)中的每个属性的值。

两个执行阶段都允许在全局处理阶段将消息标记为一系列属性值。然后,可以在属性处理阶段通过属性名称或下标引用属性值。

指定了下列全局属性作为解析器的一部分:

属性 类型 行为
描述 string 解析器的文本描述。此值仅由适配器配置编辑器使用。
唯一标识 string 此组件的唯一标识。解析器引用此字符串以标识要使用哪个组件实例。
分隔符标记 字符串或正则表达式 将消息分为属性值对的标记或描述一系列标记的正则表达式。

例如,如果日志文件的每个新行都包含一个属性及其值,则可以指定“分隔符标记”\n。将消息分成属性值对的好处是可以在属性处理阶段引用字符串段。
注意:如果未指定分隔符标记,则不会执行任何全局处理。

指示标记 字符串或正则表达式 将“分隔符标记”创建的字符串段分为属性值对的标记或描述一系列标记的正则表达式。例如,如果用 = 符号分隔每个属性和值并且“指示标记”的值为 =,则可以在属性处理阶段引用属性及其值。如果指定了分隔符标记但是未指定指示标记,则消息会分为一系列属性值,可以在替换规则中通过下标引用这些值。

公共基本事件的各个属性具有下列属性:

注意:在全局处理阶段解析的值将被修剪掉前导和尾部空格字符。因此,可以编写使用位置值并假定值没有前导和尾部空格字符的替换规则。

属性 类型 行为
使用上一匹配替换作为缺省值 boolean 如果此属性的当前替换规则集返回正匹配,则存储匹配值以便在没有正匹配的情况下将它用作处理下一条记录的缺省值。
缺省值 字符串 如果此属性的任何替换规则都不提供正匹配或者此属性没有替换规则,则将对此属性指定此处指定的缺省值。如果特定属性的所有记录需要相同的值,则可以使用此属性而不需要为该属性创建缺省替换规则。注意,如果有已保存的值可用,则使用上一匹配替换作为缺省值将优先。
父代所需的 boolean 允许您指定此元素是否必须具有有效值才能使父元素有效。例如,如果为 situation 元素选择了此选项,就会通知解析器:公共基本事件对象必须有有效的 situation 元素。在处理期间,如果 situation 元素返回空值,解析器就不处理该公共基本事件对象的任何其它子元素,这是因为它已知道这个公共基本事件对象是无效的,原因是必需的子元素返回了无效的值。
子代选项 boolean 允许您指定:当有效子属性或元素返回了有效值时,此元素的处理是否应该停止。例如,假定 situation 有三个子元素 ReportSituationRequestSituationStartSituation,这三个子元素都有自己的子树。如果对 situation 元素选择了子代选项选项,则此元素的解析将在它的第一个子代子树返回有效值时停止。

将替换规则作为属性处理阶段的一部分运行。以从上到下的顺序处理它们。一旦某个规则是一个匹配,就不会针对此属性运行其它规则。如果找不到匹配,则除非指定了属性的使用上一匹配替换作为缺省值缺省值属性,否则不会将值放置在属性中。

替换规则包含下列属性:

属性 类型 行为
匹配 正则表达式 标识如果在由此“替换规则”处理的字符串段范围内出现匹配时要应用于此属性的值的正则表达式。如果不提供正则表达式,则认为规则是匹配。
位置 名值属性对 “位置”允许您引用在全局处理阶段创建的名值属性对。
  • 如果同时指定了分隔符标记和指示标记,则位置字符串可以使用下列语法通过名称引用许多属性:$h('Attr1')@@$h('Attr2')...
    $h('Attrn') 标识先前创建的属性名称。
    其中 @@ 是属性之间的分隔符。
  • 如果指定了分隔符标记但未指定指示标记,则“位置”字符串可以使用下列语法通过下标而不是名称引用一个或多个属性:n1@@n2..
    其中 n1 和 n2 是表示下标的整数。下标从 1 开始。如果消息字符串以分隔符标记开始,则下标为 1 处的属性值将为空。第一个属性值将从下标 2 开始。

在“匹配”属性中,可以添加分隔符以指示要对哪个属性值应用哪些正则表达式。

替换 string 要放置在属性中的值。这可以是字符串或者它可以引用“匹配”属性中的正则表达式。可以通过使用正则表达式中的分组引用“匹配”属性抽取的字符串段。$1 指示第一个分组,$2 指示第二个分组,依此类推。
使用内置函数 复选框 当对属性选择了此项时,在没有任何先前替换规则或者如果存在先前替换规则但它们匹配时,使用内置函数将导致通用日志适配器运行时通过使用它自己的内部函数为该属性生成一个值。只有下列 CBE 属性支持此功能:
  • localInstanceId
  • globalInstanceId
  • componentIdentification.location
  • componentIdentification.locationType
替换类 string 指定创建 Java 类的用户的名称,该类可以对通过规则的位置匹配替换规范匹配的值执行定制解析逻辑。如果替换规则与记录中的数据匹配,则将调用此类并且结果将用来创建公共基本事件对象。
规范:
  • 此类必须实现接口类 org.eclipse.hyades.logging.adapter.parsers.ISubstitutionExtension 或扩展类 org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension,从而使通用日志适配器能够执行它。
  • 当想要将状态数据保存在日志文件记录之间时使用扩展类。类 org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension 导致通用日志适配器仅分配此类的一个实例以解析日志文件的所有记录。
  • 必须将用户类包括在通用日志适配器运行时的类路径中。
  • 如果通用日志适配器要在 Eclipse 环境中运行,则可以通过使用 org.eclipse.hyades.logging.adapter 插件的 substitutionExtension 扩展点来将该类创建为通用日志适配器的 eclipse 插件扩展。
时间格式 string 此字段仅适用于 creationTime 元素的替换规则并用来简化日期时间解析。例如,某些日志文件包含包括月份的名称而不是月份的数字表示的时间戳记。这使得难以创建替换规则以生成 CBE creationTime 元素所需的“XML 模式日期时间”数据类型格式的字符串值。在这种情况下,用户可以在“时间格式”字段中指定 java 简单日期格式字符串,如在 java.text.SimpleDateFormat 的 javadoc(java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html)中所述。将根据“时间格式”字符串解析通过规则的“位置”、“匹配”和“替换”规范匹配的值并且获得的值将用来生成 CBE creationTime 值。
注意:在解析含有时间格式字符串的时间戳记时,将使用由上下文实例配置中指定的 ISO 语言和国家或地区代码值表示的语言环境。

格式化程序

格式化程序接收属性至解析器提供的这些属性的值的映射并构建正确的 Java 对象实例。适配器运行时包含创建符合公共基本事件 v1.0.1 规范的公共基本事件对象的单个格式化程序。

格式化程序包含下列属性:

属性 类型 行为
唯一标识 string 此组件的唯一标识。格式化程序引用此字符串以标识要使用哪个组件实例。
描述 string 格式化程序的文本描述。此值仅由适配器配置编辑器使用。

输出程序

输出程序外部化格式化程序提供的最终得到的公共基本事件记录。输出程序提供或合并用于存储上下文的最终输出的机制。通用日志适配器提供了下列输出程序:

输出程序的属性:

属性 类型 行为
唯一标识 string 此组件的唯一标识。输出程序引用此字符串以标识要使用哪个组件实例。
描述 string 输出程序的文本描述。此值仅由适配器配置编辑器使用。
输出程序类型 枚举 这是输出程序的类型。

输出程序类型和必需的属性:

输出程序类型 必需的属性
StandardOutOutputter
SingleFileOutputter 目录,文件名
LoggingAgentOutputter 代理程序名 - 创建记录代理程序时为其提供的名称
等待记录时间(waitUntilLoggingTime,可选) - 输出程序在开始写入代理程序之前等待用户连接该代理程序并开始监视它的时间。如果未指定此属性,则输出程序在写入代理程序之前将不会等待监视代理程序。

 

相关概念
Hyades 通用日志适配器概述
公共基本事件格式规范

相关任务
创建日志解析器
创建基于规则的适配器
创建静态适配器

相关参考
适配器配置文件结构
公共基本事件格式规范
适配器配置编辑器
正则表达式语法