Java OutputStream Output

Defines a Java OutputStream to write TenXObject instance and template field values.

OutputStreams provide a simple mechanism for adding custom output destinations to write TenXObject/Summary/Template values.

For an example of a custom OutputStream implementation see UnixSocketOutputStream

Configuration

To configure the Java OutputStream output module, Edit these settings.

Below is the default configuration from: outputStream/config.yaml (* Required Fields).

Edit Online

# 🔟❎ 'run' output stream configuration

# Configure a Java OutputStream to write TenXObject field and templates values.
# To learn more see https://doc.log10x.com/run/output/event/outputStream/

# Set the 10x pipeline to 'run' 
tenx: run

# =============================== Dependencies ================================

include: run/modules/output/event/outputStream

# ============================ OutputStream Options ===========================

# Multiple OutputStream file outputs can be defined below
outputStream:

  # ----------------------------- Object Output ------------------------------

    # 'writeObjects' controls whether to write TenXObject field values to output.
  - writeObjects: true # (❗ REQUIRED)

    # ------------------------- OutputStream Options -------------------------

    # 'class' specifies the class derived from java.io.OutputStream
    #  that is instantiated, written to and closed by the 10x host JVM
    #  In this example, values are written to a Unix domain socket
    class: com.log10x.ext.edge.output.unix.UnixSocketOutputStream

    # 'args' provides an optional mechanism to pass an Object[] value
    #  to the constructor of 'class' that contains implementation-specific
    #  configuration values. In this example, we calculate and set the
    #  file name used by the Unix domain socket to write which TenXObject instance/template values.
    args:
      - address
      - '$=path("<user.home>/tenx.socket")' 

    # 'groupKeys' provides an optional mechanism for grouping instances of
    #  'class' according to a unique set of values. Grouping allows multiple
    #  outputs such as this output and the template output below it to
    #  share a single instance of 'class' which is effective when writing
    #  to OutputStream, which holds a mutually exclusive resource. In this
    #  example, outputs are grouped by the address of the client Unix domain socket.
    groupKeys:
      - '$=path("<user.home>/tenx.socket")' 

    # --------------------------- Encoding Options ----------------------------

    # 'filter' sets a JavaScript expression that TenXObjects must evaluate as truthy to write to the output.
    #  To learn more see https://doc.log10x.com/run/output/regulate/#filter-expressions
    filter: isObject                          

    # 'fields' defines the fields to write for each TenXObject sent to this output.
    #  To learn more see https://doc.log10x.com/run/output/stream/#outputfields  
    fields: 
      - encode() 

    # 'encodeType' specifies how 'fields' are encoded to output. Possible values: [json,delimited].
    #  To learn more see https://doc.log10x.com/run/output/event/outputStream/#outputstreamencodetype
    encodeType: delimited 

    # 'encodeDelimiter' sets the char delimiter used to separate TenXObject
    #  field values when 'encodeType' is set to: 'delimited'     
    encodeDelimiter: ',' 


  # ---------------------------- Template Output ----------------------------

    # 'writeTemplates' controls whether to write template values for TenXObjects passed to
    #  to file. Only new templates are written. 
  - writeTemplates: true

    # ------------------------- OutputStream Options -------------------------

    # The file output below writes the template values of TenXObjects 
    # passed to this file location. To learn more about TenXTemplates, see:
    # https://doc.log10x.com/run/template

    # For descriptions of 'class', 'args', and 'groupKeys', see the 
    # object output stream above. 
    class: com.log10x.ext.edge.output.unix.UnixSocketOutputStream

    args:
      - address
      - '$=path("<user.home>/tenx.socket")' 

    groupKeys:
      - '$=path("<user.home>/tenx.socket")'

Options

Specify the options below to configure multiple Java OutputStream output:

