State Tracker Plug-In - Technical Reference

Plug-in configuration

The following parameters can be configured for this plug-in:

columns

This is used to configure optional column headings for the sampler. The columns setting on a tracker group takes precedence over this setting.

If you have one or more trackers collecting the same type of information it can be useful to change the default names for the captured event parameters.

Mandatory: No

columns > renameTrackerColumn

Setting this option renames the first column of the dataview to the name you define here. By default the column is named "tracker" as it contains the name of the state tracker.

This can be useful if you have a view of dynamic trackers all tracking the same kind of thing. If you are tracking line statuses for example and your tracker uniquely identifies the line then you may wish to rename the column "line".

Note: The corresponding setting on a tracker group takes precedence over this setting.

Mandatory: No

columns > column

A column name to replace the default one. Column names replace the default names parameter1...parametern in the order in which they are defined.

Note: The corresponding setting on a tracker group takes precedence over this setting.

Mandatory: No

performance

Optional settings for high volume environments. The performance settings on a tracker group takes precedence over these settings.

Mandatory: No

performance > skipMidSampleUpdates

By default all state changes are reported to the gateway as they are detected. That way for example if a tracker changes state three times the view will update three times so that rules can act upon the change.

Under certain circumstances intermediate state changes may not be of interest with just the final result being of interest. Turning on this setting will reduce network traffic and speed up processing. However important updates may be missed.

Note: The corresponding setting on a tracker group takes precedence over this setting.

Mandatory: No

performance > maxMessagesPerSample

With a very large number of trackers it is possible that the sample cannot be completed within the allotted timeframe. This setting sets a maximum number of messages that the sampler can process in a given sample.

Mandatory: No

performance > minimumReservedRowspace

With a very large number of trackers it is possible to improve the time table to publish the dataview if we have an idea up front how many rows the dataview is likely to contain.

This setting is useful for dataviews with several thousand rows and should be set to the number of expected rows or greater.

Note: The corresponding setting on a tracker group takes precedence over this setting.

Mandatory: No

templateOptions

A place to configure global template options for dynamic trackers.

Mandatory: No

templateOptions > hideTrackerIDs

When using dynamic trackers the ID is reported as the name of the tracker in the first column of the dataview. As the ID is also a capturing group of the regular expression it is also reported on the row as an event parameter.

To suppress this, set this parameter to true and tracker IDs will not be reported in the dataview.

Mandatory: No
Default: false

behavioural

These are settings that affect general behaviour of the sampler.

behavioural > fileTruncateResetsTrackers

When a file reduces in size because the data has been truncated (some scenarios truncate the file at end of day) the usual behaviour is to remember the current states and continue tracking from there.

Note: When a file is truncated and we then lose read access to it the trackers are reset if this setting is enabled, e.g., the Netprobe user no longer has read permissions to a file that has been rolled over.

Enabling this option will force all trackers associated with the file to reset to their default state. All dynamically created trackers are removed.

Mandatory: No
Default: false

trackerGroup

This is a grouping of related trackers to be displayed in the same dataview.

Mandatory: No

trackerGroup > name

The name of the group of trackers. This should be unique among tracker groups and will be used to name the view in which the trackers are displayed.

Mandatory: Yes

trackerGroup > columns

This is used to configure optional column headings for the sampler. The columns setting on a tracker group takes precedence over the global setting.

If you have one or more trackers collecting the same type of information it can be useful to change the default names for the captured event parameters.

Mandatory: No

trackerGroup > columns > renameTrackerColumn

Setting this option renames the first column of the dataview to the name you define here. By default the column is named "tracker" as it contains the name of the state tracker.

This can be useful if you have a view of dynamic trackers all tracking the same kind of thing. If you are tracking line statuses for example and your tracker uniquely identifies the line then you may wish to rename the column "line".

Note: This takes precedence over the global setting.

Mandatory: No

trackerGroup > columns > column

A column name to replace the default one. Column names replace the default names parameter1...parametern in the order in which they are defined.

Note: This takes precedence over the global setting.

Mandatory: No

trackerGroup > performance

Optional settings for high volume environments. The performance settings on a tracker group takes precedence over the global settings.

Mandatory: No

trackerGroup > performance > skipMidSampleUpdates

