JESL is licensed under the Nastel Technologies EULA.

JESL allows application developers to stream time-series data to meshIQ.
To stream data to meshIQ Track, your application must:

• Use TNT4J, or MQTT/SLF4J/Log4j/Logback in your application to log events, activities, and metrics (see TNT4J-Streams).

• Obtain your jKool account and API access token at https://www.meshiq.com. The API access token is required to stream data to your XRay/Track repository.

• Use the JESL Event Sink implementation (contained in this project) within your TNT4J configuration (requires an API access token).

Maven Dependency

Add the JESL dependency to your project:

<dependency>
    <groupId>com.jkoolcloud</groupId>
    <artifactId>jesl</artifactId>
    <version>12.0.2</version>
</dependency>

Configure Streaming to XRay/Track

Configure your application to stream to XRay/Track using the JESL Event Sink (requires an API access token).
See: com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory.

TLS / HTTPS Note

To initiate HTTPS connections, JESL uses TLS v1.2+:

• TLS v1.2 — for all Java version 8 builds.

• TLS v1.3 — for Java version 8 starting with build 261+ (Oracle) / 262+ (OpenJDK) and later versions (11, 17, 21…).

Package Contents

JESL includes the following components:

• TNT4J streaming library with SLF4J support (see SLF4J Event Sink Integration).

  • JESL Simulator — streams simulated events, activities, and metrics to XRay/Track. Simulations are defined in XML files ( See <JESL>/sims/order-process.xml and >JESL>/sims/tnt4j-sim-template.xml).

• JESL Event Sink — TNT4J Event Sink implementation to stream events to XRay/Track.

JESL Simulator

The JESL Simulator provides the ability to simulate tracking activities and events. Activities, events, and their components are defined using an XML format. There are three major parts to a simulation definition:

• Sources — defines the sources involved in simulated activities and events.

• Messages — defines the messages that will be exchanged during activities.

• Activities and Events — defines the actual activities and their sub-activities and events.

The included file tnt4j-sim-template.xml contains a simulation definition template with detailed element descriptions and the XML hierarchy.
The file order-process.xml contains a sample set of activities and events, along with sample snapshots.

To define a simulation, copy one of the supplied XML simulation definition files as a template and create the necessary activity elements.

Modes

1. Simulation (simulation type: run)
   Runs a user-specified simulation file (e.g., sims/order-process.xml) and sends the tracking data to the JESL Event Sink and/or writes the tracking data to the specified file. In this mode, the simulator can be configured to run the simulation a specified number of iterations, optionally generating unique correlators and tags for each iteration (appends a unique value to the end of defined correlators and tags in the simulation definition file).

2. Replay (simulation type: replay)
   Reads previously saved tracking data from the specified file and sends it to the JESL Event Sink.

Running the Simulator

The simplest way to run the simulator is to execute jksim.bat (or jksim.sh) as follows:

jksim -A:api-access-token -f:sim-file -i:iterations
# Example:
jksim -A:MY-TOKEN -f:../sims/order-process.xml -i:5

• api-access-token — your API access token obtained during registration with jKool.

• sim-file — the simulation file that defines all interactions, events, and metrics. Sample files are under the <jesl>/sims/ folder (e.g., <jesl>/sims/order-process.xml).

• iterations — the number of iterations for the simulation (default: 1).

You may need to alter the jksim shell script to specify custom simulator parameters (such as simulation type) as well as other advanced options.

The simulator also contains options for allowing the data values used for some tracking component attributes to be altered to provide unique values for these attributes for each tracking activity so that each activity definition in the input file serves as a template for the activities to generate, allowing each to be a unique instance of an activity with the defined components. An example of such an attribute is the Correlator. If a Correlator is defined and the correlator value is not unique across each activity, then all activities will get stitched together into one large activity.

Options (Selected)

• -A — Specifies the access token used to validate connection to the JESL Event Sink. (Required when using the -T option.)

• -p — Scales each time attribute up or down by the specified percentage to introduce variation in event durations and intervals.

• -u — Makes correlators and tags unique between iterations by appending a timestamp to each one, so each iteration generates independent activities and events.

jksim.bat help

Prerequisite

Requires the TNT4J Appender for Log4j.

Log4j can be configured to stream events and metrics to meshIQ Track by using the JESL Log4j appender com.jkoolcloud.tnt4j.logger.log4j.TNT4JAppender as follows.

1) Add the JESL Log4j appender to your Log4j configuration