Name	Description	Category
outputStreamClass	Fully2 qualified java.io.OutputStream/Writer sub-class name	General
outputStreamArgs	Arguments to pass to the constructor of 'outputStreamClass'	General
outputStreamFilter	A JavaScript expression an TenXObject must evaluate as 'truthy' against to be written to this output	General
outputStreamFields	List of TenXObject field names to encode	Encode
outputStreamWriteObjects	If true, TenXObject field values specified by [outputStreamFields](https://doc.log10x.com/run/output/event/outputstream/#outputstreamfields) are encoded to this output	Encode
outputStreamWriteTemplates	If true, write new TenXTemplates to this output	Encode
outputStreamEncodeType	The output format in which to encode TenXObject values. Possible values:[json, delimited]	Encode
outputStreamEncodedLinePrefix	The line prefix prepended to the encoded event if 'outputStreamEncodeType' is 'delimited'	Encode
outputStreamEncodeDelimiter	The delimiter placed between key and values pairs if 'outputStreamEncodeType' is 'delimited'	Encode
outputStreamGroupKeys	Values to assign an 'outputStream' to a target output instance	Advanced

General

`outputStreamClass`

Fully2 qualified java.io.OutputStream/Writer sub-class name.

Type	Required	Category
String	✔	General

specifies a fully qualified OutputStream or Writer sub-class to instantiate. The specified outputStreamFields of each encoded TenXObjects will be written to the stream with a matching call to its flush method after each instance.

The class must implement a parameterless constructor or one with the following signature:

/**
* @param args
*   The values of the 'outputStream' option group specified
*   for this OutputStream/Writer instance provided as a map(<argName>=<argValue>...).
*   This allows the stream to read configuration values provided via config files/command line arguments.
*
* @param evaluatorBean
*   An evaluator bean to enable this stream to interact with the 10x Engine
*/
public MyOutputStream(Map<String, Object> args, com.log10x.api.bean.EvaluatorBean evaluatorBean){...}

`outputStreamArgs`

Arguments to pass to the constructor of 'outputStreamClass'.

Type	Default	Category
List	[]	General

Value pairs to insert to the OutputStream/Writer constructor 'args' Map. This argument adds configuration values to the map passed to Stream/Writer ctor in addition to those specified by its matching 'outputStream' option group instance.

This argument allows for providing stream-specific context and default values such as a host address, port, etc.

`outputStreamFilter`

A JavaScript expression an TenXObject must evaluate as 'truthy' against to be written to this output.

Type	Default	Category
String	""	General

Specifies a JavaScript expression that an TenXObject must evaluate as truthy to write its instance/template field values to this output.

For example, to only emit timestamped TenXObjects, specify:

outputStreamFilter: this.timestamped

Encode

`outputStreamFields`

List of TenXObject field names to encode.

Type	Default	Category
List	[]	Encode

Specifies a list of TenXObject intrinsic/calculated/extracted field names to extract and write to the output.

`outputStreamWriteObjects`

If true, TenXObject field values specified by [outputStreamFields](https://doc.log10x.com/run/output/event/outputstream/#outputstreamfields) are encoded to this output.

Type	Default	Category
String	true	Encode

Determine whether to write outputStreamFields values of an TenXObject passed to this output. This configuration is typically defined using a JavaScript expression.

To enable/disable the output depending on whether a launch argument, environment variable, or JVM -D option evaluates as truthy, use:

  outputStreamWriteObjects: $=TenXEnv.get("myOutputStreamClass")

To learn more see TenXEnv.get.

`outputStreamWriteTemplates`

If true, write new TenXTemplates to this output.

Type	Default	Category
String	false	Encode

Controls whether to write template values of TenXObjects passed to this output. The output will only emit TenXTemplates that the pipeline did not load at startup via the templateFile argument, and will only emit an TenXTemplate once based on its templateHash value.

`outputStreamEncodeType`

The output format in which to encode TenXObject values. Possible values:[json, delimited].

Type	Default	Category
String	delimited	Encode

Specifies how to encode outputStreamFields values to this output. Possible values:

json: formats names and values for the current TenXObject as: {"field":"str","field2":1, "field3": true}
delimited: formats values for the current TenXObject as: "str",1,true The outputStreamEncodeDelimiter argument determines the separator to use.

`outputStreamEncodedLinePrefix`

The line prefix prepended to the encoded event if 'outputStreamEncodeType' is 'delimited'.

Type	Default	Category
String		Encode

Sets the char which is prepended to the emitted TenXObject field values when outputStreamEncodeType is delimited.

`outputStreamEncodeDelimiter`

The delimiter placed between key and values pairs if 'outputStreamEncodeType' is 'delimited'.

Type	Default	Category
String	" "	Encode

Sets the char delimiter to separate TenXObject field values when outputStreamEncodeType is delimited.

Advanced

`outputStreamGroupKeys`

Values to assign an 'outputStream' to a target output instance.

Type	Default	Category
List	[]	Advanced

Specifies a list of values by which instances of the 'outputStream' option group are assigned to specific instances of 'outputStreamClass' to enable multiple outputs to use a single synchronized OutputStream instance.

This module is defined in outputStream/module.yaml.