By default all state changes are reported to the gateway as they are detected. That way for example if a tracker changes state three times the view will update three times so that rules can act upon the change.

Under certain circumstances intermediate state changes may not be of interest with just the final result being of interest. Turning on this setting will reduce network traffic and speed up processing. However important updates may be missed.

Note: This takes precedence over the global setting

Mandatory: No

trackerGroup > performance > minimumReservedRowspace

With a very large number of trackers it is possible to improve the time table to publish the dataview if we have an idea up front how many rows the dataview is likely to contain.

This setting is useful for dataviews with several thousand rows and should be set to the number of expected rows or greater.

Note: This takes precedence over the global setting.

Mandatory: No

trackerGroup > trackers

The set of trackers which are members of the group

Mandatory: Yes

trackerGroup > trackers > tracker

A tracker monitors a file for events signifying a logical state change.

One or more trackers may be defined to track / monitor different events. It is possible to have more than one tracker per file.

Mandatory: Yes

trackerGroup > trackers > tracker > name

A unique name used to identity the tracker.

Mandatory: Yes

trackerGroup > trackers > tracker > filename

A path specifying the file to be monitored. The filename may contain wildcards and standard Geneos <today> dates-stamping within filenames.

Mandatory: No
Default: a filename or stream must be configured

trackerGroup > trackers > tracker > stream

The name of the Geneos stream which this tracker will subscribe to. A stream can optionally be configured instead of a log file to customise data input.

Mandatory: No

Default: a filename or stream must be configured

Wildcard expressions

This configuration supports wildcard expressions for streams coming from other plugins. Supported wildcard characters are * and ?.

A stream matched by a wildcarded tracker will appear in the dataview as a new row with the following name format:

<stream name>.<tracker name>

You can use wildcarded trackers alongside non-wildcarded trackers. The function of non-wildcarded trackers remain independent of the wildcarded trackers.

Dynamic trackers

If a tracker template is enabled, then a stream matched by a wildcarded tracker will appear in the dataview as a new row with the following name format:

<stream name>.<tracker name>.<id>

For more information, see Dynamic Tracking with Templates in State Tracker Plug-In - User Guide.

Precedence for wildcarded trackers

Multiple wild-carded trackers can track the same streams within the same tracker group.

Between tracker groups with wildcarded trackers, a stream matching a wildcard expression will fall under the first tracker group whose wildcarded trackers match the stream, and will not appear in other tracker group dataviews. The tracker groups follow a top-down order in the GSE.

State Tracker in Dynamic Entities

State Tracker samplers running under Dynamic Entities follow these behaviours:

  • Unmatched stream names without wildcard expressions do not show up in the dataview.
  • You can only monitor streams created within the same Dynamic Entity.
  • The Managed entity is implied, and you do not need to specify it in the stream pattern. For example, the pattern TG1.log can match a stream and result in the stream <me>.TG1.log in the dataview.

For more information, see Dynamic Entities.

trackerGroup > trackers > tracker > rewind

If the Rewind flag is set, the Tracker will monitor the file from the beginning. The default behaviour is to monitor the file as it grows for new events.

If using a Geneos stream for input, this flag is ignored.

Mandatory: Yes
Default: false

trackerGroup > trackers > tracker > filters

Filters are a means of filtering out messages before they are processed.

Mandatory: No

trackerGroup > trackers> tracker > filters > filter

The filter is a regular expression that if matched will stop the message from being processed. For example if the log contains a number of debug messages indicated by DEBUG at the start of the line a filter can simply contain:

^DEBUG

This will filter out all messages beginning with DEBUG before processing.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Mandatory: Yes

trackerGroup > trackers > tracker > messageTimestamp

It is usual for a log file to contain a timestamp. If one exists this provides a place to identify and interpret the timestamp within a message.

Mandatory: No

trackerGroup > trackers > tracker > messageTimestamp > identifyingPattern

This is a regular expression that identifies a timestamp within a message. For example timestamp in of the form:

[2008-12-25-06-00-00] Rest of message here…

Could be picked out with the regular expression:

^\[(\d+-\d+-\d+-\d+-\d+-\d+)\]

This is enough to identify the date within the square brackets at the start of the message.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Mandatory: Yes

