Skip to content

Runtime JS

The runtime JavaScript API is the primary control method for dynamically configuring the 10x Engine and operating on typed TenXObjects. To load custom .js files see JavaScript configuration.

Quick Start Guides

API Reference

This API provides the base classes from which custom input, object and summary initializers are derived as well utility functions for operating on strings, numbers, lookups, etc.

Name Description
TenXBaseObject Provide a joint class base for TenXObject, summary and template and instances.
TenXInput Serves as a base class to allow for custom input initialization.
TenXOutput Serves as a base class to allow for custom output initialization.
TenXUnit Serves as a base class to allow for custom pipeline unit initialization.
TenXObject Provide structured, reflective access to log/trace events read from input(s)
TenXSummary Access aggregate values of TenXObjects which share a target set of field values.
TenXTemplate Base class for custom template initialization.
TenXCollection Base class for collection utilities (arrays and maps).
TenXArray Query array elements, length, and search.
TenXMap Utilities for map (object) operations.
TenXString Search, pattern-match and join string values.
TenXLookup Load and query the values of text lookup tables (.csv, .tsv) and geoIP DB files (.mmdb).
TenXConsole Print values to the host process' stdout/stderr output streams.
TenXDate Access system time and formatting/parsing date values.
TenXCounter Get and set the values of global atomic counters.
TenXMath Mathematical functions such as aggregation, parsing and hashing.
TenXEnv Access 10x launch arguments.
TenXLog Write messages to the 10x log.
TenXEngine The 10x Engine provides the underlying implementation of all classes and functions in the 'tenx.js' module.

10x JavaScript does NOT allow for explicit new object allocations, loops, and other language constructs that have indeterminate execution times/memory costs.

TenXBaseObject

Provide a joint class base for TenXObject, summary and template and instances.

Objects: provide a structured approach to operating on semi/unstructured events. To learn more see TenXObject

Templates:describe the schema/structure of other TenXObject similar to programmatic classes (who are themselves object instances) who describes the structure of other instances. To learn more see TenXTemplates.

Summaries: aggregate the values of other Objects. Summaries are instantiated by an aggregator after a certain number of TenXObjects have been aggregated or a certain interval has elapsed. They are commonly used with time series outputs (e.g. Prometheus) To learn more see TenXSummary

Kind: global class

text : string

The content of the event from which this instance was structured. This value may be read directly from an input or calculated on demand for expanded instances.

Kind: instance property of TenXBaseObject

utf8Size : number

The byte size of UTF8 encoding of text.

Kind: instance property of TenXBaseObject

fullText : string

A text value extracted from the input stream from which the object originated which encloses its text field. For example, if an object's text reflects a field extracted from a JSON object, The value of fullText will return the text of its entire enclosing JSON object.

Kind: instance property of TenXBaseObject

vars : Array.<string>

An array of variable sequences extracted from the object's text. The length function can be used to query the number of elements in this array.

Kind: instance property of TenXBaseObject
Example

export class HttpObject extends TenXObject {
  // Compute an HTTP error code field from the penultimate entry in vars[]
  // according to: https://httpd.apache.org/docs/2.4/logs.html schema.
  // For example, this will extract the '200' value into the 'code' field from:
  // 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326
  constructor() {
    // Grab the penultimate variable value
    var code =  TenXMath.parseInt(this.vars[-2]); 
    // Validate it's in the correct range       
    this.code = (code >= 200) && (code < 600) ? code : 0;
  }
}

isTemplate : boolean

Returns whether the current object is an TenXTemplate instance. To learn more see TenXTemplates

Kind: instance property of TenXBaseObject

isObject : boolean

Returns whether the current instance is an object and not a template or summary instance.

Kind: instance property of TenXBaseObject

isEncoded : boolean

Returns whether the current TenXObject was read from a compact input stream. To learn more see TenXTemplates

Kind: instance property of TenXBaseObject

isSummary : boolean

Returns whether the current object is a summary instance produced by an aggregator

Kind: instance property of TenXBaseObject

template : string

A sequence of all symbol and delimiter tokens from the object's text field. To learn more see TenXTemplates.

Kind: instance property of TenXBaseObject

templateHash : string

An alphanumeric encoded value of a 64bit hash of the current object's template field.

Kind: instance property of TenXBaseObject

timestamped : boolean

Return true if the instance is timestamped. Epoch values are accessible via the timestamp array.

Kind: instance property of TenXBaseObject

inputName : string

Returns the context in which the current object, template or summary was created.

At run time it may be needed to treat TenXObjects differently based on the input or aggregator from which they originated.

For example, to check if the current TenXObject was read from the 'Fluentd' input, as configured via its inputName, the following check can be made:

Kind: instance property of TenXBaseObject
Example

class MyObject extends TenXObject {
   constructor() {

      if (this.inputName == "Fluentd") {
        TenXCounter.inc("Fluentd");
        if this.startsWith("DEBUG") this.drop();
     } 
   }
}

get(field, [index]) ⇒ number | string | boolean

Returns the value of a target intrinsic, extracted or calculated field of the current instance.