<!-- ### Default JESL Appender configuration ### -->
<Tnt4j name="meshiq_track" sourceName="com.jkoolcloud.jesl.stream" sourceType="APPL"
       metricsOnException="true" metricsFrequency="60">
    <PatternLayout>
        <Pattern>%d{ABSOLUTE} %-5p [%c{1}] %m%n</Pattern>
    </PatternLayout>
</Tnt4j>

<!-- ### jesl stream API logger -->
<AsyncLogger name="com.jkoolcloud.jesl.stream" level="OFF"/>
<!-- ### jkoolcloud API logger -->
<AsyncLogger name="com.jkoolcloud" level="INFO"/>
<!-- ### jesl API logger -->
<AsyncLogger name="com.jkoolcloud.jesl" level="INFO"/>

2) Map categories to the meshiq_track appender

<Logger name="com.myco.mypackage" level="INFO">
    <AppenderRef ref="meshiq_track"/>
</Logger>

3) Add JVM arguments to your Java start-up

-Dtnt4j.config=<jesl.home>/log4j/tnt4j.properties \
-Dtnt4j.token.repository=<jesl.home>/log4j/tnt4j-tokens.properties

Optional: enable automatic application dump

-Dtnt4j.dump.on.vm.shutdown=true \
-Dtnt4j.dump.on.exception=true \
-Dtnt4j.dump.provider.default=true

Optional: set default data center and geolocation

-Dtnt4j.source.DATACENTER=YourDataCenterName \
-Dtnt4j.source.GEOADDR="Melville, NY"

logger.info("Starting a tnt4j activity #beg=Test, #app=" + Log4JTest.class.getName());
logger.warn("First log message #app=" + Log4JTest.class.getName() + ", #msg='1 Test warning message'");
logger.error("Second log message #app=" + Log4JTest.class.getName() + ", #msg='2 Test error message'", new Exception("test exception"));
logger.info("Ending a tnt4j activity #end=Test, #app=" + Log4JTest.class.getName() + " #%i/order-no=" + orderNo);

Applications that use TNT4J can stream events and metrics to meshIQ Track by configuring the application source to use the JESL Event Sink (com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory).

Basic Configuration (tnt4j.properties)

{
    ....
    ; event sink configuration: destination and data format
    event.sink.factory: com.jkoolcloud.tnt4j.sink.impl.BufferedEventSinkFactory
    event.sink.factory.PooledLoggerFactory: com.jkoolcloud.tnt4j.sink.impl.PooledLoggerFactoryImpl

    event.sink.factory.EventSinkFactory: com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory
    event.sink.factory.EventSinkFactory.Url: https://stream.meshiq.com
    event.sink.factory.EventSinkFactory.Token: YOUR-ACCESS-TOKEN
    event.formatter: com.jkoolcloud.tnt4j.format.JSONFormatter
    ....
}

Example TNT4J source with JESL Event Sink (com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory):

{
    source: com.myco.myappl
    source.factory: com.jkoolcloud.tnt4j.source.SourceFactoryImpl
    source.factory.GEOADDR: New York
    source.factory.DATACENTER: HQDC
    source.factory.RootFQN: SERVER=?#DATACENTER=?#GEOADDR=?
    source.factory.RootSSN: tnt4j-myapp

    tracker.factory: com.jkoolcloud.tnt4j.tracker.DefaultTrackerFactory
    dump.sink.factory: com.jkoolcloud.tnt4j.dump.DefaultDumpSinkFactory

    ; event sink configuration: destination and data format
    event.sink.factory: com.jkoolcloud.tnt4j.sink.impl.BufferedEventSinkFactory
    event.sink.factory.PooledLoggerFactory: com.jkoolcloud.tnt4j.sink.impl.PooledLoggerFactoryImpl

    event.sink.factory.EventSinkFactory: com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory
    event.sink.factory.EventSinkFactory.Url: https://stream.meshiq.com
    event.sink.factory.EventSinkFactory.Token: YOUR-ACCESS-TOKEN
    event.formatter: com.jkoolcloud.tnt4j.format.JSONFormatter

    ; Configure default sink filter based on level and time (elapsed/wait)
    event.sink.factory.Filter: com.jkoolcloud.tnt4j.filters.EventLevelTimeFilter
    event.sink.factory.Filter.Level: TRACE
    ; Uncomment lines below to filter out events based on elapsed time and wait time
    ; Timed event/activities greater or equal to given values will be logged
    ;event.sink.factory.Filter.ElapsedUsec: 100
    ;event.sink.factory.Filter.WaitUsec: 100

    tracking.selector: com.jkoolcloud.tnt4j.selector.DefaultTrackingSelector
    tracking.selector.Repository: com.jkoolcloud.tnt4j.repository.FileTokenRepository
}

