Global Variables were one of the most important features introduced with Cribl LogStream 2.1. In this short post we’ll take a look at what they are, how they work and how to use them to build more effective pipelines.
If you’re new to Cribl LogStream it may make sense to take our sandbox for a drive before reading further.
LogStream Global Variables are re-usable and composable expressions for the purposes of storing constants that can be referenced later or storing value expressions that can be invoked with optional arguments. They are managed via Knowledge > Global Variables and can be any of the following types: number, string, boolean, object, array, expression. They are accessed via C.vars. and can be called anywhere JS expressions are supported in the product, including obviously functions in any pipeline. They’re also typeahead enabled for convenient and contextual help.
How to use them
The typical use-case is code reuse which simultaneously helps improve expression manageability and intention articulation. For instance, if you find yourself wanting to add current time in epoch format in many pipelines then it’s more convenient to just define a single Global Variable and call it whenever you need it, as opposed to typing the original expression every single time. LogStream ships with an expression variable named: unixtime. Go to Knowledge > Global Variables and expand unixtime:
Adding a field with Eval, is as easy as calling C.vars.unixtime():
Another example with a longer expression
Suppose we wanted to convert a field holding a byte size into a human-readable size. E.g., 2048 -> 2KB. We can do that with a simple value expression in Eval. But it’s much easier to have a re-usable definition via Global Variables and call it whenever we need it by passing the field of interest as an argument.
In this example, we’re creating a new field called filesizeHuman by passing filesize to the Global Variable as such: C.vars.convertBytes(filesize):
Notice how long the expression is, typing it every single time would be tedious and prone to typos or mistakes. Using a Global Variable we now have a single definition that is easy to control, manage and update.
One more example – adding internal fields to events
Say we wanted to decorate each event with the inputId of the Source they came from and the LogStream hostname of the Worker that processed it. We can define a Global Variable expression with the following: {'cribl_host': C.os.hostname(), 'cribl_inputId': __inputId} and then assign it to a field in an Eval function.
The expression evaluates a simple object with the hostname and inputId as below:
One last example, this time with an array
Suppose we wanted to drop all events from any pipeline in the system if they match a certain log level – for example, all DEBUG events. Suppose further that later we have a new requirement to drop all TRACE level events, too. As above, we can first add a Drop function with a Filter expression set to level=='DEBUG' and later go back to each and every pipeline and modify it to level=='DEBUG' || level=='TRACE'. Or, we can use a Global Variable as a Filter expression, for instance:
C.vars.dropLogLevel is defined as an array and the includes() method can be used. For good measure, level can be converted to lowercase before the check.
Using Global Variable decouples definition from the application and allows us to control the expression from a single place instead of modifying all the pipelines where it’s applied at.
—
New to Cribl LogStream? Take our Sandbox for a drive!
If you have any questions or feedback join our community Slack– we’d love to help you out. If you’re looking to join a fast-paced, innovative team drop us a line at hello@cribl.io– we’re hiring!