trackerGroup > trackers > tracker > messageTimestamp > datePatternGroup

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Using the identifying pattern example again:

^\[(\d+-\d+-\d+-\d+-\d+-\d+)]

This regular expression has a capturing subgroup to identify the date within the brackets. So here the datePatternGroup is 1. The default is to use the complete match which would still work in this instance.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Mandatory: Yes
Default: 0

trackerGroup > trackers > tracker > messageTimestamp > dateFormat

This defines the format of the timestamp that has been extracted from the message. The Date codes used define how the adapter processes the timestamp.

To interpret the date from "11:32:22.983 2008-11-21" a format of "%H:%M:%S%f %Y-%m-%d" should be used.

Specifier Replaced by
%a Abbreviated weekday name (i.e. Thu)
%A Full weekday name (i.e. Thursday).
%b Abbreviated month name (i.e. Aug)
%B Full month name (i.e. August)
%c Date and time representation (local dependant)
%d Day of the month (01-31)
%f Milliseconds. (Reads between 0 and 3 digits). The period is part of this code, to read seconds and milliseconds use %S%f. If you do not want the period included in the code please use %Of which reads just the digits.
%g Supports and read micro-second resolution timestamps.
%H Hour in 24h format (00-23)
%I Hour in 12h format (01-12)
%j Day of the year (001-366)
%m Month as a decimal number (01-12)
%M Minute (00-59)
%p AM or PM designation
%S Second (00-61)
%U Week number with the first Sunday as the first day of week one (00-53)
%w Weekday as a decimal number with Sunday as 0 (0-6)
%W Week number with the first Monday as the first day of week one (00-53)
%x Date representation (local dependant)
%X Time representation (local dependant)
%y Year, last two digits (00-99)
%Y Year, last all digits (i.e. 2008)
%Z Timezone name or abbreviation (i.e. CDT)
%% A % sign

