Events-processing output

Internal

• events-processing

Overview

"output" is the default procedure applied to event streams, in absence of any other configuration. The procedure inspects all events flowing through the stream and the event's string representation, possibly preceded by header line, to the configured output stream, which is usually stdout. The procedure can be programmatically configured to use a different output stream.

The string representation for an event is generated according to the following algorithm:

• If no output format is explicitly specified by the command, the output procedure will delegate formatting to a default output format, which in turn will try to use, in order:
  • the preferred representation of the event, as returned by the event.
  • the raw representation of the event, as returned by event.
  • for timed events, the timestamp.
  • the event's toString() invocation result.
• If an output format is specified, the output format will be used to render the header and the event representation.

If a custom output format is used, and only In case of timed events, the leading timestamp will be generated regardless of the details of the custom output format. If the output format explicitly specified the timestamp, the timestamp will be redundantly rendered.

One way to provide the format specification is on command-line: format specification arguments follow the "-o" marker and end either with the last argument or when a higher level argument (file, for example) is encountered.The output format also acts as a filter - if the event does not match at least one of the output format elements, it will not be displayed at all. More details on the output format are available below: "Output Format".

some-parser [output] -o <output-format> ./file.txt

cat ./file.txt | some-parser [output] -o <output-format>

Output Format

The output format can be used to:

• Restrict the output to specific event types.
• Restrict the output to specific event properties.

Displaying Properties with a Specific Index

Index-based output can be achieved with the following syntax:

<command> -o 0, 1, 2 ....

For CSV content, valid indexes are displayed by the 'headers' command.

Processing Output Properties

The property values selected via a property name or index can be processed by applying functions to it. Use the following syntax:

csv -o "function-name(1), 2 ./data.csv
csv -o function-name(heap-capacity), heap-occupancy ./gc.csv

where "heap-capacity" and "heap-occupancy" are valid property names, and 1 and 2 are valid property indexes.

Output Separators

The output fields may be separated on command line by spaces, commas and a combination of these. The following representations are equivalent:

... -o blue red
... -o blue, red

Headers

The output procedure will display a header, based on the format, before the first event that matches the format is rendered.