match stage

The match stage is a filtering stage that conditionally applies a set of stageswhen a log entry matches a configurable LogQL streamselector.

Schema

  1. match:
  2.   # LogQL stream selector.
  3.   selector: <string>
  5.   # Names the pipeline. When defined, creates an additional label in
  6.   # the pipeline_duration_seconds histogram, where the value is
  7.   # concatenated with job_name using an underscore.
  8.   [pipieline_name: <string>]
  10.   # Nested set of pipeline stages only if the selector
  11.   # matches the labels of the log entries:
  12.   stages:
  13.     - [
  14.         <regex_stage>
  15.         <json_stage> |
  16.         <template_stage> |
  17.         <match_stage> |
  18.         <timestamp_stage> |
  19.         <output_stage> |
  20.         <labels_stage> |
  21.         <metrics_stage>
  22.       ]

Refer to the Promtail Configuration Reference for theschema on the various other stages referenced here.

Example

For the given pipeline:

  1. pipeline_stages:
  2. - json:
  3.     expressions:
  4.       app:
  5. - labels:
  6.     app:
  7. - match:
  8.     selector: "{app=\"loki\"}"
  9.     stages:
  10.     - json:
  11.         expressions:
  12.           msg: message
  13. - match:
  14.     pipeline_name: "app2"
  15.     selector: "{app=\"pokey\"}"
  16.     stages:
  17.     - json:
  18.         expressions:
  19.           msg: msg
  20. - output:
  21.     source: msg

And the given log line:

  1. { "time":"2012-11-01T22:08:41+00:00", "app":"loki", "component": ["parser","type"], "level" : "WARN", "message" : "app1 log line" }

The first stage will add app with a value of loki into the extracted map,while the second stage will add app as a label (again with the value of loki).

The third stage uses LogQL to only execute the nested stages when there is alabel of app whose value is loki. This matches in our case; the nestedjson stage then adds msg into the extracted map with a value of app1 log line.

The fourth stage uses LogQL to only executed the nested stages when there is alabel of app whose value is pokey. This does not match in our case, sothe nested json stage is not ran.

The final output stage changes the contents of the log line to be the value ofmsg from the extracted map. In this case, the log line is changed to app1 log line.