This article provides a sample configuration demonstrating how to dynamically define field names, locators, and value types in TNT4J-Streams using placeholder references and field-locators.
See the article Stream Elements Filtering Using Dynamic Locators for more details.
Running Samples
When release assemblies are built, samples are located in the samples directory, e.g., build/tnt4j-streams-12.0.0/samples. To run a particular sample:
- Go to the sample directory
- Run
run.batorrun.sh, depending on your OS
For more a detailed explanation of stream and parser configuration and usage see the 'Configuring TNT4J-Streams' and the JavaDocs.
Single Log File
This sample shows how to stream activity events (orders) data from a single log file.
Sample files can be found in samples/single-log directory.
orders.log file contains a set of order activity events. Each file line defines the data of a single order activity event.
Records in this file are from year 2011,
e.g. 12 Jul 2011, so when sending the events data to meshIQ,
please do not forget to adjust the dashboard time frame to that period!
Sample stream configuration:
<?xml version="1.0" encoding="utf-8"?>
<tnt-data-source
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://meshiq-xsd.s3.amazonaws.com/streams/tnt-data-source.xsd">
<parser name="TokenParser" class="com.jkoolcloud.tnt4j.streams.parsers.ActivityTokenParser">
<property name="FieldDelim" value="|"/>
<field name="StartTime" locator="1" format="dd MMM yyyy HH:mm:ss" locale="en-US"/>
<field name="ServerIp" locator="2"/>
<field name="ApplName" value="orders"/>
<field name="Correlator" locator="3"/>
<field name="UserName" locator="4"/>
<field name="EventName" locator="5"/>
<field name="EventType" locator="5">
<field-map source="Order Placed" target="START"/>
<field-map source="Order Received" target="RECEIVE"/>
<field-map source="Order Processing" target="OPEN"/>
<field-map source="Order Processed" target="SEND"/>
<field-map source="Order Shipped" target="END"/>
</field>
<field name="MsgValue" locator="8"/>
</parser>
<stream name="FileStream" class="com.jkoolcloud.tnt4j.streams.inputs.FileLineStream">
<property name="FileName" value="orders.log"/>
<!--<property name="RangeToStream" value="1:"/>-->
<parser-ref name="TokenParser"/>
</stream>
</tnt-data-source>Stream configuration states that FileLineStream referencing TokenParser shall be used.
FileStream reads data from orders.log file.
TokenParser uses the | symbol as the fields delimiter and maps fields to TNT4J event fields using a field index locator.
StartTime field defines the format
and locale to correctly parse the field data string. EventType uses
a manual field string mapping to TNT4J event field values.
Multiple Log Files
This sample shows how to stream activity events (orders) data from multiple log files using filename-matching wildcard pattern.
Sample files can be found in samples/multiple-logs directory.
orders-in.log and orders-out.log files contain a set of order activity events. Each file line defines the data of a single order activity event.
Records in this file are from year 2011,
e.g. 12 Jul 2011, so when sending the events data to meshIQ,
please do not forget to adjust the dashboard time frame to that period!
Sample configuration and sample idea are the same as the Single Log file sample with one single difference:
<property name="FileName" value="orders-*.log"/>
meaning that stream should process not one single file, but the set of files matching the orders-*.log wildcard pattern.
OS Piped Stream
This sample shows how to stream activity events (orders) data received over an OS pipe from another application or OS command.
Sample files can be found in samples/piping-stream directory.
orders.log file contains a set of order activity events. Each file line defines the data of a single order activity event.
Records in this file are from year 2011,
e.g. 12 Jul 2011, so when sending the events data to meshIQ,
please do not forget to adjust the dashboard time frame to that period!
jk-pipe.bat or jk-pipe.sh files are wrappers for bin/tnt4j-streams executables to minimize parameters. All you need is to pass the file name of the stream parser configuration, e.g., parsers.xml
run.bat or run.sh files use OS piping to run a sample.
Sample parser configuration:
<?xml version="1.0" encoding="utf-8"?>
<tnt-data-source
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://meshiq-xsd.s3.amazonaws.com/streams/tnt-data-source.xsd">
<parser name="TokenParser" class="com.jkoolcloud.tnt4j.streams.parsers.ActivityTokenParser">
<property name="FieldDelim" value="|"/>
<field name="StartTime" locator="1" format="dd MMM yyyy HH:mm:ss" locale="en-US"/>
<field name="ServerIp" locator="2"/>
<field name="ApplName" value="orders"/>
<field name="Correlator" locator="3"/>
<field name="UserName" locator="4"/>
<field name="EventName" locator="5"/>
<field name="EventType" locator="5">
<field-map source="Order Placed" target="START"/>
<field-map source="Order Received" target="RECEIVE"/>
<field-map source="Order Processing" target="OPEN"/>
<field-map source="Order Processed" target="SEND"/>
<field-map source="Order Shipped" target="END"/>
</field>
<field name="MsgValue" locator="8"/>
</parser>
</tnt-data-source>For details on parser configuration see the sample named Single Log File.
Zipped File Lines
This sample shows how to stream activity events (Apache access log records) data from zipped file entries.
Sample files can be found in samples/zip-stream directory.
sample.zip and sample.gz files contain a set of compressed Apache access log records.
Sample stream configuration:
<?xml version="1.0" encoding="utf-8"?>
<tnt-data-source
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://meshiq-xsd.s3.amazonaws.com/streams/tnt-data-source.xsd">
<parser name="AccessLogParserExt" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b %D"/>
<property name="ConfRegexMapping" value="%*r=(((\S+) (.*?)( (\S+))?)|(-))"/>
<property name="ConfRegexMapping" value="%*i=(.*?)"/>
<field name="Location" locator="1" locator-type="Index"/>
<field name="UserName" locator="3" locator-type="Index"/>
<field name="StartTime" locator="4" locator-type="Index" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="7" locator-type="Index"/>
<field name="ResourceName" locator="8" locator-type="Index"/>
<field name="CompCode" locator="12" locator-type="Index">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="12" locator-type="Index"/>
<field name="MsgValue" locator="13" locator-type="Index"/>
<field name="ElapsedTime" locator="15" locator-type="Index" datatype="Number" format="#####0.000"
locale="en-US" units="Seconds"/>
</parser>
<parser name="AccessLogParserCommon" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b"/>
<property name="ConfRegexMapping" value="%*r=(((\S+) (.*?)( (\S+))?)|(-))"/>
<property name="ConfRegexMapping" value="%*i=(.*?)"/>
<field name="Location" locator="1" locator-type="Index"/>
<field name="UserName" locator="3" locator-type="Index"/>
<field name="StartTime" locator="4" locator-type="Index" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="7" locator-type="Index"/>
<field name="ResourceName" locator="8" locator-type="Index"/>
<field name="CompCode" locator="12" locator-type="Index">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="12" locator-type="Index"/>
<field name="MsgValue" locator="13" locator-type="Index"/>
</parser>
<stream name="SampleZipFileStream" class="com.jkoolcloud.tnt4j.streams.inputs.ZipLineStream">
<property name="FileName" value="./tnt4j-streams-core/samples/zip-stream/sample.zip"/>
<!--<property name="FileName" value="./tnt4j-streams-core/samples/zip-stream/sample.zip!2/*.txt"/>-->
<!--<property name="FileName" value="./tnt4j-streams-core/samples/zip-stream/sample.gz"/>-->
<!--<property name="ArchType" value="GZIP"/>-->
<parser-ref name="AccessLogParserExt"/>
<parser-ref name="AccessLogParserCommon"/>
</stream>
</tnt-data-source>Stream configuration states that ZipLineStream referencing AccessLogParserExt and AccessLogParserCommon shall be used.
ZipLineStream reads all entry lines from the sample.zip file.
To filter zip file entries use a zip entry name wildcard pattern, e.g., sample.zip!2/*.txt. In this case, the stream will read only zipped files with the extension txt from the internal zip directory named 2 (including sub-directories).
Details on AccessLogParserCommon (or ApacheAccessLogParser in general) can be found in samples section Apache Access Log Single File and parsers configuration section 'Apache access log parser'.
Standard Java InputStream/Reader
This sample shows how to stream activity events (Apache access log records) data read from standard Java input.
Sample files can be found in samples/java-stream directory.
Sample stream configuration:
<?xml version="1.0" encoding="utf-8"?>
<tnt-data-source
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://meshiq-xsd.s3.amazonaws.com/streams/tnt-data-source.xsd">
<parser name="AccessLogParserExt" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b %D"/>
<property name="ConfRegexMapping" value="%*r=(((\S+) (.*?)( (\S+))?)|(-))"/>
<property name="ConfRegexMapping" value="%*i=(.*?)"/>
<field name="Location" locator="1" locator-type="Index"/>
<field name="UserName" locator="3" locator-type="Index"/>
<field name="StartTime" locator="4" locator-type="Index" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="7" locator-type="Index"/>
<field name="ResourceName" locator="8" locator-type="Index"/>
<field name="CompCode" locator="12" locator-type="Index">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="12" locator-type="Index"/>
<field name="MsgValue" locator="13" locator-type="Index"/>
<field name="ElapsedTime" locator="15" locator-type="Index" datatype="Number" format="#####0.000"
locale="en-US" units="Seconds"/>
</parser>
<parser name="AccessLogParserCommon" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b"/>
<property name="ConfRegexMapping" value="%*r=(((\S+) (.*?)( (\S+))?)|(-))"/>
<property name="ConfRegexMapping" value="%*i=(.*?)"/>
<field name="Location" locator="1" locator-type="Index"/>
<field name="UserName" locator="3" locator-type="Index"/>
<field name="StartTime" locator="4" locator-type="Index" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="7" locator-type="Index"/>
<field name="ResourceName" locator="8" locator-type="Index"/>
<field name="CompCode" locator="12" locator-type="Index">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="12" locator-type="Index"/>
<field name="MsgValue" locator="13" locator-type="Index"/>
</parser>
<java-object name="SampleFileStream" class="java.io.FileInputStream">
<param name="fileName" value="./tnt4j-streams-core/samples/zip-stream/sample.gz" type="java.lang.String"/>
</java-object>
<java-object name="SampleZipStream" class="java.util.zip.GZIPInputStream">
<param name="stream" value="SampleFileStream" type="java.io.InputStream"/>
</java-object>
<!--java-object name="SampleFileReader" class="java.io.FileReader">
<param name="fileName" value="./tnt4j-streams-core/samples/apache-access-single-log/access.log"
type="java.lang.String"/>
</java-object-->
<stream name="SampleJavaInputStream" class="com.jkoolcloud.tnt4j.streams.inputs.JavaInputStream">
<property name="HaltIfNoParser" value="false"/>
<reference name="SampleZipStream"/>
<!--reference name="SampleFileReader"/-->
<reference name="AccessLogParserExt"/>
<reference name="AccessLogParserCommon"/>
</stream>
</tnt-data-source>Stream configuration states that SampleJavaInputStream referencing AccessLogParserExt and AccessLogParserCommon shall be used.
SampleJavaInputStream reads all lines from SampleZipStream, referring to the FileInputStream SampleFileStream, which reads the file sample.gz.
The java-object/param@value value
may be a reference to a configuration already-defined object like SampleFileStream in
this particular sample.
To use a Reader as input, you should uncomment the configuration lines defining and referring to SampleFileReader and comment out the SampleZipStream reference.
Details on AccessLogParserCommon (or ApacheAccessLogParser in general) can be found in samples section Apache Access Log Single File and parsers configuration section 'Apache access log parser'.
Apache Access Log: Single File
This sample shows how to stream Apache access log records as activity events from a single log file.
Sample files can be found in samples/apache-access-single-log directory.
access.log is a sample Apache access log file depicting some HTTP server activity.
Records in this file are from year 2004,
e.g. 07/Mar/2004, so when sending the events data to meshIQ,
please do not forget to adjust the dashboard time frame to that period!
Sample stream configuration:
<?xml version="1.0" encoding="utf-8"?>
<tnt-data-source
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://meshiq-xsd.s3.amazonaws.com/streams/tnt-data-source.xsd">
<parser name="AccessLogParserExt" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b %D"/>
<!--property name="Pattern"
value="^(\S+) (\S+) (\S+) \[([\w:/]+\s[+\-]\d{4})\] "(((\S+) (.*?)( (\S+)|()))|(-))" (\d{3}) (\d+|-)( (\S+)|$)"/-->
<property name="ConfRegexMapping" value="%*r=(((\S+) (.*?)( (\S+)|()))|(-))"/>
<property name="ConfRegexMapping" value="%*i=(.*?)"/>
<field name="Location" locator="1" locator-type="Index"/>
<field name="UserName" locator="3" locator-type="Index"/>
<field name="StartTime" locator="4" locator-type="Index" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="7" locator-type="Index"/>
<field name="ResourceName" locator="8" locator-type="Index"/>
<field name="CompCode" locator="12" locator-type="Index">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="12" locator-type="Index"/>
<field name="MsgValue" locator="13" locator-type="Index"/>
<field name="ElapsedTime" locator="15" locator-type="Index" datatype="Number" format="#####0.000" locale="en-US" units="Seconds"/>
</parser>
<parser name="AccessLogParserCommon" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b"/>
<property name="ConfRegexMapping" value="%*r=(((\S+) (.*?)( (\S+)|()))|(-))"/>
<property name="ConfRegexMapping" value="%*i=(.*?)"/>
<field name="Location" locator="1" locator-type="Index"/>
<field name="UserName" locator="3" locator-type="Index"/>
<field name="StartTime" locator="4" locator-type="Index" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="7" locator-type="Index"/>
<field name="ResourceName" locator="8" locator-type="Index"/>
<field name="CompCode" locator="12" locator-type="Index">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="12" locator-type="Index"/>
<field name="MsgValue" locator="13" locator-type="Index"/>
</parser>
<stream name="FileStream" class="com.jkoolcloud.tnt4j.streams.inputs.FileLineStream">
<property name="HaltIfNoParser" value="false"/>
<property name="FileName" value="access.log"/>
<!--<property name="RangeToStream" value="1:"/>-->
<parser-ref name="AccessLogParserExt"/>
<parser-ref name="AccessLogParserCommon"/>
</stream>
</tnt-data-source>Stream configuration states that FileLineStream, referencing AccessLogParserExt and AccessLogParserCommon shall be used. Note that multiple parsers can be used to parse stream entry data, meaning that activity event data will be produced by the first parser capable of parsing entry data.
FileStream reads data from the access.log file. HaltIfNoParser property states that the stream should skip unparseable entries and not stop if such a situation occurs.
AccessLogParserCommon parser is dedicated to parsing Apache access log entries made using the default logging configuration.
LogPattern defines the logger pattern used to log entries to the log file. Using this property parser is capable of automatically building a RegEx to parse log entry fields.
The user is also allowed to manually define a RegEx for the log entry line using the Pattern property.
ConfRegexMapping properties are used to allow the user to override the default log pattern token-RegEx mappings and define them manually to improve the automatically build entry line RegEx.
Activity event field mapping is performed using a locator identifying the RegEx pattern group index.
AccessLogParserExt differs from AccessLogParserCommon only by having one additional log token %D in the LogPattern property.
So if for example half of the log file was made using the log pattern defined in the AccessLogParserCommon parser LogPattern property and the second part using the log pattern defined in the AccessLogParserExt parser LogPattern property, the stream should be able to handle the whole log file with no problems.
StartTime field defines the format
and locale to correctly parse the field data string. CompCode uses
a manual field string mapping to TNT4J event field values.
Apache Access Log Single File - Named RegEx Groups Mappings
The sample does the same as the Apache Access Log Single File but uses named RegEx group mapping for parser-defined fields.
Sample stream configuration:
<?xml version="1.0" encoding="utf-8"?>
<tnt-data-source
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://meshiq-xsd.s3.amazonaws.com/streams/tnt-data-source.xsd">
<parser name="AccessLogParserExt" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b %D"/>
<property name="ConfRegexMapping"><![CDATA[%*r=(?<request>((?<method>\S+) (?<uri>.*?)( (?<version>\S+))?)|(-))]]></property>
<field name="Location" locator="hostname" locator-type="Label"/>
<field name="UserName" locator="user" locator-type="Label"/>
<field name="StartTime" locator="time" locator-type="Label" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="method" locator-type="Label"/>
<field name="ResourceName" locator="uri" locator-type="Label"/>
<field name="CompCode" locator="status" locator-type="Label">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="status" locator-type="Label"/>
<field name="MsgValue" locator="sizeClf" locator-type="Label"/>
<field name="ElapsedTime" locator="reqTime" locator-type="Label" datatype="Number" format="#####0.000" locale="en-US"
units="Seconds"/>
</parser>
<parser name="AccessLogParserCommon" class="com.jkoolcloud.tnt4j.streams.custom.parsers.ApacheAccessLogParser">
<property name="LogPattern" value="%h %l %u %t "%r" %s %b"/>
<property name="ConfRegexMapping"><![CDATA[%*r=(?<request>((?<method>\S+) (?<uri>.*?)( (?<version>\S+))?)|(-))]]></property>
<field name="Location" locator="hostname" locator-type="Label"/>
<field name="UserName" locator="user" locator-type="Label"/>
<field name="StartTime" locator="time" locator-type="Label" format="dd/MMM/yyyy:HH:mm:ss Z" datatype="DateTime" locale="en-US"/>
<field name="EventType" value="SEND"/>
<field name="EventName" locator="method" locator-type="Label"/>
<field name="ResourceName" locator="uri" locator-type="Label"/>
<field name="CompCode" locator="status" locator-type="Label">
<field-map source="100:206" target="SUCCESS" type="Range"/>
<field-map source="300:308" target="WARNING" type="Range"/>
<field-map source="400:417" target="ERROR" type="Range"/>
<field-map source="500:511" target="ERROR" type="Range"/>
</field>
<field name="ReasonCode" locator="status" locator-type="Label"/>
<field name="MsgValue" locator="sizeClf" locator-type="Label"/>
</parser>
<stream name="FileStream" class="com.jkoolcloud.tnt4j.streams.inputs.FileLineStream">
<property name="HaltIfNoParser" value="false"/>
<property name="FileName" value="./tnt4j-streams-core/samples/apache-access-single-log/access.log"/>
<property name="RestoreState" value="false"/>
<!--<property name="RangeToStream" value="1:"/>-->
<!--<property name="UseExecutors" value="true"/>-->
<!--<property name="ExecutorThreadsQuantity" value="5"/>-->
<!--<property name="ExecutorsTerminationTimeout" value="20"/>-->
<!--<property name="ExecutorsBoundedModel" value="false"/>-->
<!--<property name="ExecutorRejectedTaskOfferTimeout" value="20"/>-->
<parser-ref name="AccessLogParserExt"/>
<parser-ref name="AccessLogParserCommon"/>
</stream>
</tnt-data-source>See the parsers configuration section 'Apache access log parser' for the default RegEx group names used by ApacheAccessLogParser.
Apache Access Log: Multiple Files
This sample shows how to stream Apache access log records as activity events from multiple log files using file name matching wildcard pattern.
Sample files can be found in samples/apache-access-multi-log directory.
localhost_access_log.[DATE].txt is a sample Apache access log file depicting some HTTP server activity.
Records in this file are from year 2015 ranging
from April until November, so when sending the events data to meshIQ,
please do not forget to adjust the dashboard time frame to that period!
Sample configuration and sample idea are the same as the Apache Access Log Single File sample with one difference:
<property name="FileName" value="*_access_log.2015-*.txt"/>
meaning that the stream should process not a single file, but the set of files matching the *_access_log.2015-*.txt wildcard pattern.