Provide your actual API access token in (event.sink.factory.EventSinkFactory.Token).

Fallback URLs

JKCloudEventSinkFactory allows multiple fallback URLs ( , comma-delimited). Only one is used at a time; the next is used if the current one becomes unavailable.

event.sink.factory.EventSinkFactory.Url: https://stream.meshiq.com,https://stream1.meshiq.com,https://stream.meshiq.com:6584

    event.formatter:com.jkoolcloud.tnt4j.format.JSONFormatter
; Configures special numeric values handling. Can be one of: SUPPRESS, ENQUOTE, MAINTAIN. Default value: SUPPRESS
event.formatter.SpecNumbersHandling:MAINTAIN

SpecNumbersHandling property values:

• SUPPRESS – Suppresses properties that have special numeric values. The produced JSON will not contain these activity entity properties.

• ENQUOTE – Encloses special numeric values in quotes. The produced JSON will contain quoted values, e.g., "Infinity", "NaN".

• MAINTAIN – Maintains the value as is. The produced JSON will contain literal numeric values, e.g., Infinity, NaN.

• ConnTimeout - defines connection timeout in milliseconds. Default - 10 sec.
• IdleTimeout - defines connection idle timeout in milliseconds. Default - 4min.
• AckSends - indicates connection to wait for acknowledgments for sent packages. Default - false.
• DisableSSLVerification - indicates connection to disable SSL validation (useful for expired certs). Default - false.

Sample:

event.sink.factory.EventSinkFactory: com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory
event.sink.factory.EventSinkFactory.Url: https://stream.meshiq.com
event.sink.factory.EventSinkFactory.Token: YOUR-ACCESS-TOKEN
event.sink.factory.EventSinkFactory.ConnTimeout: 5000
event.sink.factory.EventSinkFactory.IdleTimeout: 300000
event.sink.factory.EventSinkFactory.AckSends: true
event.sink.factory.EventSinkFactory.DisableSSLVerification: true

A proxy can be used to deliver data over the JESL Event Sink (com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory) for both HTTP(S) and TCP(S) layers.

To use an HTTP proxy, set the following configuration properties:

• ProxyScheme – Defines the proxy scheme to be used. One of: http or https. Default value: http. (Optional)

• ProxyHost – Defines the proxy host name or IP address.

• ProxyPort – Defines the proxy port number.

• ProxyUser – Defines the proxy login user. (Optional)

• ProxyPass – Defines the proxy user password. (Optional)

Sample:

event.sink.factory.EventSinkFactory: com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory
event.sink.factory.EventSinkFactory.Url: https://stream.meshiq.com
event.sink.factory.EventSinkFactory.Token: YOUR-ACCESS-TOKEN
event.sink.factory.EventSinkFactory.ProxyScheme: http
event.sink.factory.EventSinkFactory.ProxyHost: proxy.host.com
event.sink.factory.EventSinkFactory.ProxyPort: 8060
event.sink.factory.EventSinkFactory.ProxyUser: proxy-user
event.sink.factory.EventSinkFactory.ProxyPass: proxy-pass

To use a SOCKSv5 proxy, set the following configuration properties:

• ProxyHost – Defines the proxy host name or IP address.

• ProxyPort – Defines the proxy port number.

• ProxyUser – Defines the proxy login user. (Optional)

• ProxyPass – Defines the proxy user password. (Optional)

Sample:

event.sink.factory.EventSinkFactory: com.jkoolcloud.jesl.tnt4j.sink.JKCloudEventSinkFactory
event.sink.factory.EventSinkFactory.Url: tcp://172.16.6.25:6004
event.sink.factory.EventSinkFactory.ProxyHost: proxy.host.com
event.sink.factory.EventSinkFactory.ProxyPort: 8060
event.sink.factory.EventSinkFactory.ProxyUser: proxy-user
event.sink.factory.EventSinkFactory.ProxyPass: proxy-pass

Proxy authentication credentials can also be passed through JVM system properties java.net.socks.username and java.net.socks.password, for example:

-Djava.net.socks.username=proxy-user -Djava.net.socks.password=proxy-pass

Also see the Java SE documentation for additional proxy configuration options using JVM system properties.

<verb> <expression> show as <widget>

mvn clean package

mvn clean install

mvn -P pack-sources-and-javadocs

mvn -P final-release

JESL requires the following (which will download automatically if using Maven):

• JDK 17+
• TNT4J
• Apache HTTP Client
• SLF4J-Simple (runtime, optional)

• meshIQ