This function produces and returns a JSON object listing all intrinsic (i.e., built into all objects), extracted (i.e., JSON and Key/Value fields automatically extracted from the object's text field) and encoded (i.e., assigned into the object through an event action) fields.

Kind: instance method of TenXBaseObject
Returns: number | string | boolean - Value of 'field' at position 'index'

Param Type Default Description
field string Field name to whose value to return
[index] number 0 Index of the element if 'field' is an array

Example

export class MyObject extends TenXObject {
  // filter instances for which the value of 'myField'
  // is different than the 'myValue' launch argument  
  constructor() {
    this.drop(this.get(TenXEnv.get("myField") != TenXEnv.get("myValue"));
  }
}

set(field, value) ⇒ boolean

Set a target value into a calculated field

This function is similar to Reflect.set.

Note that intrinsic fields (i.e., fields declared by this class) cannot be set.

Calls to this function can only be made from within an TenXObject's constructor.

Kind: instance method of TenXBaseObject
Returns: boolean - return true if the value was set

Param Type Description
field string Field name to set
value number | string | boolean to assign to field

Example

export class MyGeoObject extends TenXObject {
  // Assign a geo-ref lookup value (e.g., country, region) specified by a launch argument to a matching field
  constructor() {
    this.set(TenXEnv.get("geoField"), TenXLookup.get("geoIP"), this.ipAddress, TenXEnv.get("geoField"));
  }
}

joinFields(delimiter, ...fields) ⇒ string

Returns a new String composed of evaluated TenXObject fields joined together with the specified delimiter or as a JSON object containing the field name/value pairs.

Kind: instance method of TenXBaseObject
Returns: string - a String composed of the evaluated fields separated by the delimiter. If an empty delimiter is passed, the field values are formatted and escaped as JSON values of an array. If only one argument is passed, the values of the argument are treated as the array of fields to join and the delimiter is assumed to be empty (formatting as JSON).

Param Type Description
delimiter string the delimiter that separates each field value (should be one character long)
...fields Array.<string> the current TenXObject's intrinsic/extracted/calculated fields to join.

length() ⇒ number

Invokes length, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

includes() ⇒ boolean

Invokes includes, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

startsWith() ⇒ boolean

Invokes startsWith, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

endsWith() ⇒ boolean

Invokes endsWith, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

indexOf() ⇒ number

Invokes indexOf, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

lastIndexOf() ⇒ number

Invokes lastIndexOf, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

toLowerCase() ⇒ string

Invokes toLowerCase, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

toUpperCase() ⇒ string

Invokes toUpperCase, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

matchAll() ⇒ Array.<string>

Invokes matchAll, passing text as the value of 'str'.

Kind: instance method of TenXBaseObject

match() ⇒ string

Invokes match, passing text as the value of 'str'.

replace() ⇒ string

Invokes replace, passing text as the value of 'str'

Kind: instance method of TenXBaseObject

toString() ⇒ string

Returns a JSON representation of the current instance's intrinsic, extracted, and calculated fields.

This function returns a JSON object listing all intrinsic (i.e., built into all TenXObjects), extracted (i.e., JSON/KV entries extracted from text) and calculated (i.e., assigned into the instance within its constructor) fields.

This function is useful for examining the state of a specific instance, especially in conjunction with the log() function.

To print the JSON description of every object whose text field contains the 'target' variable to console:

Kind: instance method of TenXBaseObject
Returns: string - the object's JSON representation
Example

if this.includes(TenXEnv.get("target")) TenXConsole.log(this.toString());

token([tokenOffset], [tokenTypes], [from]) ⇒ string

Returns the value of specific tokens within the current TenXObject.

TenXObjects are comprised of tokens, which are alpha-numeric values categorized as:

  • symbol: values found in the pipeline's symbol library.
  • delimiter: single length token delimiters (e.g. ',;<>.').
  • variable: alpha-numeric values that are neither delimiter nor symbols.

This function provides a mechanism for querying the current TenXObject's token structure.

Kind: instance method of TenXBaseObject
Returns: string - Value of the token of type 'tokenTypes', having skipped 'tokenOffset' tokens from the 'startIndex' start position

Param Type Default Description
[tokenOffset] number 0 Number of tokens within the object's tokens array to begin searching from.
[tokenTypes] number variable Comma delimited string containing the token type(s) to search for. Available values: [symbol, variable, delimiter].
[from] number | string 0 Number: Position within the target string to begin searching for the target token. If positive, the zero-based n character is used. If negative, the (length - n - 1) is used if the index is out of bounds, it is ignored and 0 is used.

Example

The following call can be made to look for the second variable in the current TenXObject:

this.status = this.token(2, "variable");

tokenSize() ⇒ number

Returns the number of tokens in the current TenXObject's text field. To learn more about tokens, see:token delimitershttps://doc.log10x.com/run/transform/structure/#delimiters)

Kind: instance method of TenXBaseObject
Returns: number - number of tokens in the current object

findToken(type, valueOrFrom, [to]) ⇒ number

Returns the index of the first token matching the specified type and criteria.

Tokens within timestamp and IPaddress values are excluded from the search.

Kind: instance method of TenXBaseObject
Returns: number - Index of the first matching token, or -1 if not found. If valueOrFrom is array/map, returns first token included in array or map keyset.

Param Type Description
type string Token type to search for: "symbol" or "variable".
valueOrFrom number | string | Array.<(number|string)> | Object Single value to match, or array/map (generated by TenXMap.fromEntries) for inclusion check, or 'from' for range (number/string).
[to] number | string Optional 'to' for range (same type as valueOrFrom).

timestampStart(index) ⇒ number

Returns the index of within the object's text where the Nth timestamp sequence begins (inclusive).

To learn more see timestamp extraction.

Kind: instance method of TenXBaseObject
Returns: number - zero-based index of the start position (inclusive), -1 if not found

Param Type Description
index number Index within the timestamp array to use. A negative value can be provided to search from the end of the timestamp array

timestampEnd(index) ⇒ number

Returns the index of within the object's text where the Nth timestamp sequence ends (exclusive).

To learn more see timestamp extraction.

Kind: instance method of TenXBaseObject
Returns: number - zero-based index of the end position (exclusive), -1 if not found

Param Type Description
index number Index within the timestamp array to use. A negative value can be provided to search from the end of the timestamp array

timestampFormat([timestampIndex]) ⇒ string

Returns the timestamp pattern for the specified timestamp.

For example, for an event whose timestamp is equal to: '2021-09-16T02:33:05.289552Z', the return value would be: yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'

To learn more see timestamp extraction.

Kind: instance method of TenXBaseObject
Returns: string - Timestamp pattern if found, otherwise an empty value

Param Type Default Description
[timestampIndex] number 0 Index of the desired timestamp within the object's timestamp array.

TenXInput

Kind: global class

Serves as a base class to allow for custom input initialization.

Input constructors allow for the initialization of resources needed for event processing and aggregation such as setting counters, loading lookup tables via load() or connecting to GeoIP DBs via loadGeoIPDB().

These resources are available by TenXObject and TenXSummary sub-class to enrich and filter instances.

inputName

The name of this input (e.g., 'myElastic') as defined by the input configuration.

.get(key) ⇒ number | string | boolean

Get an input value specified by a key name.

This function gets a specific entry from a input field whose values are shared between different TenXObjects of the same input.

Kind: static method of TenXInput
Returns: number | string | boolean - value of the input field. Empty string if input field item was not previously set.

Param Type Description
key string name of the input field to get.

.set(key, value) ⇒ number | string | boolean

Set the value of the input field specified by the key name.

This function sets a specific entry from a input field whose values are shared between different TenXObjects of the same input.

Kind: static method of TenXInput
Returns: number | string | boolean - The value of the input field before the new value is set. Empty string if set for the first time.

Param Type Description
key string Name of the input input field to set.
value number | string | boolean Value to set in the input field.

TenXOutput

Kind: global class

Serves as a base class to allow for custom output initialization.

Output constructors allow for the initialization of resources needed for event processing and aggregation such as setting counters.

Each option defined in the output's declaring module is available at runtime as a named member. For example, the outputFilePath option can be accessed as a named member of the output instance:

export class FileOutput extends TenXOutput {
    constructor() { 
        if (this.outputFilePath) {
            if (this.outputFileWriteObjects != false) {
                if (this.outputFileWriteTemplates) {
                    TenXConsole.log("Writing TenXObjects and TenXTemplates to: " + this.outputFilePath);
                } else {
                    TenXConsole.log("Writing TenXObjects to: " + this.outputFilePath);
                }
            } else if (this.outputFileWriteTemplates ) {
                TenXConsole.log("Writing TenXTemplates to: " + this.outputFilePath);
            }
        }
    }
}

outputName

Provides a logical name for the output instance as defined by its declaring module.

outputType

Provides the type of the output. Possible values: file, stdout, event, metric.

TenXUnit

Kind: global class

Serves as a base class to allow for custom pipeline unit initialization and shutdown.

Unit constructors allow for the initialization of resources needed for pipeline execution such as setting counters and configuring unit-specific behavior.

Unit close allow for releasing resources or finalizing actions such as closing connections and printing post-processing results.

Each option defined in the unit's declaring module is available at runtime as a named member. For example, unit configuration options can be accessed as named members of the unit instance:

// @loader: tenx

import {TenXUnit, TenXEnv, TenXConsole} from '../../../../../../lib/script/tenx'

export class ConfigLoadUnit extends TenXUnit {

    static get shouldLoad() {
       return !TenXEnv.get("quiet", false);
    }

    constructor() { 

        if (this.unitName == "configLoader") {

            TenXConsole.log("🛠️ Launching 10x Engine: Dev app (local development & testing environment)");
        }
    }

    close() {

        if (this.unitName == "configLoader") {

            TenXConsole.log("🛠️ Pipeline excecution complete");
        }
    }
}

These resources are available by TenXObject and TenXSummary sub-class to enrich and filter instances.

unitName

Provides a logical name for the unit instance as defined by its declaring module.

TenXTemplate

Kind: global class

Serves as a base class to allow for custom template initialization.

Static members allow all instances of the same template to share members.

The example below assigns TenXTemplates with a calculated severity level using specific symbol values (e.g.,Debug, Traceback most recent call last) and configurable terms (e.g., INFO).

export class LevelTemplate extends TenXTemplate {

    constructor() {

        // check the template's symbol value starts with any of the configured 'levelTerms' values
        // use the map function to get the level value associated with a matching term

        LevelTemplate.level = TenXString.startsWith(
            this.symbolSequence("", "log", 30),           // capture the first 30 chars symbol values
            TenXMap.fromEntries(TenXEnv.get("levelTerms"))  // map the symbol value to a severity level
        );
    }
}

.get(field) ⇒ number | string | boolean

Returns the value of a target field of the current TenXTemplate instance.

Kind: static method of TenXTemplate Returns: number | string | boolean - Value of 'field'

Param Type Description
field string Field name whose value to return

.set(field, value) ⇒ number | string | boolean

Set a target value into the current template field.

This function is similar to Reflect.set.

Kind: static method of TenXTemplate Returns: number | string | boolean - the value set

Param Type Description
field string Field name to set
value number | string | boolean Value to assign to field

Example

export class MessageTemplate extends TenXTemplate {

    constructor() {

        if (GroupTemplate.isGroup) {

            TenXTemplate.set(
                TenXEnv.get("symbolMessageField", "symbolMessage"),
                this.symbolSequence(
                    TenXEnv.get("symbolContexts", "log,exec"),
                    TenXEnv.get("inputField"),
                    TenXEnv.get("symbolMaxLen", 0))
            );
        }
    }
}

TenXObject

Kind: global class
Extends: TenXBaseObject

Provide structured, reflective access to log/trace events read from input(s).

The 10x Engine transforms semi/unstructured log and trace events read from input(s) into well-defined, typed TenXObjects. Sub-classes of this class can declare constructors and functions that enrich, group and filter instances.

Custom Constructors

The 10x Engine can load multiple subclasses, in which case their constructors will be executed to initialize matching TenXObject instances in their order of loading.

TenXObject instances provides access to the following capabilities:

Variables

The categorizes each value within an instance's text into high-cardinality (e.g., IP, number, and GUID) and constant/low-cardinality (e.g., class, function, message) values through the vars and ipAddress fields and the token function.

Timestamps

Alphanumeric sequences convertible into a Unix Epoch values (e.g., Thursday, April 11, 2024 2:51:58 PM -> 1712847118000) are extracted and accessible via the timestamp array.

JSON/KV

Embedded fields are accessible as named members. For example, if text contains the following segments:
...{"price":1}... {"price":2}...price=3...price:4...' Price values are accessible as 'this.price' for the first element and 'this.price[N]' for zero-based access. The get function allows the name of the field to be specified dynamically.

TenXTemplate

The template and templateHash fields return a string representation of the instance's TenXTemplate.

Reflection

The source code/binary executable origin of constant and low cardinality values and context within their origin file (e.g., class, function, printout) are queryable via the symbol() and symbolSequence() functions.

Encoding

TenXObjects can be serialized like proto-buffers to reference (vs. repeat) information contained in their templates to reduce their footprint by > 50% via the encode function used by Optimizer modules.

Calculated Fields

New fields can be assigned to enrich each instance using any intrinsic/extracted fields, reflective functions, launch arguments and lookup files. The example below enriches TenXObjects with HTTP code values: 

export class HttpObject extends TenXObject {
  // Compute an HTTP error code field from the penultimate variable token
  // according to: https://httpd.apache.org/docs/2.4/logs.html schema.
  // For example, this will extract the '200' value into the 'code' field from:
  // 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326
  constructor() {
    // Grab the penultimate variable value
    var code =  TenXMath.parseInt(this.vars[-2]); 
    // Validate it's in the correct range       
    this.code = (code >= 200) && (code < 600) ? code : 0;
  }
}

Filtering

An TenXObject instance whose information is not required for output can be filtered via the drop function to save on storage and analytics costs.

Grouping

TenXObjects can form logical groups that can be aggregated, filtered and encoded as a single composite object (e.g., stack traces that comprise multiple lines to describe a single error) using the groupExpressions setting.

.groupSize : number

If the current instance is a logical group formed via groupExpressions returns the number of TenXObject within the group.

Kind: instance property of TenXObject

.extractorName : string

If the current object was extracted from a pattern match or JSON field using an input extractor, returns 'name' property of the extractor; otherwise an empty string. To learn more see input extractors

Kind: instance property of TenXObject

.extractorKey : string

If the object was extracted from a pattern match or JSON field using an input extractor, returns the 'key' property of the extractor (i.e., the name of the JSON field or regex match group); otherwise empty string. To learn more see input extractors

Kind: instance property of TenXObject

.source : string

Returns the source value assigned to this instance by its input source pattern

Kind: instance property of TenXObject

.timestamp : Array.<string>

An array of UNIX epoch values of timestamps parsed from the object's text. The length function can be used to query the number of elements in this array. To learn more about how timestamp values are extracted from events, see timestamps.

Kind: instance property of TenXObject

.ipAddress : Array.<string>

An array of string values of IPV4 parsed from the object's text. To geo-reference an entry in this array, see loadGeoIPDB().

Kind: instance property of TenXObject

.classes : Array.<string>

An array of symbol source /binary file names from which class tokens within the object's text originated. This value is only available if symbol files have been loaded. To learn more see symbols.

Kind: instance property of TenXObject

.text : string

The content of the event from which this instance was structured. This value may be read directly from an input or calculated on demand for expanded instances.

Kind: instance property of TenXObject

.utf8Size : number

The byte size of UTF8 encoding of text.

Kind: instance property of TenXObject

.fullText : string

A text value extracted from the input stream from which the object originated which encloses its text field. For example, if an object's text reflects a field extracted from a JSON object, The value of fullText will return the text of its entire enclosing JSON object.

Kind: instance property of TenXObject

.vars : Array.<string>

An array of variable sequences extracted from the object's text. The length function can be used to query the number of elements in this array.

Kind: instance property of TenXObject
Example

export class HttpObject extends TenXObject {
  // Compute an HTTP error code field from the penultimate entry in vars[]
  // according to: https://httpd.apache.org/docs/2.4/logs.html schema.
  // For example, this will extract the '200' value into the 'code' field from:
  // 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326
  constructor() {
    // Grab the penultimate variable value
    var code =  TenXMath.parseInt(this.vars[-2]); 
    // Validate it's in the correct range       
    this.code = (code >= 200) && (code < 600) ? code : 0;
  }
}

.isTemplate : boolean

Returns whether the current object is an TenXTemplate instance. To learn more see TenXTemplates

Kind: instance property of TenXObject

.isObject : boolean

Returns whether the current instance is an object and not a template or summary instance.

Kind: instance property of TenXObject

.isEncoded : boolean

Returns whether the current TenXObject was read from a compact input stream. To learn more see lossless compact

Kind: instance property of TenXObject

.isSummary : boolean

Returns whether the current object is a summary instance produced by an aggregator

Kind: instance property of TenXObject

.template : string

A sequence of all symbol and delimiter tokens from the object's text field. To learn more see TenXTemplates.

Kind: instance property of TenXObject

.templateHash : string

An alphanumeric encoded value of a 64bit hash of the current object's template field.

Kind: instance property of TenXObject

.timestamped : boolean

Return true if the instance is timestamped. Epoch values are accessible via the timestamp array.

Kind: instance property of TenXObject

.inputName : string

Returns the context in which the current object, template or summary was created.

At run time it may be needed to treat TenXObjects differently based on the input or aggregator from which they originated.

For example, to check if the current TenXObject was read from the 'Fluentd' input, as configured via its inputName, the following check can be made:

Kind: instance property of TenXObject
Example

class MyObject extends TenXObject {
   constructor() {

      if (this.inputName == "Fluentd") {
        TenXCounter.inc("Fluentd");
        if this.startsWith("DEBUG") this.drop();
     } 
   }
}

.drop([condition]) ⇒ boolean

Drops the current instance from the 10x pipeline.

This function allows for removing TenXObjects whose log/trace information is not required from aggregation and output.

Note: Instances are structured from log/trace events 'on-demand'; that is if an instance is dropped without first accessing its template members, significant performance gains can be achieved.

Kind: instance method of TenXObject
Returns: boolean - whether the current instance was successfully dropped.

Param Type Default Description
[condition] boolean true If truthy, the current object is dropped.

Example

export class FilteredObject extends TenXObject {
  constructor() {
    // Does not require the instance to undergo structuring
    this.drop(this.startsWith("TRACE"));

    // Requires the instance to undergo structuring based on the value of the penultimate 'vars' element.
    this.drop(this.vars[-2] != 200);
   }
 }

.outputType([types]) ⇒ string

Returns the type of output (e.g. event, metric, stream, file, stdout) the current instance is currently being emitted to.

This call can only be made within an output context to control whether to serialize the current instance to a target output.

For example, a Regulator module may set the 'printToOutput' function below into the outputStreamsFilter argument to write only timestamped TenXObjects to the console output.

Kind: instance method of TenXObject
Returns: string - type of the current output (e.g., 'stdout', 'file', 'event', 'metric', 'stream') or an empty string if the output type is not contained in the 'types' array.

Param Type Default Description
[types] Array.<string> [] An array value compared against the current output type. If the array does not contain the output's type an empty string is returned

Example

export class MyObject extends TenXObject { 
  get printOnlyTimestamped() {
    return this.outputType() == "stdout" ? this.timestamp : true;
  }
}

.outputPath() ⇒ string

Returns the 'path' value of an output the current instance is being serialized to.

This call can only be made within an output context to control whether to serialize the current instance to a target output.

For example, a Regulator module may set the outputStreamsFilter argument to the 'encodeToPrometheus' function below that to only encode TenXObjects extracted from a 'message' JSON field to a Prometheus destination.

Kind: instance method of TenXObject
Returns: string - Path of the active output (e.g. file path, log4j appender, micrometer registry,.. )
Example

export class MetricObject extends TenXObject {
  get encodeToPrometheus() {
    return TenXString.includes(this.outputPath(), "prometheus") ?
      this.extractorKey == "message" : false;
    }
 }

.encode([includeEnclosingText]) ⇒ string

An encoded value combining the object's templateHash, timestamp and vars fields.

This function generates an efficient representation of this object's variable state (i.e., values not contained in its shared TenXTemplate).

if includeEnclosingText is true, the return value of enclosed by the value of fullText which provides a representation of an TenXObject's encoded text within the context of the full event from which it was extracted. This mode enables Forwarder inputs to ship encoded TenXObjects to their target destination (e.g., Splunk, Elastic) with their full associated context (e.g., container id, name).

To learn more see lossless compact.

Kind: instance method of TenXObject Returns: string - a compact representation of this instance.

Param Type Default Description
includeEnclosingText boolean true whether to enclose the return encoded text

Example

For the following log event: 

{"log":"[INFO] 127.0.0.1:48899 - 63371 \"HINFO IN 3388893353626257077.643398171450697041. udp 56 false 512\" NXDOMAIN qr,rd,ra 56 0.123504685s\n","stream":"stdout","docker":{"container_id":"4c195cfdbf7e41f640631629970b9af2d8a1f40f63dcffd15edca84e2e2e497e"},"kubernetes":{"container_name":"coredns","namespace_name":"kube-system","pod_name":"coredns-7db6d8ff4d-pddxj","container_image":"registry.k8s.io/coredns/coredns:v1.11.1","container_image_id":"docker-pullable://registry.k8s.io/coredns/coredns@sha256:1eeb4c7316bacb1d4c8ead65571cd92dd21e27359f0d4917f1a5822a73b75db1","pod_id":"38b91d65-ba47-4d0f-a689-711056955842","pod_ip":"10.244.0.99","host":"minikube","labels":{"k8s-app":"kube-dns","pod-template-hash":"7db6d8ff4d"}},"tenx_tag":"kubernetes.var.log.containers.coredns-7db6d8ff4d-pddxj_kube-system_coredns-4c195cfdbf7e41f640631629970b9af2d8a1f40f63dcffd15edca84e2e2e497e.log"}

The following call for an TenXObject extracted from the event's log JSON field:

TenXConsole.log(this.encode(true));

Will print:

{"log":"~-Kw0UHgdH_9,127,0,1,48899,63371,3388893353626257077,643398171450697041,56,512,123504685s","stream":"stdout","docker":{"container_id":"4c195cfdbf7e41f640631629970b9af2d8a1f40f63dcffd15edca84e2e2e497e"},"kubernetes":{"container_name":"coredns","namespace_name":"kube-system","pod_name":"coredns-7db6d8ff4d-pddxj","container_image":"registry.k8s.io/coredns/coredns:v1.11.1","container_image_id":"docker-pullable://registry.k8s.io/coredns/coredns@sha256:1eeb4c7316bacb1d4c8ead65571cd92dd21e27359f0d4917f1a5822a73b75db1","pod_id":"38b91d65-ba47-4d0f-a689-711056955842","pod_ip":"10.244.0.99","host":"minikube","labels":{"k8s-app":"kube-dns","pod-template-hash":"7db6d8ff4d"}},"tenx_tag":"kubernetes.var.log.containers.coredns-7db6d8ff4d-pddxj_kube-system_coredns-4c195cfdbf7e41f640631629970b9af2d8a1f40f63dcffd15edca84e2e2e497e.log"}

Whereas a call to: this.encode(false) will drop portions of the event not encoded and return: 

~-Kw0UHgdH_9,127,0,1,48899,63371,3388893353626257077,643398171450697041,56,512,123504685s

.symbol(type, symbolName, [index]) ⇒ string

Returns the N value of a symbol token sequence matching a target criteria

This function selects a certain set of symbol and delimiter tokens from the object's template based on their context within the source code/binary file from which they originated.

Kind: instance method of TenXObject
Returns: string - the symbol and delimiter token sequence selected from the object's Template fields matching the selected criteria. If no matching sequence is found or symbol files. have not been loaded, an empty value is returned.

Param Type Default Description
type string Type of symbol that is being searched for. Supported values: PACKAGE, CLASS, METHOD, LOG, ENUM, CONST, TEXT (case insensitive). To select all symbol types, pass an empty string.
symbolName string A specific symbol name to look for. For example, look for the values of an enum named "status", that value could be specified to limit results to symbol tokens whose literals are defined in the "status" enum
[index] number 0 index of the selected symbol token matching the type and symbolName parameters. To choose the second symbol sequence, use 1; for last, use -1.

Example

To capture the symbol tokens that originated from an enum named "Status" for the following object: 17/06/09 20:51:58 INFO spark.CacheManager: Partition rdd_2876_26 not found, computing Status ENABLED

this.status = this.symbol("ENUM", "Status"); //capture the 'ENABLED value above

.symbolSequence(symbolContexts,fieldName,maxLen) ⇒ string

Returns a sequence of symbol tokens of a specified type.

This function selects a the longest set of symbol and delimiter tokens from the object's TenXTemplate based on their context within the source code/binary file from which they originated.

To capture a symbol sequence for the following event:

17/06/24 20:51:58 INFO spark.CacheManager: Partition rdd_2876_26 not found, computing Status ENABLED

The following call can be used:

this.message = symbolSequence("log,class,exec"); // = 'Partition__not_found_computing_Status'

The symbolContext argument controls the symbol contexts to search for; if the first type does not yield a result, the next one is tried etc.

Supported values: package, class, method, log, enum, const, text, exec, any (case insensitive).

Specifying any produces Prometheus-compliant metric name comprised of symbol tokens from the current instance's template field.

The field argument can limit the sequence search to a target extracted field. For example, specifying an argument value of: "message" will search for matching symbols only in the object's message JSON/KV field (if exists).

This function queries the template field and removes all characters that cannot be used as part of a metric name (e.g., variables, delimiters), as well as any timestamp patterns.

The resulting string can be used within the context of an aggregator. to send aggregate information such as volume, bytes, counter information that relates to all TenXObject instances sharing the same metric name (which will usually describe different instances of the same logical event).

For example, the following event may have the following value as its text field:

{"timestamp": 1631753487.281258, "severity": "INFO", "name": "192.158.1.38", "message": "A request to send order confirmation email was sent"}

Its template field will be calculated as:

{"timestamp": $(epochNano), "severity": "INFO", "name": "$.$.$.$", "message": "A request to send order confirmation email sent"}"

This value cannot be used as a valid metric name, as described in Metric naming.

Instead, this function will return the following valid metric name:

timestamp_severity_INFO_name_message_request_to_send_order_confirmation_email_sent

This return value can be used to periodically report the volume of email using an aggregator and time-series output.

Kind: instance method of TenXObject
Returns: string - The symbol sequence selected from the object's Template fields matching the selected criteria. If no matching sequence is found or symbol path. have not been loaded, an empty value is returned.

Param Type Default Description
symbolContext string Comma delimited symbol types to search for. Supported values: PACKAGE, CLASS, METHOD, LOG, ENUM, CONST, TEXT, EXEC, ANY (case insensitive).
fieldName string name of extracted JSON/KV field name (e.g., 'log','message') to scan for symbol tokens. If not specified, scans the text field.
maxLen number Max length of result string, 0 for unlimited.

.symbolOrigin(symbolContext) ⇒ string

Returns a the source code/binary origin of 'symbol' tokens of a specified type.

This function selects a the origin (i.e. the source code or binary executable which emitted) the longest set of symbol and delimiter tokens from the object's TenXTemplate.

To capture the origin value for the following event: 

17/06/24 20:51:58 INFO spark.CacheManager: Partition rdd_2876_26 not found, computing Status ENABLED

The following call can be used:

this.origin = symbolOrigin("log,class,exec"); // CacheManager.scala'

The 'symbolContext' argument controls the symbol contexts to search for; if the first type does not yield a result, the next one is tried etc.

Supported values: PACKAGE, CLASS, METHOD, LOG, ENUM, CONST, TEXT, EXEC (case insensitive).

A symbol context value may be preceded by [fieldName]: to limit the sequence search to a target extracted field. For example, for: "log:message,class", will search for symbols originating from code log statements (e.g., "log.error("...")" only in the object's "message" field (if it exists). When searching for "class" symbols, the entire object is searched.

Kind: instance method of TenXObject
Returns: string - The symbol sequence and/or origin selected from the object's Template fields matching the selected criteria. If no matching sequence is found or symbol path. have not been loaded, an empty value is returned.

Param Type Default Description
symbolContext string Types of symbols to search for. Supported values: PACKAGE, CLASS, METHOD, LOG, ENUM, CONST, TEXT, EXEC (case insensitive).

.isNewTemplate() ⇒ boolean

Returns whether the object's TenXTemplate was loaded from disk, an input stream or generated at runtime on the fly.

This function is commonly used by output streams to determine whether to encode the object's template to output, assuming pre-existing templates do not need to be shipped to output.

Kind: instance method of TenXObject
Returns: boolean - True if the object's template was generated on the fly.

.get(field, [index]) ⇒ number | string | boolean

Returns the value of a target intrinsic, extracted or calculated field of the current instance.

This function produces and returns a JSON object listing all intrinsic (i.e., built into all objects), extracted (i.e., JSON and Key/Value fields automatically extracted from the object's text field) and encoded (i.e., assigned into the object through an event action) fields.

Kind: instance method of TenXObject
Returns: number | string | boolean - Value of 'field' at position 'index'

Param Type Default Description
field string Field name to whose value to return
[index] number 0 Index of the element if 'field' is an array

Example

export class MyObject extends TenXObject {
  // filter instances for which the value of 'myField'
  // is different than the 'myValue' launch argument  
  constructor() {
    this.drop(this.get(TenXEnv.get("myField") != TenXEnv.get("myValue"));
  }
}

.set(field, value) ⇒ boolean

Set a target value into a calculated field

This function is similar to Reflect.set.

Note that intrinsic fields (i.e., fields declared by this class) cannot be set.

Calls to this function can only be made from within an TenXObject's constructor.

Kind: instance method of TenXObject
Returns: boolean - return true if the value was set

Param Type Description
field string Field name to set
value number | string | boolean to assign to field

Example

export class MyGeoObject extends TenXObject {
  // Assign a geo-ref lookup value (e.g., country, region) specified by a launch argument to a matching field
  constructor() {
    this.set(TenXEnv.get("geoField"), TenXLookup.get("geoIP"), this.ipAddress, TenXEnv.get("geoField"));
  }
}

.joinFields(delimiter, ...fields) ⇒ string

Returns a new String composed of evaluated TenXObject fields joined together with the specified delimiter or as a JSON object containing the field name/value pairs.

Kind: instance method of TenXObject
Returns: string - a String composed of the evaluated fields separated by the delimiter. If an empty delimiter is passed, the field values are formatted and escaped as JSON values of an array. If only one argument is passed, the values of the argument are treated as the array of fields to join and the delimiter is assumed to be empty (formatting as JSON).

Param Type Description
delimiter string the delimiter that separates each field value (should be one character long)
...fields Array.<string> the current TenXObject's intrinsic/extracted/calculated fields to join.

.length() ⇒ number

Invokes length, passing text as the value of 'str'.

Kind: instance method of TenXObject

.includes() ⇒ boolean

Invokes includes, passing text as the value of 'str'.

Kind: instance method of TenXObject

.startsWith() ⇒ boolean

Invokes startsWith, passing text as the value of 'str'.

Kind: instance method of TenXObject

.endsWith() ⇒ boolean

Invokes endsWith, passing text as the value of 'str'.

Kind: instance method of TenXObject

.indexOf() ⇒ number

Invokes indexOf, passing text as the value of 'str'.

Kind: instance method of TenXObject

.lastIndexOf() ⇒ number

Invokes lastIndexOf, passing text as the value of 'str'.

Kind: instance method of TenXObject

.toLowerCase() ⇒ string

Invokes toLowerCase, passing text as the value of 'str'.

Kind: instance method of TenXObject

.toUpperCase() ⇒ string

Invokes toUpperCase, passing text as the value of 'str'.

Kind: instance method of TenXObject

.matchAll() ⇒ Array.<string>

Invokes matchAll, passing text as the value of 'str'.

Kind: instance method of TenXObject

.match() ⇒ string

Invokes match, passing text as the value of 'str'.

Kind: instance method of TenXObject

.replace() ⇒ string

Invokes replace, passing text as the value of 'str'

Kind: instance method of TenXObject

.toString() ⇒ string

Returns a JSON representation of the current instance's intrinsic, extracted, and calculated fields.

This function returns a JSON object listing all intrinsic (i.e., built into all TenXObjects), extracted (i.e., JSON/KV entries extracted from text) and calculated (i.e., assigned into the instance within its constructor) fields.

This function is useful for examining the state of a specific instance, especially in conjunction with the log() function.

To print the JSON description of every object whose text field contains the 'target' variable to console:

Kind: instance method of TenXObject
Returns: string - the object's JSON representation
Example

if this.includes(TenXEnv.get("target")) TenXConsole.log(this.toString());

.token([tokenOffset], [tokenTypes], [from]) ⇒ string

Returns the value of specific tokens within the current TenXObject.

TenXObjects are comprised of tokens, which are alpha-numeric values categorized as:

  • symbol: values found in the pipeline's symbol library.
  • delimiter: single length token delimiters (e.g. ',;<>.').
  • variable: alpha-numeric values that are neither delimiter nor symbols.

This function provides a mechanism for querying the current TenXObject's token structure.

Kind: instance method of TenXObject
Returns: string - Value of the token of type 'tokenTypes', having skipped 'tokenOffset' tokens from the 'startIndex' start position

Param Type Default Description
[tokenOffset] number 0 Number of tokens within the object's tokens array to begin searching from.
[tokenTypes] number variable Comma delimited string containing the token type(s) to search for. Available values: [symbol, variable, delimiter].
[from] number | string 0 Number: Position within the target string to begin searching for the target token. If positive, the zero-based n character is used. If negative, the (length - n - 1) is used if the index is out of bounds, it is ignored and 0 is used.

Example

The following call can be made to look for the second variable in the current TenXObject:

this.status = this.token(2, "variable");

.tokenSize() ⇒ number

Returns the number of tokens in the current TenXObject's text field. To learn more about tokens, see:token delimiters

Kind: instance method of TenXObject
Returns: number - number of tokens in the current object

.timestampStart(index) ⇒ number

Returns the index of within the object's text where the Nth timestamp sequence begins (inclusive).

To learn more see timestamp extraction.

Kind: instance method of TenXObject
Returns: number - zero-based index of the start position (inclusive), -1 if not found

Param Type Description
index number Index within the timestamp array to use. A negative value can be provided to search from the end of the timestamp array

.timestampEnd(index) ⇒ number

Returns the index of within the object's text where the Nth timestamp sequence ends (exclusive).

To learn more see timestamp extraction.

Kind: instance method of TenXObject
Returns: number - zero-based index of the end position (exclusive), -1 if not found

Param Type Description
index number Index within the timestamp array to use. A negative value can be provided to search from the end of the timestamp array

.timestampFormat([timestampIndex]) ⇒ string

Returns the timestamp pattern for the specified timestamp.

For example, for an event whose timestamp is equal to: '2021-09-16T02:33:05.289552Z', the return value would be: yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'

To learn more see timestamp extraction.

Kind: instance method of TenXObject
Returns: string - Timestamp pattern if found, otherwise an empty value

Param Type Default Description
[timestampIndex] number 0 Index of the desired timestamp within the object's timestamp array.

TenXSummary

Kind: global class
Extends: TenXBaseObject

Access aggregate values of TenXObjects which share a target set of field values.

Aggregators are defined in a similar way to "GROUP BY" SQL statements which groups table rows based on specific columns.

Once the number of aggregated instances has exceeded a target threshold or interval, the aggregator creates an instance of TenXSummary whose aggregated values are accessible as named members as well as via the intrinsic fields defined below.

Below is a snippet that demonstrates initializing TenXSummary instances using HTTP lookups.

export class HttpSummary extends TenXSummary {
  constructor() {
   if (this.code) this.message = TenXLookup.get("http", this.code);
  }
}

.summaryVolume : number

The number of TenXObjects whose values have been aggregated into this summary instance.

Kind: instance property of TenXSummary

.summaryBytes : number

The accumulative number of bytes in the values of text fields of objects whose values have been incorporated into this summary instance.

Kind: instance property of TenXSummary

.summaryValues : Array.<string>

Array of values by which TenXObjects have been grouped into this summary instance.

Kind: instance property of TenXSummary

.summaryValuesHash : string

A hash value of the summaryValues field used to more concise representation of the values by which objects have been grouped into this summary.

Kind: instance property of TenXSummary

.summaryTotals : Array.<number>

Sum values of the aggregatorTotalFields value of TenXObjects aggregated into this instance. This value commonly specifies metric counter values when writing TenXSummaries to time-series outputs.

Kind: instance property of TenXSummary

.text : string

The content of the event from which this instance was structured. This value may be read directly from an input or calculated on demand for expanded instances.

Kind: instance property of TenXSummary

.utf8Size : number

The byte size of UTF8 encoding of text.

Kind: instance property of TenXSummary

.fullText : string

A text value extracted from the input stream from which the object originated which encloses its text field. For example, if an object's text reflects a field extracted from a JSON object, The value of fullText will return the text of its entire enclosing JSON object.

Kind: instance property of TenXSummary

.vars : Array.<string>

An array of variable sequences extracted from the object's text. The length function can be used to query the number of elements in this array.

Kind: instance property of TenXSummary
Example

export class HttpObject extends TenXObject {
  // Compute an HTTP error code field from the penultimate entry in vars[]
  // according to: https://httpd.apache.org/docs/2.4/logs.html schema.
  // For example, this will extract the '200' value into the 'code' field from:
  // 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326
  constructor() {
    // Grab the penultimate variable value
    var code =  TenXMath.parseInt(this.vars[-2]); 
    // Validate it's in the correct range       
    this.code = (code >= 200) && (code < 600) ? code : 0;
  }
}

.isTemplate : boolean

Returns whether the current object is an TenXTemplate instance. To learn more see TenXTemplates

Kind: instance property of TenXSummary

.isObject : boolean

Returns whether the current instance is an object and not a template or summary instance.

Kind: instance property of TenXSummary

.isEncoded : boolean

Returns whether the current TenXObject was read from a compact input stream. To learn more see TenXTemplates

Kind: instance property of TenXSummary

.isSummary : boolean

Returns whether the current object is a summary instance produced by an aggregator

Kind: instance property of TenXSummary

.template : string

A sequence of all symbol and delimiter tokens from the object's text field. To learn more see TenXTemplates.

Kind: instance property of TenXSummary

.templateHash : string

An alphanumeric encoded value of a 64bit hash of the current object's template field.

Kind: instance property of TenXSummary

.timestamped : boolean

Return true if length of timestamp is greater than 0

Kind: instance property of TenXSummary

.inputName : string

Returns the context in which the current object, template or summary was created.

At run time it may be needed to treat TenXObjects differently based on the input or aggregator from which they originated.

For example, to check if the current TenXObject was read from the 'Fluentd' input, as configured via its inputName, the following check can be made:

Kind: instance property of TenXSummary
Example

class MyObject extends TenXObject {
   constructor() {

      if (this.inputName == "Fluentd") {
        TenXCounter.inc("Fluentd");
        if this.startsWith("DEBUG") this.drop();
     } 
   }
}

.get(field, [index]) ⇒ number | string | boolean

Returns the value of a target intrinsic, extracted or calculated field of the current instance.

This function produces and returns a JSON object listing all intrinsic (i.e., built into all objects), extracted (i.e., JSON and Key/Value fields automatically extracted from the object's text field) and encoded (i.e., assigned into the object through an event action) fields.

Kind: instance method of TenXSummary
Returns: number | string | boolean - Value of 'field' at position 'index'

Param Type Default Description
field string Field name to whose value to return
[index] number 0 Index of the element if 'field' is an array

Example

export class MyObject extends TenXObject {
  // filter instances for which the value of 'myField'
  // is different than the 'myValue' launch argument  
  constructor() {
    this.drop(this.get(TenXEnv.get("myField") != TenXEnv.get("myValue"));
  }
}

.set(field, value) ⇒ boolean

Set a target value into a calculated field

This function is similar to Reflect.set.

Note that intrinsic fields (i.e., fields declared by this class) cannot be set.

Calls to this function can only be made from within an TenXObject's constructor.

Kind: instance method of TenXSummary
Returns: boolean - return true if the value was set

Param Type Description
field string Field name to set
value number | string | boolean to assign to field

Example

export class MyGeoObject extends TenXObject {
  // Assign a geo-ref lookup value (e.g., country, region) specified by a launch argument to a matching field
  constructor() {
    this.set(TenXEnv.get("geoField"), TenXLookup.get("geoIP"), this.ipAddress, TenXEnv.get("geoField"));
  }
}

.joinFields(delimiter, ...fields) ⇒ string

Returns a new String composed of evaluated TenXObject fields joined together with the specified delimiter or as a JSON object containing the field name/value pairs.

Kind: instance method of TenXSummary
Returns: string - a String composed of the evaluated fields separated by the delimiter. If an empty delimiter is passed, the field values are formatted and escaped as JSON values of an array. If only one argument is passed, the values of the argument are treated as the array of fields to join and the delimiter is assumed to be empty (formatting as JSON).

Param Type Description
delimiter string the delimiter that separates each field value (should be one character long)
...fields Array.<string> the current TenXObject's intrinsic/extracted/calculated fields to join.

.length() ⇒ number

Invokes length, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.includes() ⇒ boolean

Invokes includes, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.startsWith() ⇒ boolean

Invokes startsWith, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.endsWith() ⇒ boolean

Invokes endsWith, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.indexOf() ⇒ number

Invokes indexOf, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.lastIndexOf() ⇒ number

Invokes lastIndexOf, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.toLowerCase() ⇒ string

Invokes toLowerCase, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.toUpperCase() ⇒ string

Invokes toUpperCase, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.matchAll() ⇒ Array.<string>

Invokes matchAll, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.match() ⇒ string

Invokes match, passing text as the value of 'str'.

Kind: instance method of TenXSummary

.replace() ⇒ string

Invokes replace, passing text as the value of 'str'

Kind: instance method of TenXSummary

.toString() ⇒ string

Returns a JSON representation of the current instance's intrinsic, extracted, and calculated fields.

This function returns a JSON object listing all intrinsic (i.e., built into all TenXObjects), extracted (i.e., JSON/KV entries extracted from text) and calculated (i.e., assigned into the instance within its constructor) fields.

This function is useful for examining the state of a specific instance, especially in conjunction with the log() function.

To print the JSON description of every object whose text field contains the 'target' variable to console:

Kind: instance method of TenXSummary
Returns: string - the object's JSON representation
Example

if this.includes(TenXEnv.get("target")) TenXConsole.log(this.toString());

.token([tokenOffset], [tokenTypes], [from]) ⇒ string

Returns the value of specific tokens within the current TenXObject.

TenXObjects are comprised of tokens, which are alpha-numeric values categorized as:

  • symbol: values found in the pipeline's symbol library.
  • delimiter: single length token delimiters (e.g. ',;<>.').
  • variable: alpha-numeric values that are neither delimiter nor symbols.

This function provides a mechanism for querying the current TenXObject's token structure.

Kind: instance method of TenXSummary
Returns: string - Value of the token of type 'tokenTypes', having skipped 'tokenOffset' tokens from the 'startIndex' start position

Param Type Default Description
[tokenOffset] number 0 Number of tokens within the object's tokens array to begin searching from.
[tokenTypes] number variable Comma delimited string containing the token type(s) to search for. Available values: [symbol, variable, delimiter].
[from] number | string 0 Number: Position within the target string to begin searching for the target token. If positive, the zero-based n character is used. If negative, the (length - n - 1) is used if the index is out of bounds, it is ignored and 0 is used.

Example

The following call can be made to look for the second variable in the current TenXObject:

this.status = this.token(2, "variable");

.tokenSize() ⇒ number

Returns the number of tokens in the current TenXObject's text field. To learn more about tokens, see:token delimiters

Kind: instance method of TenXSummary
Returns: number - number of tokens in the current object

.timestampStart(index) ⇒ number

Returns the index of within the object's text where the Nth timestamp sequence begins (inclusive).

To learn more see timestamp extraction.

Kind: instance method of TenXSummary
Returns: number - zero-based index of the start position (inclusive), -1 if not found

Param Type Description
index number Index within the timestamp array to use. A negative value can be provided to search from the end of the timestamp array

.timestampEnd(index) ⇒ number

Returns the index of within the object's text where the Nth timestamp sequence ends (exclusive).

To learn more see timestamp extraction.

Kind: instance method of TenXSummary
Returns: number - zero-based index of the end position (exclusive), -1 if not found

Param Type Description
index number Index within the timestamp array to use. A negative value can be provided to search from the end of the timestamp array

.timestampFormat([timestampIndex]) ⇒ string

Returns the timestamp pattern for the specified timestamp.

For example, for an event whose timestamp is equal to: '2021-09-16T02:33:05.289552Z', the return value would be: yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'

To learn more see timestamp extraction.

Kind: instance method of TenXSummary
Returns: string - Timestamp pattern if found, otherwise an empty value

Param Type Default Description
[timestampIndex] number 0 Index of the desired timestamp within the object's timestamp array.

TenXCollection

Base class for collection utilities, providing shared methods for length and access.

Kind: global class

TenXCollection.length(collection) ⇒ number

Returns the length of a collection (array or map).

Kind: static method of TenXCollection
Returns: number - the number of elements in the collection

Param Type Description
collection Array.<(number|string)> | Object the target collection

TenXCollection.get(collection, key, [defValue]) ⇒

Returns an element from the collection by key or index.

For arrays, 'key' is treated as index (number). For maps, 'key' is the string key.

Kind: static method of TenXCollection
Returns: the element at the specified key or index. If out of bounds or not found, returns defValue if provided, otherwise an empty value is returned

Param Type Description
collection Array.<(number|string)> | Object the collection from which to retrieve the target element
key number | string Key or index in collection. For arrays: positive/negative index (Python-style for negative). For maps: string key.
[defValue] * Optional default value to return if the key/index is out of bounds or not found. If not provided, an empty value is returned.

Example

export class CollectionExample extends TenXObject {
  constructor() {
    let myArray = ["apple", "banana", "cherry"];
    let myMap = {"fruit": "apple", "color": "red"};

    // Array access with default values
    let first = TenXArray.get(myArray, 0, "unknown");        // returns "apple"
    let outOfBounds = TenXArray.get(myArray, 10, "unknown");  // returns "unknown"

    // Map access with default values  
    let fruit = TenXMap.get(myMap, "fruit", "unknown");       // returns "apple"
    let missing = TenXMap.get(myMap, "missing", "unknown");   // returns "unknown"
  }
}

TenXCollection.includes(collection, term) ⇒ boolean | string | *

Tests if a target collection contains the specified term.

Kind: static method of TenXCollection
Returns: boolean | string | * - Returns true if the collection contains the term. If term is an array, returns the first item from term that is contained within str (or any element in str if an array, or any key in str if a map), or undefined if no match. If term is a map generated by TenXMap.fromEntries, returns the value associated with the first key from term that is contained within the collection, or undefined if no match.

Param Type Description
collection Object array or map to search in.
term string | Array. | Object Term to search for. If term is a string, checks if str (or any element/key) contains it. If term is an array, returns the first item from term contained in str (or any element/key). If term is a map generated by TenXMap.fromEntries, returns the value associated with the first key contained in str (or any element/key).

TenXArray ⇐ TenXCollection

Query array elements, length, and search.

Kind: global class
Extends: TenXCollection

TenXArray.indexOf(list, value) ⇒ number

Returns the index of the first occurrence of 'value' in 'list'.

Kind: static method of TenXArray
Returns: number - the index of the first occurrence, or -1 if not found

Param Type Description
list Array.<(number|string)> the array to search in
value number | string the value to search for

TenXMap ⇐ TenXCollection

Utilities for map (object) operations.

Kind: global class
Extends: TenXCollection

TenXMap.fromEntries(list, [separator], [keyName], [valueName]) ⇒ Object

Returns a map object parsed from a list of values.

Kind: static method of TenXMap
Returns: Object - A map object parsed from the values array.

Param Type Default Description
list Array.<string> The array of values from which to parse the result map (e.g., a=b,c=d,..).
[separator] string "=" String to use to separate keys and values in the list. For separator =, returns: {"a":"b","c":"d"}.
[keyName] string "\"\"" Name of key field name. For example, for keyName = myKey and valueName = myVal, returns: [{"myKey":"a","myVal":"b"},{"myKey":"c","myVal":"d"}].
[valueName] string "\"\"" Name of value field name (e.g., myVal). Required if keyName is specified.

Example

class LevelTemplate extends TenXTemplate {
  constructor() {
    // Check the template's symbol value starts with any of the configured 'levelTerms' values
    // Use the fromEntries function to get the level value associated with a matching term
    let levelTerm = TenXString.startsWith(
      this.symbolSequence("", TenXEnv.get("inputField"), 30),
      TenXMap.fromEntries(TenXEnv.get("levelTerms"))
    );
    // If no match, try inferring from the template's timestamp pattern using configured 'levelTimestampPatterns' values
    if (!levelTerm) {
      levelTerm = TenXString.startsWith(
        this.timestampFormat(),
        TenXMap.fromEntries(TenXEnv.get("levelTimestampPatterns"))
      );
    }
  }
}

TenXString

Search, pattern-match and join string values.

Kind: global class

TenXString.length(list) ⇒ number

returns the length of a string value in a local variable or object field

Kind: static method of TenXString
Returns: number - the number of characters in the string

Param Type Description
list string the target string

TenXString.split(str, delimiter, [limit]) ⇒ Array.<string>

Splits the 'str' string around matches of delimiter.

The array returned by this method contains each substring of this string that is terminated by another substring that matches the given delimiter. The substrings in the array are in the order in which they occur in this string. If the expression does not match any part of the input, then the resulting array has just one element, namely str.

The limit parameter controls the number of times the pattern is applied and therefore affects the length of the resulting array.

If the limit is positive, then the pattern will be applied at most limit - 1 times, the array's length will be no greater than the limit, and the array's last entry will contain all input beyond the last matched delimiter.

If the limit is zero, then the pattern will be applied as many times as possible, the array can have any length and trailing empty strings will be discarded.

If the limit is negative, then the pattern will be applied as many times as possible, and the array can be any length.

Kind: static method of TenXString
Returns: Array.<string> - Array of strings computed by splitting string around matches of the delimiter

Param Type Description
str string String to split
delimiter string Delimiting string
[limit] number Result threshold, as described above

TenXString.includes(str, term) ⇒ boolean | string | *

Tests if a target string, array of strings, or map contains the specified term.

Kind: static method of TenXString
Returns: boolean | string | * - Returns true if term is a string and str (or any element in str if an array, or any key in str if a map) contains it. If term is an array, returns the first item from term that is contained within str (or any element in str if an array, or any key in str if a map), or undefined if no match. If term is a map generated by TenXMap.fromEntries, returns the value associated with the first key from term that is contained within str (or any element in str if an array, or any key in str if a map), or undefined if no match.

Param Type Description
str string | Array. | Object String, array of strings, or map to search in.
term string | Array. | Object Term to search for. If term is a string, checks if str (or any element/key) contains it. If term is an array, returns the first item from term contained in str (or any element/key). If term is a map generated by TenXMap.fromEntries, returns the value associated with the first key contained in str (or any element/key).

TenXString.startsWith(str, prefix) ⇒ boolean | string | *

Tests if a target string starts with the specified prefix.

Kind: static method of TenXString
Returns: boolean | string | * - Returns true if prefix is a string and str starts with it, or if prefix is an empty string or equal to str. If prefix is an array, returns the matching item or undefined if no match. If prefix is a map generated by TenXMap.fromEntries, returns the value corresponding to the matching key or undefined if no match.

Param Type Description
str string String to search in.
prefix string | Array. | Object Prefix to match. If prefix is a string, checks if str starts with it. If prefix is an array, returns the first matching item from the array if str starts with it. If prefix is a map generated by TenXMap.fromEntries, returns the value from the map corresponding to the key that str starts with.

TenXString.endsWith(str, postfix) ⇒ boolean | string | *

Tests if a target string ends with the specified postfix.

Kind: static method of TenXString
Returns: boolean | string | * - Returns true if postfix is a string and str ends with it, or if postfix is an empty string or equal to str. If postfix is an array, returns the matching item or undefined if no match. If postfix is a map generated by TenXMap.fromEntries, returns the value from the map corresponding to the key that str ends with. |

Param Type Description
str string String to search in.
postfix string | Array. | Object Postfix to match. If postfix is a string, checks if str ends with it. If postfix is an array, returns the first matching item from the array if str ends with it. If postfix is a map generated by TenXMap.fromEntries, returns the value from the map corresponding to the key that str ends with.

TenXString.indexOf(str, term, fromIndex) ⇒ number

Returns the index within the search string of the first occurrence of the specified substring, starting at the specified index.

Kind: static method of TenXString
Returns: number - the index of the first occurrence of the specified substring or array, starting at the specified index, or -1 if there is no such occurrence.

Param Type Description
str string | Array.<string> Substring or array to search in.
term string Substring to search for.
fromIndex number Index from which to start the search if 'str' is a string

TenXString.lastIndexOf(str, term, fromIndex) ⇒ number

Returns the index within str of the last occurrence of the specified substring, searching backward starting at the specified index.

Kind: static method of TenXString
Returns: number - the index of the last occurrence of the specified substring, searching backward from the specified index, or -1 if there is no such occurrence.

Param Type Description
str string String to search in.
term string Substring to search for.
fromIndex number Index in str to start the search from.

TenXString.toLowerCase(str) ⇒ string

Converts all of the characters in str to lowercase.

Kind: static method of TenXString
Returns: string - String, converted to lowercase.

Param Type Description
str string String to convert.

TenXString.toUpperCase(str) ⇒ string

Converts all of the characters in str to uppercase.

Kind: static method of TenXString
Returns: string - String, converted to uppercase.

Param Type Description
str string String to convert.

TenXString.matchAll(str, pattern) ⇒ Array.<string>

Returns a list of matches of the specified pattern within str.

Kind: static method of TenXString
Returns: Array.<string> - List of matches within str. If no match is found, an empty array is returned

Param Type Description
str string String to search in.
pattern string Regex pattern to match

TenXString.match(str, pattern) ⇒ string

Returns the first matches of the specified pattern within str.

Kind: static method of TenXString
Returns: string - First string segment matching the pattern. If no match is found, an empty string is returned

Param Type Description
str string String to search in.
pattern string Regex pattern to match

TenXString.replace(str, target, replacement) ⇒ string

Replaces each substring in str that matches the literal target sequence with the specified literal replacement sequence.

The replacement proceeds from the beginning of the string to the end for For example, replacing "aa" with "b" in the string "aaa" will result in "ba" rather than "ab".

Kind: static method of TenXString
Returns: string - The resulting string

Param Type Description
str string The string to search in.
target string The sequence of char values to be replaced
replacement string The replacement sequence of char values

TenXString.substring(str, beginIndex, endIndex) ⇒ string

Returns a string that is a substring of 'str'.

The substring begins at the specified beginIndex and extends to the character at index endIndex - 1. Thus, the length of the substring is endIndex-beginIndex.

Kind: static method of TenXString
Returns: string - Specified substring.

Param Type Description
str string String to search in.
beginIndex number Beginning index, inclusive. If negative, length(str) + beginIndex is used. If not provided, 0 is used
endIndex number Ending index, exclusive. If negative, length(str) + endIndex is used. If not provided, length(str) is used

TenXString.join(delimiter, ...elements) ⇒ string

Returns a new String composed of elements joined together with the specified delimiter.

Kind: static method of TenXString
Returns: string - String composed of the elements separated by the delimiter

Param Type Description
delimiter string Delimiter that separates each element
...elements Array.<string> Elements to join together.

TenXString.concat(...elements) ⇒ string

Returns a new String composed of elements joined together.

Kind: static method of TenXString
Returns: string - String composed of the elements

Param Type Description
...elements Array.<string> Elements to join together.

TenXString.stringify(...values) ⇒ string

Returns a JSON representation of an array of input values.

If 'values' is provided, this function returns a JSON object of the values passed similar to 
  [JSON.stringify()](https://www.w3schools.com/js/js_json_stringify.asp)

Kind: static method of TenXString
Returns: string - JSON representation of the 'values' array

Param Type Description
...values Array.<Object> Even-numbered array of values to format

Example

this.print(this.stringify(
  "now", TenXDate.now(), 
  "str", "hello" + " world")
);

 will print: {"now": 1661782307673, "str": "hello world"}

TenXString.jsonPath(json, path) ⇒ *

Applies a JsonPath query to a JSON string and returns the result.

This function parses the JSON string and applies the JsonPath query expression to extract specific values or data structures from the JSON object. JsonPath is a query language for JSON, similar to XPath for XML.

Kind: static method of TenXString
Returns: * - The result of the JsonPath query. Can be a single value, an array of values, or undefined if no match is found.

Param Type Description
json string The JSON string to query
path string The JsonPath expression to apply

Example

// Given JSON: {"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}
var jsonStr = '{"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}';

// Extract all user names:
var names = TenXString.jsonPath(jsonStr, "$.users[*].name");  // returns ["Alice", "Bob"]

// Extract first user's age:
var age = TenXString.jsonPath(jsonStr, "$.users[0].age");    // returns 30

// Extract users with age > 27:
var oldUsers = TenXString.jsonPath(jsonStr, "$.users[?(@.age > 27)]");

TenXLookup

Load and query the values of text lookup tables (.csv, .tsv) and geoIP DB files (.mmdb).

Kind: global class

.load(lookup, [extractColumns], ...columns) ⇒ number

Load a comma/tab-delimited text lookup table into memory.

An event may hold a value in a field that may need to be translated to another using a key/value map for a specific action to be taken, or for the event to be correctly encoded for output.

This function scans a text file containing comma/tab delimited rows to create an efficient in-memory table that can be used to locate specific rows based on a selected column value and retrieve the value of a specified value column.

For example, the "example.csv" file can be loaded into memory in the following manner:

TenXLookup.load("example.csv", true, "Model", "Year", "Maker")

Column names are extracted from the header of the file, and the file is scanned to index the file positions of the "Model", "Year" and "Maker" column values.

Indexing allows for random access to column values without having to scan the file each time the lookup table is queried. Queries to the table can be made via subsequent calls to the lookup() function to locate the maker of the "Focus" model (e.g., "Ford"). This function supports the loading of text lookup files, which can span GBs of data without having to load them into memory in their raw form or scan them each time the lookup is queried

Kind: static method of TenXLookup
Returns: number - The lastModified value (UNIX epoch in milliseconds) of the lookup file on disk (similar to the parameterless overload of lastModified()), allowing the calling TenxInput instance to validate the lookup file's freshness. Raises an error if the lookup file could not be loaded.

Param Type Default Description
lookup string the name of the lookup file. If the name is a canonized path name it is used as-is to locate the file. If the name does not contain a path name or is relative, it is treated as relative to the 'TENX_CONFIG' env variable value.
[extractColumns] boolean true specifies whether the first row of the file should be used to determine the column names. If set to false, access to column names with subsequent calls to the lookup function will need to be made using numeric column indexes vs. alphanumeric names.
...columns Array.<string> an array of up to 5 column names to index in memory. This provides fast access to column values without having to re-scan the file when querying the lookup

Example

this.maker = TenXLookup.get("example", this.model,  "Model",  "Maker");

.loadGeoIPDB(fileName) ⇒ number

Loads a GeoIP DB file to allow the geo location of host IP addresses.

This function uses the Maxmind client library to connect to a GeoIP DB file. Once connected, the get() function can be used to query the location attributes of a target host IP address.

Supported lookup fields provided for an IP address are: - Continent - Country - Subdivision - City - Postal - Latitude - Longitude

Field names are case insensitive.

The following call will load a MaxMind GeoIP db as part of input initialization:

export class CountryInput extends TenXInput {
  constructor() {
    TenXLookup.loadGeoIPDB("GeoLite2-City.mmdb");
  }
}

TenXObject constructors can use the calls to get() can translate the ipAddress field into its matching country value: 

export class CountryObject extends TenXObject {
  constructor() {
    this.country = TenXLookup.get("GeoLite2-City", this.ipAddress, "country");
  }
}

Kind: static method of TenXLookup
Returns: number - The lastModified value (UNIX epoch in milliseconds) of the GeoIP DB file on disk (similar to the parameterless overload of lastModified()), allowing the calling TenxInput instance to validate the lookup file's freshness. Raises an error if the lookup file could not be loaded.

Param Type Description
fileName string Path to the GeoIP DB file.

.lookupMatch(lookup) ⇒ boolean

Checks whether a specified lookup table has a row matching the current TenXObject equivalent fields.

This function scans a lookup table that has been previously loaded via a call to load() for a row whose values matches those of fields identified by the table's columns within the current object. The lookup table must be loaded with an 'extractColumns' argument set to true for this function to operate correctly.

For example, a dropPolicy.csv lookup table containing a message and severity columns may be queried against the current object's (intrinsic/calculated/extracted) fields of the same two names. If the current object's message and severity fields match the values of a target row within the lookup - the call would return true.

The lookup table can be further synchronized with a GitHub repository to allow changes to the table to be made and reflected within the lifetime of the current 10x Engine via config realod.

Kind: instance method of TenXBaseObject
Returns: boolean - whether the lookup table contains a row whose values match those of current object's (intrinsic/calculated/extracted) fields named by the table's columns.

Param Type Description
lookup string the name of the lookup to access. This name can be the name of a .csv/.tsv text file previously loaded via load(). Lookup table names are case insensitive, and the parent folder/file extension may be omitted (e.g., specify 'examples' vs. '/etc/lookups/examples.csv')

Example

if (TenXLookup.match("dropPolicy.csv") { // check whether 'this.message' and 'this.severity' are found in the table
  this.drop();                          // if so - filter out the current object
}

.get(lookup, key, [keyColumn], [valueColumn]) ⇒ string

Query a previously loaded lookup table using a specific key

This function queries a lookup table that has been previously loaded via a call to load() or loadGeoIPDB() for a specific column value using a key and value column names.

For example, to calculate the make of a car object using an TenXObject's extracted/calculated 'model' field from the 'examples' lookup table loaded via load(), use:

Kind: static method of TenXLookup
Returns: string - Value held within the table's 'valueColumn' for the row whose 'keyColumn' is equal to 'key'. If the key is not found, an empty string is returned.

Param Type Default Description
lookup string the name of the lookup to access. This name can be that of a .csv/.tsv text file or geoIP DB previously loaded via load() Lookup table names are case insensitive, and the parent folder and file extension can be omitted (e.g., specify 'examples' vs. '/etc/lookups/examples.csv')
key string the lookup key value to search for, such as a a host IP for a GeoIP DB or comma/tab-delimited value to look for within a .csv/.tsv text file.
[keyColumn] string | number 0 Name of the column containing the key value, or its zero-based numeric index in the lookup table.
[valueColumn] string | number 0 Name of the value column from which to retrieve the function's result value or its zero-based numeric index in the lookup table.

Example

export class Car extends TenXObject {
  constructor() {
    this.make = TenXLookup.get("examples", this.model, "model", "make"); 
  }
}

.lastModified(lookupName, [offset]) ⇒ number | boolean

Returns the last modified time of a lookup file as a 64-bit epoch timestamp, or checks if the lookup is fresh based on a specified age threshold.

Allows determination of lookup data "freshness" by returning the last modification time of the underlying lookup file on disk. Lookup files can be configured to sync with GitHub or reload from disk when changes occur.

This function helps determine when lookup data was last updated, which is useful for monitoring data currency and triggering refresh operations when needed.

Kind: static method of TenXLookup
Returns: number | boolean - If offset is not provided: 64-bit epoch timestamp of the last modification time. If offset is provided: true if lookup is fresh, false if stale.

Param Type Description
lookupName string Name of the lookup whose last modified time to retrieve
[offset] number Optional. Maximum age in milliseconds to consider the lookup "fresh". If provided, the function returns true if the lookup is fresh (lastModified > TenXDate.now() - offset), false if stale.

Example

// Get the last modified timestamp
export class GeoIPInput extends TenXInput {
  constructor() {
    // Do not load a lookup file that is more than 24 hours old
    let lastMod = TenXLookup.lastModified(TenXEnv.get("geoIpLookFile"));
    let twentyFourHoursAgo = TenXDate.now() - (24 * 60 * 60 * 1000);

    if (lastMod < twentyFourHoursAgo) {
      throw new Error("GeoIP lookup data is stale (older than 24h), last modified: " + 
        TenXDate.format(lastMod, "yyyy-MM-dd HH:mm:ss"));
    }

    // Load the GeoIP database if fresh
    TenXLookup.loadGeoIPDB(TenXEnv.get("geoIpLookFile"));
  }
}
Example
// Check if lookup is fresh (less than 5 minutes old)
export class GeoIPInput extends TenXInput {
  constructor() {
    if (!TenXLookup.lastModified(TenXEnv.get("geoIpLookFile"), 60000 * 5)) {
      throw new Error("GeoIP lookup data is stale (older than 5 minutes)");
    }

    // Load the GeoIP database if fresh
    TenXLookup.loadGeoIPDB(TenXEnv.get("geoIpLookFile"));
  }
}

See also: Config reload • GitHub sync

TenXConsole

Print values to the host process' stdout/stderr output streams.

Kind: global class

.log([...values])

Prints a set of values to the stdout device

This function prints an array of values into the stdout device. If the values array is empty, the value of joinFields is used.

Kind: static method of TenXConsole
Return{string}: the actual string printed to the console

Param Type Default Description
[...values] Array.<Object> the list of values to print.

.error([...values]) ⇒ string

Prints a set of values to the stderr device

This function prints an array of values to the stderr device. If the values array is empty, the value of joinFields is used.

Kind: static method of TenXConsole
Returns: string - the actual string printed to the console

Param Type Default Description
[...values] Array.<Object> [] the list of values to print.

TenXDate

Access system time and formatting/parsing date values.

Kind: global class

.now([offset]) ⇒ number

Returns the current epoch time in milliseconds plus a specified offset

Kind: static method of TenXDate
Returns: number - Difference, measured in milliseconds, between the current time + offset and midnight, January 1, 1970 UTC

Param Type Default Description
[offset] string | number 0 Offset duration to be added to the current epoch time. If a string is provided (e.g., "30sec"), it is converted into milliseconds. If a number is provided, it is treated as a +/- millisecond numeric offset.

.parse(str, pattern) ⇒ number

Parses a string value into an epoch value based on a specified pattern

Kind: static method of TenXDate
Returns: number - Numerical value holding the epoch time resulting from parsing str based on the pattern. If parsing fails, 0 is returned

Param Type Description
str string String to parse
pattern string Date-time pattern

Example

TenXConsole.log(TenXDate.parse("2021-09-16T02:33:05.289552Z", "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"));

will output: 1631773985289

.format(epoch, pattern) ⇒ string

Formats a numeric epoch value into a string representation based on a specified pattern

Kind: static method of TenXDate
Returns: string - Numerical value holding the epoch time resulting from formatting epoch based on pattern. If formatting fails, an empty string is returned

Param Type Description
epoch number Epoch value to format
pattern string Date-time pattern to apply

Example

TenXConsole.log(TenXDate.format(1631773985289, "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"));

will output: 2021-09-16T02:33:05.289552

.parseDuration(duration) ⇒ number

Parses a duration string and converts it to milliseconds

Kind: static method of TenXDate
Returns: number - Numerical value holding the duration in milliseconds. If parsing fails, 0 is returned

Param Type Description
duration string Duration string to parse (e.g., "6d", "3min", "1h", "30sec", "500ms") Supported units: ms (milliseconds), sec/s (seconds), min/m (minutes), h (hours), d (days), w (weeks)

Example

TenXConsole.log(TenXDate.parseDuration("6d"));

will output: 518400000 (6 days in milliseconds)
Example 
TenXConsole.log(TenXDate.parseDuration("3min"));

will output: 180000 (3 minutes in milliseconds)

.isBefore(left, right) ⇒ boolean

Checks if the first epoch timestamp is before the second epoch timestamp. Handles both millisecond and nanosecond epoch formats automatically.

Kind: static method of TenXDate Returns: boolean - true if left < right, false otherwise Throws: IllegalArgumentException if either argument is null, not a valid number, or negative

Param Type Description
left number First epoch timestamp to compare (milliseconds or nanoseconds)
right number Second epoch timestamp to compare (milliseconds or nanoseconds)

Example 

TenXDate.isBefore(1631773985289, 1631773985290); // returns true
Example 
TenXDate.isBefore(this.timestamp, TenXDate.now()); // compare event time to current time

.isBeforeOrEqual(left, right) ⇒ boolean

Checks if the first epoch timestamp is before or equal to the second epoch timestamp. Handles both millisecond and nanosecond epoch formats automatically.

Kind: static method of TenXDate Returns: boolean - true if left <= right, false otherwise Throws: IllegalArgumentException if either argument is null, not a valid number, or negative

Param Type Description
left number First epoch timestamp to compare (milliseconds or nanoseconds)
right number Second epoch timestamp to compare (milliseconds or nanoseconds)

Example 

TenXDate.isBeforeOrEqual(1631773985289, 1631773985289); // returns true
Example 
TenXDate.isBeforeOrEqual(this.timestamp, TenXEnv.get("cutoff_time")); // compare event time to cutoff

.isAfter(left, right) ⇒ boolean

Checks if the first epoch timestamp is after the second epoch timestamp. Handles both millisecond and nanosecond epoch formats automatically.

Kind: static method of TenXDate Returns: boolean - true if left > right, false otherwise Throws: IllegalArgumentException if either argument is null, not a valid number, or negative

Param Type Description
left number First epoch timestamp to compare (milliseconds or nanoseconds)
right number Second epoch timestamp to compare (milliseconds or nanoseconds)

Example 

TenXDate.isAfter(1631773985290, 1631773985289); // returns true
Example 
TenXDate.isAfter(this.timestamp, TenXDate.now("-1h")); // check if event is within the last hour

.isAfterOrEqual(left, right) ⇒ boolean

Checks if the first epoch timestamp is after or equal to the second epoch timestamp. Handles both millisecond and nanosecond epoch formats automatically.

Kind: static method of TenXDate Returns: boolean - true if left >= right, false otherwise Throws: IllegalArgumentException if either argument is null, not a valid number, or negative

Param Type Description
left number First epoch timestamp to compare (milliseconds or nanoseconds)
right number Second epoch timestamp to compare (milliseconds or nanoseconds)

Example 

TenXDate.isAfterOrEqual(1631773985289, 1631773985289); // returns true
Example 
TenXDate.isAfterOrEqual(this.timestamp, TenXEnv.get("start_time")); // check if event is at or after start

TenXCounter

Get and set the values of global atomic counters.

Kind: global class

.get([counter]) ⇒ number

Returns the value of the specified atomic counter. If no counter by this name found it is created.

Kind: static method of TenXCounter
Returns: number - Value of the counter

Param Type Default Description
[counter] string "default" Name of the counter whose value to get.

.inc([counter], [value], [resetInterval]) ⇒ number

Increase and return the value of the selected atomic counter by a specified value.

To add the values of the current object's calculated/extracted 'price' field to a 'purchases' counter:

Kind: static method of TenXCounter
Returns: number - Value of the counter after 'value' has been added to it

Param Type Default Description
[counter] string "default" Name of the counter to get.
[value] number 1 Value by which to increase the counter.
[resetInterval] string | number "" Repeating interval after which the counter is reset to 0. Can be a number (milliseconds), string interval (e.g., "10s", "1min"), ISO-8601 duration format (e.g., "PT10S", "PT1M"), or name of a variable containing it. This value cannot exceed 255 seconds and is rounded up to the second.

Example

TenXCounter.inc("purchases", this.price);

.getAndInc([counter], [value], [resetInterval]) ⇒ number

Increase the value of the selected counter by a specified value and return its value before increase.

To add the values of the current object's calculated/extracted 'price' field in a 'purchases' counter:

Kind: static method of TenXCounter
Returns: number - The value of the counter before 'value' has been added to it

Param Type Default Description
[counter] string "default" Name of the counter whose value to get.
[value] number 1 The value by which to increase the counter.
[resetInterval] string | number "" Repeating interval after which the counter is reset to 0. Can be a number (milliseconds), string interval (e.g., "10s", "1min"), ISO-8601 duration format (e.g., "PT10S", "PT1M"), or name of a variable containing it. This value cannot exceed 255 seconds and is rounded up to the second.

Example

TenXCounter.getAndInc("purchases", this.price);

.getAndSet([counter], [value], [resetInterval]) ⇒ number

Set the value of a target 64bit atomic counter to a specified value and optionally reset every target interval.

A counter can be used to aggregate the number of events matching a specific condition:

export class MyObject extends TenXObject {

        MyObject() {
            if this.startsWith("ERROR")
             TenXCounter.inc("errors");
        }
}

The counter can then be atomically queried and reset into a summary instance:

js export class ErrorSummary extends TenXSummary { constructor() { this.errors = TenXCounter.getAndSet("errors", 0); } }

An interval counter can be used to limit the rate of TenXObjects based on their symbolSequence to a target limit (e.g. 1000) within a specific interval (e.g. "1s").

This prevents a "chatty" event from "hogging" the pipeline's bandwidth:

export class RateLimitObject extends TenXObject {
  constructor() {

    var symbolSequence = this.symbolSequence();

    if (TenXCounter.getAndSet(symbolSequence, "1s") > 1000) 
         this.drop();
    else 
      TenXCounter.inc(symbolSequence);      
  }
}

Kind: static method of TenXCounter
Returns: number - Value of the counter before being reset

Param Type Default Description
[counter] string "default" name of the counter whose value to get.
[value] number 1 Value to set into the counter.
[resetInterval] string | number "" Repeating interval after which the counter is reset to 0. Can be a number (milliseconds), string interval (e.g., "10s", "1min"), ISO-8601 duration format (e.g., "PT10S", "PT1M"), or name of a variable containing it. This value cannot exceed 255 seconds and is rounded up to the second.

TenXMath

Mathematical functions such as aggregation, parsing and hashing.

Kind: global class

.avg(...values) ⇒ number

Returns the average of an array of values

This function returns an average of the sum of each of the values in the supplied array. If an element cannot be converted into a number, it is ignored.

Kind: static method of TenXMath
Returns: number - the resulting average value. If no value is found to average, return 0

Param Type Description
...values Array.<number> the list of values to average

.hashCode(value) ⇒ number

Returns a simple 32bit hashCode for a supplied string

This function returns a simple hashing facility for an input string. The hashing algorithm is the same as Java's Object.hashCode function.

An example where this function can be useful in the context of the event sampling. If only 10% of transaction spans that have a DEBUG level severity are to be kept, the value of an alphanumeric field such as "transactionId" which holds a GUID value can be hashed to filter in those values which divide cleanly by 10, thus keeping (assuming a random GUID distribution) 10% of matching objects:

Kind: static method of TenXMath
Returns: number - 32-bit hashCode

Param Type Description
value string Value to hash

Example

if (this.startsWith("DEBUG") && (TenXMath.hashCode(this.transactionId) % 10) == 0) 
    this.drop();

.max(...values) ⇒ number

Returns the highest numerical value within the supplied array

This function returns the highest numerical value within the supplied array. If an element cannot be converted into a number, it is ignored.

Kind: static method of TenXMath
Returns: number - Resulting max value. If no numerical value is found, return 0.

Param Type Description
...values Array.<number> List of values to search in

.min(...values) ⇒ number

Returns the lowest numerical value in the supplied array

This function returns the lowest numerical value in the supplied array. If an element cannot be converted into a number, it is ignored.

Kind: static method of TenXMath
Returns: number - Resulting average value. If no minimal value is found, return 0.

Param Type Description
...values Array.<number> List of values to search in

.parseDouble(str, [defVal]) ⇒ number

Return a 64bit double representation of a string

This function converts the input string into a 64-bit double value. If the value does not represent a floating point value, 0 is returned.

Kind: static method of TenXMath
Returns: number - Parsed double value, defVal (if provided) or 0 in case of failure

Param Type Default Description
str string String to parse
[defVal] number 0 Value to return if str cannot be parsed

.parseInt(str, [defVal]) ⇒ number

Return a 64bit long representation of a string

This function converts the input string into a 64-bit long value. If the value does not represent a numeric point value, 0 is returned.

Kind: static method of TenXMath
Returns: number - Parsed long value, defVal (if provided) or 0 in case of failure

Param Type Default Description
str string String to be parsed
[defVal] number 0 Value to return if str cannot be parsed

.random([min], [max]) ⇒ number

Returns a randomly generated number

This function randomly generated an int number in the range between min and max. If min and/or max are not supplied, and the function returns a double number between 0 and 1.

Kind: static method of TenXMath
Returns: number - Resulting random number.

Param Type Default Description
[min] number 0 Start of random range
[max] number 1 End of random range

.round(value) ⇒ number

Returns the closest integer to the argument, with ties rounding to positive infinity.

This function rounds a number to the nearest integer using Java-style rounding rules. For values exactly halfway between two integers (e.g., 2.5), it rounds up to the larger integer.

Kind: static method of TenXMath
Returns: number - The rounded integer value.

Param Type Description
value number The number to round

.sum(...values) ⇒ number

Returns the sum of values in the supplied array

This function returns the sum of values in the supplied array. If an element cannot be converted into a number, it is ignored.

Kind: static method of TenXMath
Returns: number - Resulting sum value. If no numerical value is found, returns 0.

Param Type Description
...values Array.<number> List of values to search in

TenXEnv

Access 10x launch arguments.

Kind: global class

.get(name, defValue) ⇒ string

Returns the value of a launch argument or environment variable.

Requests for variable values are resolved in the following order:

Kind: static method of TenXEnv
Returns: string - Value of the variable if found, otherwise 'defValue' if provided or empty value if not.

Param Type Description
name string Name of the launch arg or environment variable to query
defValue string | number | boolean Value to return if a matching variable is not found

Example

For example, the decision to drop TRACE events can be made configurable by introducing a dropTrace argument. This argument can then be checked as follows:

class MyObject extends TenXObject {
  constructor() {
    this.drop(TenXEnv.get("dropTrace") && this.startsWith("TRACE")); 
  }
}

.path(path) ⇒ string

Resolves a relative path on disk to a canonical one.

Configuration files utilize this function to resolve a file/folder reference relative to: - includePaths - Shell variable (e.g.,. MY_FOLDER) - JVM system property (e.g.,. user.dir, temp.dir, tenx.temp.dir)

Kind: static method of TenXEnv
Returns: string - canonical path value

Param Type Description
paths string[] relative file/folder paths to attempt to resolve in order
emptyOnFail boolean return empty string if path not found, otherwise return last item in paths

Example

# Resolve a relative config path, if not found - default to pipeline temp dir variable.
localFolder: $=path("<user.dir>/compile/sources", <tenx.temp.dir>") 

# Resolve the 'astpretty.py' relative path
launchOptions:
  args:
    - $=path("pipelines/compile/modules/scanner/pythonAST/astpretty.py")

TenXLog

Write messages to the 10x log.

Kind: global class

.debug(message, ...params) ⇒ string

logs a message to the 10x log with a DEBUG level.

This function logs a message and an optional list of parameters to the 10x log. The destination to which log messages are written is configured in the 'log4j2.yaml' file. It is recommended to apply the log4j parameter formatting scheme vs. concatenating the message and params manually. To learn more see messages.

Kind: static method of TenXLog
Returns: string - Message parameter passed into this function

Param Type Description
message string Message to log
...params Array.<string> Parameters to format into message

Example

TenXLog.debug("error parsing value: {} in object of type: {}", this.value, this.symbolSequence());

.info()

logs a message to the 10x log with an INFO level. See debug to learn more.

Kind: static method of TenXLog

.error()

logs a message to the 10x log with an ERROR level. See debug to learn more.

Kind: static method of TenXLog

.isDebug() ⇒ boolean

checks whether debug logging is enabled.

Returns a boolean value indicating whether debug-level logging is currently enabled. The function can be used to conditionally log expensive debug messages only when debugging is active, avoiding unnecessary string formatting or computation when debug logs would be discarded.

Kind: static method of TenXLog
Returns: boolean - boolean indicating whether debug logging is enabled

Example

// Drop if rate is below minimum threshold
if (rate < minRate) {

    this.drop();

    if (TenXLog.isDebug()) {

        TenXLog.debug("drop by min rate. preIncrementCount={}, baseRate={}, rate={}, freqPerMin={}, randomValue=undefined, boost={}, baseline={}",
        preIncrementCount, baseRate, rate, freqPerMin, boost, baseline);
    }
}

.throwError(message) ⇒

Throws an error to halt the 10x Engine.

This function can be used to validate input/configuration values to ensure they are present and correct before reading events from input(s).

For example, a threshold startup argument used for processing TenXObjects may need to hold a positive numeric value. For this, an assertion is used to validate that the launch argument is both present and can be converted into a positive number value.

The threshold launch argument can be defined in a module file as:

  options:      
  - names:
    - threshold
    description: my threshold value
    type: number
    required: true

The script below validates a positive number was passed to the 10x Engine:

export class ThresholdInput extends TenXInput {
  constructor() {
    if (TenXMath.parseInt(TenXEnv.get("threshold", -1)) <= 0) 
      throw new Error("positive 'threshold' not set!");      
  }
}

//The threshold can be used to tally instances whose 'threshold' field is > 'threshold'
export class ThresholdObject extends TenXObject {
  constructor() {       
    if (this.threshold > TenXEnv.get("threshold")) TenXCounter.inc("overThreshold");
  }
}

// An aggregator can be configured to generate TenXSummaries to tally the volume of TenXObjects surpassing 'threshold'. 
// To learn more see: https://doc.log10x.com/run/aggregate
export class ThresholdSummary extends TenXSummary {
  constructor() {       
    this.overThreshold = TenXCounter.getAndSet("overThreshold", 0);
  }
}

The module and script files can be passed alongside the threshold value to the 10x Engine: 

$ tenx run @threshold.js @threshold.yaml threshold 1000

A 'config.yaml' file can bundle these settings and passed to the runtime via:

tenx @config.yaml: 

tenx: run
include:
  - threshold.yaml
  - threshold.js
threshold: 1000

Kind: static method of TenXLog
Returns: halt the runtime

Param Type Description
message string a message to write to stderr if the condition is not 'truthy'.

TenXEngine

The 10x Engine provides the underlying implementation of all classes and functions in the tenx.js API module.

To load custom JavaScript classes at runtime see JavaScript configuration.

Kind: global class

.invoke(...args)

A sink method for invoking a target 10x API JS function. The concrete implementation of this method is provided at runtime by the 10x Engine. This method is not intended to be called directly by user code.

Kind: static method of TenXEngine
Returns: return value of the target function invoked by the caller

Param Type Description
args ...any arguments for the target function being invoked

.shouldLoad(config) ⇒ boolean

Determines whether a custom JavaScript class should be loaded and instantiated by the 10x Engine.

This static method is called by the engine during the loading phase to decide which user-defined subclasses should be applied to specific instances. The engine passes a config object containing all configuration values for the relevant module (input, output, unit, etc.).

For object, template, and summary subclasses, the config object provides all configuration values from the input module for which these classes are instantiated.

Global configuration flags (such as quiet) are accessed via TenXEnv.get() and are not part of the config object.

Kind: static method of TenXEngine
Returns: boolean - True if the class should be loaded and instantiated, false to skip

Param Type Description
config Object Configuration object with named access to all module options
config.inputName string For inputs/objects/templates: name of the input (e.g., "CloudWatchLogs")
config.outputName string For outputs: name of the output (e.g., "FileOutput")
config.unitName string For units: name of the unit (e.g., "LoadConfig")

Example

// In a CloudWatch Logs object processor
export class CloudwatchLogsObject extends TenXObject {
  // @https://doc.log10x.com/api/js/#TenXEngine.shouldLoad
  static shouldLoad(config) {
    return TenXString.endsWith(config.inputName, "CloudWatchLogs");
  }
}

Example

// In a file output with quiet mode check
export class FileOutput extends TenXOutput {
  // @https://doc.log10x.com/api/js/#TenXEngine.shouldLoad
  static shouldLoad(config) {
    return !TenXEnv.get("quiet") && config.outputName === "FileOutput";
  }
}