Configuration file structure

A configuration file contains a collection of contexts that are to be run by a Hyades Generic Log Adaptor runtime instance. Each context describes how to process a single log file. Because the configuration file is able to contain many of these contexts, the adaptor is capable of processing many log files at the same time.

Each context within the log file is constituted of a series of components. Each component has a role to play in processing a log file.

Context

The context describes the ordered grouping of components as they are chained together for log file processing. Each log file has a separate context, and multiple contexts can be defined in a single configuration. The Generic Log Adaptor provides one context:

org.eclipse.hyades.logging.adaptor.impl.BasicContext - a context which runs each of the components in a single thread.

A context has the following properties:

Property	Type	Behavior
Description	string	A text description for the context. This value is used only by the Log Editor.
Unique Id	string	A unique identifier for this component. The context refers to this string to identify which component instance to use.
Is Continuous Operation	boolean	Whether or not this log file should be monitored for changes based upon the Maximum Idle Time and Pause Interval properties.
Maximum Idle Time	integer (milliseconds)	The maximum amount of time the context will wait for a log file to change before shutting itself down.
Pause Interval	integer (milliseconds)	The amount of time the context waits after reaching the end of the log file before trying to read again.

Sensor

The sensor provides the mechanism to read the content for processing. The Generic Log Adaptor provides the following sensors:

org.eclipse.hyades.logging.adaptor.sensors.SingleOSFileSensor
org.eclipse.hyades.logging.adaptor.sensors.StaticParserSensor . This sensor integrates transforms that are performed by Java based implementations. This sensor is specialized in the fact that it directly invokes that Java parser and exports the common base events that the Java parser produces.
org.eclipse.hyades.logging.adaptor.internal.util.AdaptorSensor. This sensor monitors the adaptor's execution. All internal logging within the adaptor is sent to this sensor.

A sensor has the following properties:

Property	Type	Behavior
Description	string	A text description for the sensor. This value is used only by the Log Editor.
Unique Id	string	A unique identifier for this component. The sensor refers to this string to identify which component instance to use.
Maximum Blocking	integer	The maximum amount of data the sensor reads before forwarding to the extractor for processing. For the SingleOSFileSensor, this is the number of lines.
Convertor	string	This property, which applies to the SingleOSFileSensor only, is a command line for a preprocessing instruction to run before starting the sensor.

Extractor

The extractor takes a collection of input lines provided by the sensor and separates them into message boundaries. The Generic Log Adaptor provides the following extractors:

org.eclipse.hyades.logging.adaptor.extractors.RegularExpressionExtractor . This extractor uses regular expressions to describe the delimitation up of the template file into messages.
org.eclipse.hyades.logging.adaptor.extractors.SimpleExtractor. This extractor uses simple string comparisons to describe the delimitation of the template file into messages. This extractor, a high-performance alternative to the regular expression extractor, should be used with log files that contain unchanging message delimiters.

The following properties are provided as part of the configuration for the extractor:

Property	Type	Behavior
Description	string	A text description for the extractor. This value is used only by the Log Editor.
Unique Id	string	A unique identifier for this component. The extractor refers to this string to identify which component instance to use.
Contains Line Breaks	boolean	Indicates whether the messages in the template file span multiple lines.
Replace Line Breaks	boolean	Replace the line breaks in this file by another string segment. The replacement is made before the extractor searches for Start Pattern or End Pattern.
Line Break Symbol	string	The string segment to replace line breaks with. This is used only if Replace Line Breaks is true.
Include Start Pattern	boolean	Whether to include the StartPattern as part of the message to be forwarded to the next component. If the value is false, the matching portion of the message is stripped.
Start Pattern	string or regular expression	The string segment that identifies the start of a message. You can always use the RegularExpressionExtractor class. However, if your start pattern is a simple string, the SimpleExtractor class incurs less overhead.
Include End Pattern	boolean	Whether to include End Pattern as part of the message to be forwarded to the next component. If the value is false, the matching portion of the message is stripped.
End Pattern	string or regular expression	The string segment that identifies the end of a message. If End Pattern is not specified, then the message is delimited by the next Start Pattern.

Parser

The parser takes the messages that have been delimited by the extractor and builds a set of mappings of string values to the data structure which is being specified within the editor (Common Base Event 1.0.1). The parser has two phases of execution:

The global processing phase, where a set of global regular expressions are executed against the message provided by the extractor.
The attribute processing phase, where specific sets of substitution rules are executed to determine the value to be assigned to each attribute specified in the Log Editor.

The following global properties are specified as part of the parser:

Property	Type	Behavior
Description	string	A text description for the parser. This value is used only by the Log Editor.
Unique Id	string	A unique identifier for this component. The parser refers to this string to identify which component instance to use.
Separator Token	string or regular expression	A token, or a regular expression that describes a series of tokens, that breaks the message up into attribute-value pairs. Assume each new line of your log file contains an attribute and its value. You could specify a Separator Token of `\n`. The advantage of breaking the message up is that the string segments can be referred to in the attribute processing phase.
Designation Token	string or regular expression	A token, or a regular expression that describes a series of tokens, that breaks the string segments created by the Separator Token into attribute-value pairs. For example, if each attribute and value are separated by a `=` sign , and the value of Designation Token is `=` , the attribute and its value can be referred to in the attribute processing phase.

The individual attributes of the common base event have the following properties:

Property	Type	Behavior
Use Previous Match Substitution As Default	boolean	If the current set of Substitution Rules for this attribute returns a positive match, then store the match value so that it can be used as a default to process the next record if there is no positive match.

SubstitutionRules are run as part of the attribute processing phase. They are processed in order from top to bottom. Once a rule is a match, no further rules are run against this property. If no match is found, then no value is placed in the attribute.

SubstitutionRules contain the following properties:

Property Type Behavior

Match regular expression The regular expression that identifies the value to be applied to this attribute if a match occurs in the scope of the string segment being processed by this Substitution Rule. If you do not provide a regular expression, the rule is considered a match.

Positions

name-value attribute pairs

Property	Type	Behavior
Match	regular expression	The regular expression that identifies the value to be applied to this attribute if a match occurs in the scope of the string segment being processed by this Substitution Rule. If you do not provide a regular expression, the rule is considered a match.
Positions	name-value attribute pairs	Positions let you refer to the name-value attribute pairs created during the global processing phase. A Positions string can refer to many attributes by name using the following grammar: `$h('Attr1')@@$h('Attr2')...` `$h('Attrn')` identifies a previously created attribute name. `@@` is the separator between the attributes. In the Match property, you can add the separator to indicate which regular expressions should be applied to which attribute value. The Substitute property can refer to these attribute atoms using `$1`, `$2`, and so on..
Substitute	string	The value to place in the attribute. This can be a string or it can refer to the regular expression in the Match property. The string segments that are extracted by the Match property can be referred to using the groupings in the regular expression. `$1` indicates the first grouping, `$2` the second, and so on.

Positions let you refer to the name-value attribute pairs created during the global processing phase. A Positions string can refer to many attributes by name using the following grammar:

$h('Attr1')@@$h('Attr2')...

$h('Attrn') identifies a previously created attribute name.

@@ is the separator between the attributes.

In the Match property, you can add the separator to indicate which regular expressions should be applied to which attribute value. The Substitute property can refer to these attribute atoms using $1, $2, and so on..

Substitute string The value to place in the attribute. This can be a string or it can refer to the regular expression in the Match property. The string segments that are extracted by the Match property can be referred to using the groupings in the regular expression. $1 indicates the first grouping, $2 the second, and so on.

Configuration file structure

Context

Sensor

Extractor

Parser

Formatter

Outputter