Skip to main content

Gsub

Filter Elastic Compatible

Synopsis​

Performs pattern-based string replacements using regular expressions.

Schema​

gsub:
  field: <ident>
  pattern: <string>
  replacement: <string>
  description: <text>
  if: <script>
  ignore_failure: <boolean>
  ignore_missing: <boolean>
  on_failure: <processor[]>
  on_success: <processor[]>
  tag: <string>
  target_field: <ident>

Configuration​

FieldRequiredDefaultDescription
fieldY-Source field containing text to modify
patternY-Regular expression pattern to match
replacementY-Text or pattern to replace matches with
descriptionN-Documentation note
ifN-Conditional expression
ignore_failureNfalseSkip processing errors
ignore_missingNfalseSkip if input field missing
on_failureN-Error handling processors
on_successN-Success handling processors
tagN-Identifier for logging
target_fieldNfieldOutput field for modified text

Details​

The processor supports both simple string replacements and complex regex patterns, with the ability to store results in the original field or a new target field.

note

The processor caches compiled regular expressions when dealing with multiple documents with the same pattern. Complex patterns are only compiled once and reused for subsequent matches.

warning

Be careful with complex regular expressions on large text fields, as these may impact performance. Test patterns thoroughly, and consider using simpler patterns when possible.

Examples​

Basic​

Replacing error code in message...

{
  "message": "Error: 404 Not Found"
}
gsub:
  field: message
  pattern: "404"
  replacement: "200"

modifies original field:

{
  "message": "Error: 200 Not Found"
}

Anonymization​

Anonymizing IP addresses in logs...

{
  "log": "2021-04-15 00:00:00 192.168.1.1 GET /index.html - 80 - 192.168.1.100 Mozilla/5.0"
}
gsub:
  field: log
  pattern: "\\b(?:\\d{1,3}\\.){3}\\d{1,3}\\b"
  replacement: "ANONYMIZED"

replaces all:

{
  "log": "2021-04-15 00:00:00 ANONYMIZED GET /index.html - 80 - ANONYMIZED Mozilla/5.0"
}

Keep Original​

Storing the modified text in a new field...

{
  "message": "Error: 404 Not Found"
}
gsub:
  field: message
  pattern: "Error"
  replacement: "Warning"
  target_field: new_message

preserves the original field:

{
  "message": "Error: 404 Not Found",
  "new_message": "Warning: 404 Not Found"
}

Conditionals​

Replacing based on criteria...

{
  "message": "Error: Connection failed",
  "should_process": true
}
gsub:
  field: message
  pattern: "Error"
  replacement: "Warning"
  if: "ctx.should_process == true"

executes the replacement conditionally:

{
  "message": "Warning: Connection failed",
  "should_process": true
}

Error Handling​

Handling missing fields gracefully...

{
  "other_field": "value"
}
gsub:
  field: message
  pattern: "Error"
  replacement: "Warning"
  ignore_missing: true
  on_failure:
    - set:
        field: processing_status
        value: "field_missing"

continues the execution:

{
  "other_field": "value",
  "processing_status": "field_missing"
}