Global variables store values you can reference elsewhere in Cribl Edge. These variables allow you to change a single value and then populate everywhere that variable is referenced.

Variables are an important component for scaling your Cribl deployment and improving ease of maintenance. Typical use cases for variables include:

• Storing a constant that you can reference from any Function in any Pipeline.
• Storing a relatively long value expression, or one that uses one or more arguments.
• Converting abstract, complex logical expressions into a reusable variable that has a human-readable name for easier maintenance.

Cribl Edge supports a variety of global variable types:

• Number, String, Boolean: Store simple, static configuration values for reuse and ease of updating (such as threshold limits or names).
• Encrypted String: Store sensitive strings (like API keys or passwords). The value is encrypted at rest but retrieved as plain text when referenced, including when you are logged into the Cribl interface.
• Object: Store complex, structured data or key-value dictionaries, often used as an alternative to small lookup files.
• Array: Store a list of items (such as IP ranges or required field names).
• Expression: Define complex, repeatable logic that requires calculated output, especially when the logic needs to accept arguments.

You access all variables using the standard syntax C.vars.<variableName>. See Cribl Expressions for more information about C.vars and other Cribl Expressions.

Limitations

​

When multiple variables share the same name, Cribl Edge resolves the value based on scope, moving from the most specific (inner) scope to the most general (outer) scope. In other words: local scope values win over broader scopes.

For example, a variable defined inside a Pack (which has a local scope) will always override a variable with the same name defined in the Fleet settings.

Create a Global Variable

​

Creating a new global variable has three main phases:

1. Define the variable scope.

2. Configure the variable.

3. Reference the variable in a Function or Pipeline.

Define the Variable Scope

​

Variables are scoped to different levels of the application. You can only use a variable in the scope in which it is defined.

When creating a new variable, you determine its scope based on where you access and create the variable:

Configure the Variable

​

After ensuring you have accessed the variable from the correct scope, create a new variable:

1. Select Add Variable.

2. Configure the variable settings:

   • Name: Enter a unique name for the variable.

   • Description: Optionally, enter a description.

   • Type: Select the type of variable you want to create. Options include:

     Type	Explanation	Use Cases
     String	A sequence of characters (text).	Can centralize environment identifiers, file paths, URL prefixes, or standard naming conventions. If a string or name changes depending on its context (such as a different environment), you only have to update it in the variable and it populates to configurations in that environment.
     Number	For numeric values, including integers (whole numbers) and floating-point numbers (decimals).	Ideal for defining thresholds or limits that might need tuning later.
     Encrypted string	Stores a string value that is automatically encrypted when saved to the configuration file on disk (YAML). However, within the application at runtime, it is decrypted and treated as a standard string.	Use for storing sensitive credentials like API tokens, secret keys, or passwords. This ensures that if someone inspects your configuration files or git commits, they only see the encrypted hash, not the plaintext secret.
     Boolean	Represents a binary logical value that resolves to true or false.	Use as a switch to enable or disable specific logic paths, detailed logging, or experimental features across your entire deployment without editing individual Pipelines.
     Array	An ordered list of values (strings, numbers) stored in a single variable.	Can help maintain long lists of items, such as IP ranges, required field names, known good or bad hostnames, and more.
     Object	A structured collection of key-value pairs (dictionaries).	Functions as a lightweight, in-memory lookup table.
     Expression	A snippet of JavaScript code that is evaluated only when called. Expressions can accept arguments, allowing them to act like reusable custom logical functions.	Allows you to encapsulate complex, multi-condition logic (like regex matching) into a single function with a human-readable name.
     Any	A flexible container that accepts a value of any variable data type (string, number, expression) without enforcing strict validation rules.	While this variable type is flexible, it removes the safety net of UI validation. Use specific types (like number or boolean) whenever possible for better reliability.

   • Value: Enter the value, data structure, or JavaScript expression for this variable. This input must match the format required by the selected variable type. For example, Expressions should have JavaScript syntax. The system validates the input when you save.

   • Tags: Optionally, add tags that you can use for filtering and grouping in the variable list view. Use a tab or hard return between (arbitrary) tag names.

3. Save the variable. The system validates the Value field to ensure it matches the specified Type when it saves.

Reference the Variable

​

After creating the variable, you can start calling it in Functions, Pipelines, and Packs. You can reference a variable in fields that let you use custom JavaScript code. See the introduction of Build Custom Logic to Route and Process Your Data for examples and images of JavaScript-enabled fields.

Some variable types require additional inputs or arguments:

To illustrate the workflow for referencing a variable, imagine a scenario in which you want to add a field named myField to all incoming events. This field value will get referenced in multiple Pipelines and may possibly change, which is why you decided to make it a variable named theAnswer. For now, you want to set it to a static number value of 42.

After creating the number variable named theAnswer with a value of 42, you could then reference it in a Pipeline:

1. Add the Eval Function. (The Eval Function adds, modifies, or removes event fields.)

2. Select Add Field to add a new field.

3. Configure the new field to reference the theAnswer variable:

   • Name: myField
   • Value Expression: C.vars.theAnswer

4. To validate the value, select Advanced Mode in the Value Expression.

5. Confirm that the Expression output is 42 as expected.

   

   

You can then reference this variable in multiple Functions or Pipelines as needed. When you change the variable value, it will update anywhere the variable is referenced.

Use Case Examples

​

You can personally test these examples within your own Cribl Edge deployment to understand how Cribl evaluates variables.

Expression Example

​

This example shows an expression variable that executes JavaScript logic to get the current time and assign it to a field named nowEpoch. This expression does not require any input arguments, so it gets left blank.

Variable settings:

• Name: epochTime
• Type: Expression
• Value: Date.now()/1000

You could then add an Eval Function to a Pipeline:

• Field Name: nowEpoch
• Value Expression: C.vars.epochTime()

Object Example

​

This example demonstrates how to use an Object variable as a central configuration store (dictionary). You can reference specific keys within the object using dot notation. In this scenario, the goal is to assign the field contact_email a value that is stored in the admin_email key of a global configuration object.

Variable settings:

• Name: my_app_config
• Type: Object
• Value:

{
  "env": "production",
  "retry_count": 3,
  "admin_email": "ops@example.com"
}

You could then add an Eval Function to a Pipeline:

• Field Name: contact_email
• Value Expression: C.vars.my_app_config.admin_email

Array Example

​

This example shows how to use an Array variable to store a list of values (like hostnames) and check if a specific event field exists within that list. In this scenario, the goal is to drop the event if the host field matches any entry in the blocked_hosts list. This will be accomplished with logic that returns false in a filter.

Variable settings:

• Name: blocked_hosts
• Type: Array
• Value: ["bad-host-1", "test-server-99", "retired-asset"]

You could then add a Drop Function to a Pipeline with a Filter value set to: C.vars.blocked_hosts.includes(host).

Additional Examples

​

There are endless possibilities for how to use variables in Cribl Edge. See more examples in the Goat-to Resources and continue sharing use cases with the rest of the Cribl Community on Slack.