Routes
Before incoming events are transformed by a processing Pipeline, Cribl Stream uses a set of filters to first select a subset of events to deliver to the correct Pipeline. This selection is normally made via Routes.
Don’t Need Routes?
Routes are designed to filter, clone, and cascade incoming data across a related set of Pipelines and Destinations. If all you need are independent connections that link parallel Source/Destination pairs, you can use Cribl Stream’s QuickConnect rapid visual configuration tool as an alternative to Routes.
Accessing Routes
Select Routing > Data Routes from Cribl Stream’s global top nav (single-instance deployments) or from a Worker Group’s/Fleet’s top nav (distributed deployments). To configure a new Route, click Add Route.
How Do Routes Work
Routes apply filter expressions on incoming events to send matching results to the appropriate Pipeline. Filters are JavaScript-syntax–compatible expressions that are configured with each Route. Examples are:
true
source=='foo.log' && fieldA=='bar'
There can be multiple Routes in a Cribl Stream deployment, but each Route can be associated with only one processing Pipeline. (Sources and Destinations can also have their own attached pre-/post-processing Pipelines.)
Each Route must have a unique name. The Route Name field is case-sensitive, so entering the same characters with different capitalization will create a Route with a separate name.
Routes are evaluated in their display order, top‑>down. The stats shown in the Bytes/Events (toggle) column are for the most-recent 15 minutes.
In the example above, incoming events will be evaluated first against the Route named speedtest, then against mtr, then against statsd, and so on. At the end, the default Route serves as a catch-all for any event that does not match any of the other Routes.
Above, note the Events In drop-down menu to toggle between displaying Events versus Bytes, and to display In, Out, or Dropped.
Displayed percentages of Events and Bytes In and Out are by comparison to throughput or filtering across all Routes. For example, if you have four Routes that share an identical filter, each Route’s Events In might show approximately 25%
of the total inbound traffic across all Routes.
Managing the Routes Page
To apply a Route before another, simply drag it vertically. Use the toggles to turn Routes On
/Off
inline, as necessary, to facilitate development and debugging.
You can press the ]
(right-bracket) shortcut key to toggle between the Preview pane and the expanded Routes display shown above. (This works when no field has focus.)
Click a Route’s Options (•••) menu to display multiple options:
- Insert, group, move, copy, or delete Routes.
- Insert comments above or below Routes.
- Capture sample data through a selected Route.
Copying a Route displays a confirmation message and adds a Paste button next to Add Route. Pasting creates an exact duplicate of the Route, with a warning indicator to change its duplicate name.
Comments work like a Pipeline’s Comment Functions: You can use them to describe Routes’ purposes and/or interactions.
Output Destination
You can configure each Route with an Output that defines a Destination to send events to, after they’re processed by the Pipeline.
If you toggle Enable expression to Yes
, the Output field changes to an Output expression field. Here, you can enter a JavaScript expression that Cribl Stream will evaluate as the name of the Destination. Sample expression format: `myDest_${C.logStreamEnv}`
. (This evaluation happens at Route construction time, not per event.)
Expressions that match no Destination name will silently fail.
On Routes within Packs, neither Output control is available, because Packs cannot specify Destinations.
The Final
Toggle
The Final
toggle in Route settings controls what happens to an event after a Route-Pipeline pair matches it.
When Final
is toggled to Yes
(default), the Route “consumes” an event,
meaning the event will not pass down to any other Route below.
When Final
is toggled to No
, the event will be processed by this Route,
and then passed on to the next Route below.
When you toggle Final
to No
, the event sent to the current Route technically becomes a clone of the original event.
The Add Clone button lets you add a fields – names and values – to the cloned events sent to this Route’s Pipeline.
Event Cloning Strategy
Depending on your cloning needs, you might want to follow a most-specific first or a most-general first processing strategy. The general goal is to minimize the number of filters/Routes an event gets evaluated against. For example:
If you don’t need to clone any events (that is, Final
is toggled to Yes
everywhere),
then it makes sense to start with the broadest expression at the top.
This will consume as many events as early as possible.
If you need to clone a narrow set of events, then it might make sense to do that upfront. Then, follow it with a Route that consumes those clones immediately after.
The endRoute
Bumper
The endRoute
bumper appears at the bottom of the Routing table. This is a reminder that, if no Route in the table has the Final
flag enabled, events will continue to Cribl Stream’s configured Default Destination.
This is a backstop to ensure data flow. However, if that configured default is also configured as the Output of a Route higher in the table, duplicate events will reach that Destination.
You can correct this either by setting a Route to Final
, or by changing the Default Destination. The bumper provides a link to the Default Destination’s config, and identifies the currently configured default in parentheses.
Route Groups
A Route group is a collection of consecutive Routes that can be moved up and down the Route stack together. Groups help with managing long lists of Routes. They are a UI visualization only: While Routes are in a group, those Routes maintain their global position order.
Route groups work much like Function groups, offering similar UI controls and drag-and-drop options.
Unreachable Routes
Routes display an “unreachable” warning indicator (orange triangle) when data can’t reach them.
This condition will occur when, with your current configuration, any Route higher in the stack matches all three of these conditions:
- Previous Route is enabled (toggle is set to
On
). - Previous Route is final (Final toggle is set to
Yes
). - Previous Route’s Filter expression evaluates to true, (e.g.,
true
,1 === 1
, etc.).
Note that the third condition above can be triggered intermittently by a randomizing method like Math.random()
. This might be included in a previous Route’s own Filter expression, or in a Pipeline Function (such as one configured for random data sampling).
Routing with Output Router
Output Router Destinations offer another way to route data. These function as meta-Destinations, in that they allow you to send data to multiple peer Destinations based on rules. Rules are evaluated in order, top‑>down, with the first match being the winner.