On Unix systems some conversion specifications can be modified by preceding the conversion specifier character by the E or O modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behaviour will be as if the unmodified conversion specification were used. (SU) The Single Unix Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use alternative numeric symbols (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation.

Using the identifying pattern example again:

^\[(\d+-\d+-\d+-\d+-\d+-\d+)]

and this time format:

%Y-%m-%d-%H-%M-%S

It is possible to interpret the timestamp on the message.

Mandatory: Yes

trackerGroup > trackers > tracker > template

If true marks the tracker as a template. When a key is matched a tracker will be created based on this template. The tracker will need to be able to extract an id from the key.

Mandatory: No
Default: false

trackerGroup > trackers > tracker > transitionStates

The logical states for a tracker are defined here.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState

The initial state for the tracker.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > name

A name for the state.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > keys

A collection of regular expressions that would trigger change to this state.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > keys > key

A regular expression that if matched indicates a state change to this state.

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Where a capturing subgroup is found it is considered a parameter of the event that triggered the change and will be extracted for the view.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Note: Keys that are part of a template (see tracker > template) must have a named capturing group called "id" (or a series of groups "id1", "id2", … "idN") within the pattern.

The syntax for this is:

(?<id>…)

The name is case sensitive and if your pattern does not contain this an error will be logged and the key ignored.

This is necessary to mark the text that will uniquely identify the item being tracked.

If your pattern contains "id1", it can also contain "id2", "id3", and so on; as long as there are no gaps in the sequence, all such groups will be used to identify the tracked item.

See Dynamic Tracking with Templates for more details.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > DefaultState > keys > key > templateOptions > keyAppliestoAllTemplateInstances

If true the key is processed by all existing instances of the template. The key does not need to contain an ID if this is set.

This can be used to where a single messages indicates completeness for a number of processes for example.

Mandatory: No
Default: false

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout

A state may optionally timeout at a given time or after a period of time; this is configured by adding a timeout to the state.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout > relative

Defines a relative timeout. i.e. 10 minutes or 1 hour.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout > relative > interval

A number specifying the length of the relative timeout.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout > relative > units

This gives context to the interval.

Possible values:

Setting Description
seconds The interval is for a number of seconds
minutes The interval is for a number of minutes
hours The interval is for a number of hours

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout > absolute

The state times out at an absolute time specified using the 24 hour clock in the format HH:MM[:SS] (the brackets indicate that seconds are optional.) If the state is re-entered after that time, it times out immediately.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout > atTimeOfDay

The state times out at a specified time of day specified using the 24 hour clock in the format HH:MM[:SS] (the brackets indicate that seconds are optional.) If the state is entered after the specified time, it will not time out until the same time occurs the following day.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout > state

This is a reference to an existing defined state. When a timeout occurs the tracker will change to this state.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > timeout > inlineState

The state to change to on timeout can also be defined inline rather than referencing an existing state.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > defaultState > templateOptions

These options apply only to templates.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > templateOptions > removeTracker

This option removes the tracker when this state is entered. This only applies to trackers created via templates.

Mandatory: No
Default: false

trackerGroup > trackers > tracker > transitionStates > defaultState > allowTransitionToStates

This setting allows transitions to only to the set of states following. If no states are defined then transitions are allowed to any state with a matching event.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > allowTransitionToStates > states > state

A reference to a state defined within the tracker. Transitions are allowed to this state.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > allowTransitionToStates > states > inlineState

This is an inline state definition for a state that you can transition to from this state. This state is one of the allowed transitions.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > allowTransitionToStates > onException > state

A reference to a state defined within the tracker. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > defaultState > allowTransitionToStates > onException > inlineState

This is an inline state definition for a state that you can transition to from this state. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state

Defines an individual logical state for a tracker.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > name

A name for the state.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > keys

A collection of regular expressions that would trigger change to this state.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > keys > key

A regular expression that if matched indicates a state change to this state.

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Where a capturing subgroup is found it is consider a parameter of the event that triggered the change and will be extracted for the view.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Note: Keys that are part of a template (see tracker template must have a named capturing group called "id" (or a series of groups "id1", "id2", … "idN") within the pattern.

The syntax for this is:

(?<id>…)

The name is case sensitive and if your pattern does not contain this an error will be logged and the key ignored.

This is necessary to mark the text that will uniquely identify the item being tracked.

If your pattern contains "id1", it can also contain "id2", "id3", and so on; as long as there are no gaps in the sequence, all such groups will be used to identify the tracked item.

See Dynamic Tracking with Templates for more details.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > keys > key > templateOptions

This contains options applicable to templates associated with the key.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > keys > key > templateOptions > keyAppliestoAllTemplateInstances

If true the key is processed by all existing instances of the template. The key does not need to contain an ID if this is set.

This can be used to where a single messages indicates completeness for a number of processes for example.

Mandatory: No
Default: false

trackerGroup > trackers > tracker > transitionStates > state > timeout

A state may optionally timeout at a given time or after a period of time. Timeout's make it possible to trigger a state change based on this.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > timeout > relative

Defines a relative timeout. i.e. 10 minutes or 1 hour.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > timeout > relative > interval

A number specifying the length of the relative timeout.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > timeout > relative > units

This gives context to the interval.

Possible values:

Setting Description
seconds The interval is for a number of seconds
minutes The interval is for a number of minutes
hours The interval is for a number of hours

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > timeout > absolute

The state times out at an absolute time specified using the 24 hour clock in the format HH:MM[:SS] (the brackets indicate that seconds are optional.) If the state is re-entered after that time, it times out immediately.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > timeout > atTimeOfDay

The state times out at an absolute time specified using the 24 hour clock in the format HH:MM[:SS] (the brackets indicate that seconds are optional.) If the state is entered after the specified time, it will not time out until the same time occurs the following day.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > timeout > state

This is a reference to an existing defined state. When a timeout occurs the tracker will change to this state.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > timeout > inlineState

The state to change to on timeout can also be defined inline rather than referencing an existing state.

Mandatory: Yes

trackerGroup > trackers > tracker > transitionStates > state > templateOptions

These options apply only to templates.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > templateOptions > removeTracker

This option removes the tracker when this state is entered. This only applies to trackers created via templates.

Mandatory: No
Default: false

trackerGroup > trackers > tracker > transitionStates > state > allowTransitionToStates

This setting allows transitions to only to the set of states following. If no states are defined then transitions are allowed to any state with a matching event.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > allowTransitionToStates > states > state

A reference to a state defined within the tracker. Transitions are allowed to this state.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > allowTransitionToStates > states > inlineState

This is an inline state definition for a state that you can transition to from this state. This state is one of the allowed transitions.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > allowTransitionToStates > onException > state

A reference to a state defined within the tracker. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

trackerGroup > trackers > tracker > transitionStates > state > allowTransitionToStates > onException > inlineState

This is an inline state definition for a state that you can transition to from this state. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

trackerGroup > trackers > tracker > states

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

The logical states for a tracker are defined here.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

The initial state for the tracker.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > name

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A name for the state.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > keys

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A collection of regular expressions that would trigger change to this state.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > keys > key

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A regular expression that if matched indicates a state change to this state.

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Where a capturing subgroup is found it is considered a parameter of the event that triggered the change and will be extracted for the view.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Note: Keys that are part of a template (see tracker template have a named capturing group called "id" within the pattern. Multiple named capture groups (<id1>, <id2>, etc) are not supported for trackers defined using deprecated syntax.

The syntax for this is:

(?<id>…)

The name is case sensitive and if your pattern does not contain this an error will be logged and the key ignored.

This is necessary to mark the text that will uniquely identify the item being tracked.

See Dynamic Tracking with Templates for more details.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > timeout

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A state may optionally timeout at a given time or after a period of time. Timeout's make it possible to trigger a state change based on this.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > timeout > relative

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

Defines a relative timeout. i.e. 10 minutes or 1 hour.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > timeout > relative > interval

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A number specifying the length of the relative timeout.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > timeout > relative > units

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This gives context to the interval.

Possible values:

Setting Description
seconds The interval is for a number of seconds
minutes The interval is for a number of minutes
hours The interval is for a number of hours

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > timeout > absolute

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > timeout > atTimeOfDay

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > timeout > state

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This is a reference to an existing defined state. When a timeout occurs the tracker will change to this state.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > timeout > inlineState

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

The state to change to on timeout can also be defined inline rather than referencing an existing state.

Mandatory: Yes

trackerGroup > trackers > tracker > states > defaultState > templateOptions

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

These options apply only to templates.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > templateOptions > removeTracker

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This option removes the tracker when this state is entered. This only applies to trackers created via templates.

Mandatory: No
Default: false

trackerGroup > trackers > tracker > states > defaultState > allowTransitionToStates

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This setting allows transitions to only to the set of states following. If no states are defined then transitions are allowed to any state with a matching event.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > allowTransitionToStates > states > state

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A reference to a state defined within the tracker. Transitions are allowed to this state.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > allowTransitionToStates > states > inlineState

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This is an inline state definition for a state that you can transition to from this state. This state is one of the allowed transitions.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > allowTransitionToStates > onException > state

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A reference to a state defined within the tracker. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

trackerGroup > trackers > tracker > states > defaultState > allowTransitionToStates > onException > inlineState

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This is an inline state definition for a state that you can transition to from this state. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

trackerGroup > trackers > tracker > states > state

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

Defines an individual logical state for a tracker.

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > name

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A name for the state.

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > keys

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A collection of regular expressions that would trigger change to this state.

Mandatory: No

trackerGroup > trackers > tracker > states > state > keys > key

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A regular expression that if matched indicates a state change to this state.

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Where a capturing subgroup is found it is consider a parameter of the event that triggered the change and will be extracted for the view.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Note: Keys that are part of a template (see tracker > template must have a named capturing group called "id" within the pattern. Multiple named capture groups (<id1>, <id2>, etc) are not supported for trackers defined using deprecated syntax.

The syntax for this is:

(?<id>…)

The name is case sensitive and if your pattern does not contain this an error will be logged and the key ignored.

This is necessary to mark the text that will uniquely identify the item being tracked.

See Dynamic Tracking with Templates for more details.

Mandatory: No

trackerGroup > trackers > tracker > states > state > timeout

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A state may optionally timeout at a given time or after a period of time. Timeout's make it possible to trigger a state change based on this.

Mandatory: No

trackerGroup > trackers > tracker > states > state > timeout > relative

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

Defines a relative timeout. i.e. 10 minutes or 1 hour.

Mandatory: No

trackerGroup > trackers > tracker > states > state > timeout > relative > interval

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A number specifying the length of the relative timeout.

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > timeout > relative > units

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This gives context to the interval.

Possible values:

Setting Description
seconds The interval is for a number of seconds
minutes The interval is for a number of minutes
hours The interval is for a number of hours

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > timeout > absolute

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > timeout > atTimeOfDay

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > timeout > state

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This is a reference to an existing defined state. When a timeout occurs the tracker will change to this state.

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > timeout > inlineState

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

The state to change to on timeout can also be defined inline rather than referencing an existing state.

Mandatory: Yes

trackerGroup > trackers > tracker > states > state > templateOptions

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

These options apply only to templates.

Mandatory: No

trackerGroup > trackers > tracker > states > state > templateOptions > removeTracker

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This option removes the tracker when this state is entered. This only applies to trackers created via templates.

Mandatory: No
Default: false

trackerGroup > trackers > tracker > states > state > allowTransitionToStates

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This setting allows transitions to only to the set of states following. If no states are defined then transitions are allowed to any state with a matching event.

Mandatory: No

trackerGroup > trackers > tracker > states > state > allowTransitionToStates > states > state

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A reference to a state defined within the tracker. Transitions are allowed to this state.

Mandatory: No

trackerGroup > trackers > tracker > states > state > allowTransitionToStates > states > inlineState

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This is an inline state definition for a state that you can transition to from this state. This state is one of the allowed transitions.

Mandatory: No

trackerGroup > trackers > tracker > states > state > allowTransitionToStates > onException > state

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

A reference to a state defined within the tracker. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

trackerGroup > trackers > tracker > states > state > allowTransitionToStates > onException > inlineState

Deprecated. See trackerGroup > trackers > tracker > transitionStates.

This is an inline state definition for a state that you can transition to from this state. This state is transitioned to if an event is found that would lead to a transition to a state not in the allowed list.

If this is not set a state change does not occur. This setting has no effect if the list of allowed states is empty.

Mandatory: No

tracker

Deprecated, use tracker groups. See trackerGroup.

A tracker monitors a file for events signifying a logical state change.

One or more trackers may be defined to track / monitor different events. It is possible to have more than one tracker per file.

Mandatory: Yes

tracker > name

Deprecated, use tracker groups. See trackerGroup.

A unique name used to identity the tracker.

Mandatory: Yes

tracker > filename

Deprecated, use tracker groups. See trackerGroup.

A path specifying the file to be monitored. The filename may contain wildcards and standard Geneos <today> dates-stamping within filenames.

Mandatory: Yes

tracker > rewind

Deprecated, use tracker groups. See trackerGroup.

If the rewind flag is set the Tracker will monitor the file from the beginning. The default behaviour is to monitor the file as it grows for new events.

Mandatory: Yes
Default: false

tracker > filters

Deprecated, use tracker groups. See trackerGroup.

Filters are a means of filtering out messages before they are processed.

Mandatory: No

tracker > filters > filter

Deprecated, use tracker groups. See trackerGroup.

The filter is a regular expression that if matched will stop the message from being processed. For example if the log contains a number of debug messages indicated by DEBUG at the start of the line a filter can simply contain:

^DEBUG

This will filter out all messages beginning with DEBUG before processing.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Mandatory: Yes

tracker > messageTimestamp

Deprecated, use tracker groups. See trackerGroup.

It is usual for a log file to contain a timestamp. If one exists this provides a place to identify and interpret the timestamp within a message.

Mandatory: No

tracker > messageTimestamp > identifyingPattern

Deprecated, use tracker groups. See trackerGroup.

This is a regular expression that identifies a timestamp within a message. For example timestamp in of the form:

[2008-12-25-06-00-00] Rest of message here…

Could be picked out with the regular expression:

^\[(\d+-\d+-\d+-\d+-\d+-\d+)\]

This is enough to identify the date within the square brackets at the start of the message.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Mandatory: Yes

tracker > messageTimestamp > datePatternGroup

Deprecated, use tracker groups. See trackerGroup.

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Using the identifying pattern example again:

^\[(\d+-\d+-\d+-\d+-\d+-\d+)\]

This regular expression has a capturing subgroup to identify the date within the brackets. So here the datePatternGroup is 1. The default is to use the complete match which would still work in this instance.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Mandatory: Yes
Default: 0

tracker > messageTimestamp > dateFormat

Deprecated, use tracker groups. See trackerGroup.

This defines the format of the timestamp that has been extracted from the message. The Date codes used defined below define the way the adapter will process the timestamp. To interpret the date from "11:32:22.983 2008-11-21" a format of "%H:%M:%S%f %Y-%m-%d" should be used.

Specifier Replaced by
%a Abbreviated weekday name (i.e. Thu)
%A Full weekday name (i.e. Thursday)
%b Abbreviated month name (i.e. Aug)
%B Full month name (i.e. August)
%c Date and time representation (local dependant)
%d Day of the month (01-31)
%f Milliseconds. (Reads between 0 and 3 digits). The period is part of this code, to read seconds and milliseconds use %S%f. If you do not want the period included in the code please use %Of which reads just the digits.
%H Hour in 24h format (00-23)
%I Hour in 12h format (01-12)
%j Day of the year (001-366)
%m Month as a decimal number (01-12)
%M Minute (00-59)
%p AM or PM designation
%S Second (00-61)
%U Week number with the first Sunday as the first day of week one (00-53)
%w Weekday as a decimal number with Sunday as 0 (0-6)
%W Week number with the first Monday as the first day of week one (00-53)
%x Date representation (local dependant)
%X Time representation (local dependant)
%y Year, last two digits (00-99)
%Y Year, last all digits (i.e. 2008)
%Z Timezone name or abbreviation (i.e. CDT)
%% A % sign

On Unix systems some conversion specifications can be modified by preceding the conversion specifier character by the E or O modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behaviour will be as if the unmodified conversion specification were used. (SU) The Single Unix Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use alternative numeric symbols (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation.

Using the identifying pattern example again:

^\[(\d+-\d+-\d+-\d+-\d+-\d+)\]

and this time format:

%Y-%m-%d-%H-%M-%S

It is possible to interpret the timestamp on the message.

Mandatory: Yes

tracker > template

Deprecated, use tracker groups. See trackerGroup.

If true marks the tracker as a template. When a key is matched a tracker will be created based on this template. The tracker will need to be able to extract an id from the key.

Mandatory: No
Default: false

tracker > states

Deprecated, use tracker groups. See trackerGroup.

The logical states for a tracker are defined here.

Mandatory: Yes

tracker > states > defaultState

Deprecated, use tracker groups. See trackerGroup.

The initial state for the tracker.

Mandatory: Yes

tracker > states > defaultState > name

Deprecated, use tracker groups. See trackerGroup.

A name for the state.

Mandatory: Yes

tracker > states > defaultState > keys

Deprecated, use tracker groups. See trackerGroup.

A collection of regular expressions that would trigger change to this state.

Mandatory: No

tracker > states > defaultState > keys > key

Deprecated, use tracker groups. See trackerGroup.

A regular expression that if matched indicates a state change to this state.

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Where a capturing subgroup is found it is considered a parameter of the event that triggered the change and will be extracted for the view.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Note: Keys that are part of a template (see tracker > template have a named capturing group called "id within the pattern. Multiple named capture groups (<id1>, <id2>, etc) are not supported for trackers defined using deprecated syntax.

The syntax for this is:

(?<id>…)

The name is case sensitive and if your pattern does not contain this an error will be logged and the key ignored.

This is necessary to mark the text that will uniquely identify the item being tracked.

See Dynamic Tracking with Templates for more details.

Mandatory: No

tracker > states > defaultState > timeout

Deprecated, use tracker groups. See trackerGroup.

A state may optionally timeout at a given time or after a period of time. Timeout's make it possible to trigger a state change based on this.

Mandatory: No

tracker > states > defaultState > timeout > relative

Deprecated, use tracker groups. See trackerGroup.

Defines a relative timeout. i.e. 10 minutes or 1 hour.

Mandatory: No

tracker > states > defaultState > timeout > relative > interval

Deprecated, use tracker groups. See trackerGroup.

A number specifying the length of the relative timeout.

Mandatory: Yes

tracker > states > defaultState > timeout > relative > units

Deprecated, use tracker groups. See trackerGroup.

This gives context to the interval.

Possible values:

Setting Description
seconds The interval is for a number of seconds
minutes The interval is for a number of minutes
hours The interval is for a number of hours

Mandatory: Yes

tracker > states > defaultState > timeout > absolute

Deprecated, use tracker groups. See trackerGroup.

The state times out at an absolute time specified using the 24 hour clock in the format HH:MM[:SS]. The brackets indicate that seconds are optional.

Mandatory: Yes

tracker > states > defaultState > timeout > state

Deprecated, use tracker groups. See trackerGroup.

This is a reference to an existing defined state. When a timeout occurs the tracker will change to this state.

Mandatory: Yes

tracker > states > defaultState > timeout > inlineState

Deprecated, use tracker groups. See trackerGroup.

The state to change to on timeout can also be defined inline rather than referencing an existing state.

Mandatory: Yes

tracker > states > defaultState > templateOptions

Deprecated, use tracker groups. See trackerGroup.

These options apply only to templates.

Mandatory: No

tracker > states > defaultState > templateOptions > removeTracker

Deprecated, use tracker groups. See trackerGroup.

This option removes the tracker when this state is entered. This only applies to trackers created via templates.

Mandatory: No
Default: false

tracker > states > state

Deprecated, use tracker groups. See trackerGroup.

Defines an individual logical state for a tracker.

Mandatory: Yes

tracker > states > state > name

Deprecated, use tracker groups. See trackerGroup.

A name for the state.

Mandatory: Yes

tracker > states > state > keys

Deprecated, use tracker groups. See trackerGroup.

A collection of regular expressions that would trigger change to this state.

Mandatory: No

tracker > states > state > keys > key

Deprecated, use tracker groups. See trackerGroup.

A regular expression that if matched indicates a state change to this state.

Where a regular expression has a capturing subgroup (a bracketed expression) each one has a number as they appear from left to right starting at 1. Group 0 (zero) is the complete match.

Where a capturing subgroup is found it is consider a parameter of the event that triggered the change and will be extracted for the view.

Perl compatible regular expressions are supported, please see http://www.perl.com/doc/manual/html/pod/perlre.html for reference.

Note: Keys that are part of a template (see tracker > template must have a named capturing group called "id" within the pattern.

The syntax for this is:

(?<id>…)

The name is case sensitive and if your pattern does not contain this an error will be logged and the key ignored.

This is necessary to mark the text that will uniquely identify the item being tracked.

See Dynamic Tracking with Templates for more details.

Mandatory: No

tracker > states > state > timeout

Deprecated, use tracker groups. See trackerGroup.

A state may optionally timeout at a given time or after a period of time. Timeout's make it possible to trigger a state change based on this.

Mandatory: No

tracker > states > state > timeout > relative

Deprecated, use tracker groups. See trackerGroup.

Defines a relative timeout. i.e. 10 minutes or 1 hour.

Mandatory: No

tracker > states > state > timeout > relative > interval

Deprecated, use tracker groups. See trackerGroup.

A number specifying the length of the relative timeout.

Mandatory: Yes

tracker > states > state > timeout > relative > units

Deprecated, use tracker groups. See trackerGroup.

This gives context to the interval.

Possible values:

Setting Description
seconds The interval is for a number of seconds
minutes The interval is for a number of minutes
hours The interval is for a number of hours

Mandatory: Yes

tracker > states > state > timeout > absolute

Deprecated, use tracker groups. See trackerGroup.

Mandatory: Yes

tracker > states > state > timeout > atTimeOfDay

Deprecated, use tracker groups. See trackerGroup.

Mandatory: Yes

tracker > states > state > timeout > state

Deprecated, use tracker groups. See trackerGroup.

This is a reference to an existing defined state. When a timeout occurs the tracker will change to this state.

Mandatory: Yes

tracker > states > state > timeout > inlineState

Deprecated, use tracker groups. See trackerGroup.

The state to change to on timeout can also be defined inline rather than referencing an existing state.

Mandatory: Yes

tracker > states > state > templateOptions

Deprecated, use tracker groups. See trackerGroup.

These options apply only to templates.

Mandatory: No

tracker > states > state > templateOptions > removeTracker

Deprecated, use tracker groups. See trackerGroup.

This option removes the tracker when this state is entered. This only applies to trackers created via templates.

Mandatory: No
Default: false

[1] The d isn't really necessary but it's sometimes useful to put it in for people used to POSIX character classes who might not expect a "word" to match digits.