XML filter plugin

Parses XML content from a field into structured event fields. Supports full tree-to-hash conversion, optional XPath extraction, and namespace handling.

• Package: logstash-filter-xml
• Coverage source: default/bundled
• Official catalog entry: Yes

Plugin overview

xml is used in the Logstash filter stage. Parses XML into structured event fields.

Typical use cases

• Parse incoming log payloads into structured fields for querying and dashboards.
• Transform fields before indexing to keep schema and naming consistent.

Input and output behavior

• Flow: reads a configured source field and writes parsed/transformed output into a target or root fields.
• Input field: source.
• Output target: controlled by target.
• Important options: source, target, force_array, force_content.

Options

Required

• source (type: string; default: none) — Field that contains the XML document to parse.

Optional

• force_array (type: boolean; default: true) — When true, single-element XPath results are stored as single-item arrays for consistency.
• force_content (type: boolean; default: false) — When true, text content and attributes are always parsed into hash values.
• namespaces (type: hash; default: {}) — Map of namespace prefix to URI for namespace-aware XPath expressions.
• parse_options (type: string; default: none) — Parser flags for relaxed or strict handling (for example strict).
• remove_namespaces (type: boolean; default: false) — Strip XML namespaces from parsed element names.
• store_xml (type: boolean; default: true) — When true, store the parsed XML tree under target.
• suppress_empty (type: boolean; default: true) — When true, empty elements are omitted from the output.
• target (type: string; default: none) — Parent field to nest the parsed XML hash under.
• xpath (type: hash; default: {}) — Map of XPath expression to target field for selective extraction.

Example configuration

filter {
  xml {
    source        => "message"
    target        => "[payload][xml]"
    store_xml     => true
    force_array   => false
    suppress_empty => true
    xpath         => {
      "//order/id/text()"       => "[order][id]"
      "//order/customer/text()" => "[order][customer]"
    }
  }
}

Common options configuration

All Logstash filter plugins support these shared options:

• add_field (type: hash; default: {}) — Adds fields when the filter succeeds. Supports dynamic field names and values.
• add_tag (type: array; default: []) — Adds one or more tags when the filter succeeds.
• enable_metric (type: boolean; default: true) — Enables or disables metric collection for this plugin instance.
• id (type: string; default: none) — Sets an explicit plugin instance ID for monitoring and troubleshooting.
• periodic_flush (type: boolean; default: false) — Calls the filter flush method at regular intervals.
• remove_field (type: array; default: []) — Removes fields when the filter succeeds. Supports dynamic field names.
• remove_tag (type: array; default: []) — Removes tags when the filter succeeds.

filter {
  xml {
    add_field => { "pipeline_stage" => "parsed" }
    add_tag => ["parsed", "logstash_filter"]
    enable_metric => true
    id => "my_filter_instance"
    periodic_flush => false
    remove_field => ["tmp_field"]
    remove_tag => ["temporary"]
  }
}

Apply in Logit.io

1. Open your stack in Logit.io and navigate to Logstash Pipelines.
2. In the filter { ... } section, add a xml block.
3. Save your pipeline changes, then restart the Logstash pipeline if prompted.
4. Send sample events and verify parsed/enriched fields in OpenSearch Dashboards.

Validation checklist

• Confirm the xml block compiles without syntax errors.
• Verify expected new/updated fields exist in sample documents.
• Verify unexpected fields are not removed unless explicitly configured.
• Confirm tags added on success/failure align with your alerting and routing rules.

Troubleshooting

• If events are unchanged, verify your filter condition (if ...) matches incoming events.
• If the pipeline fails to start, validate braces/quotes and retry with a minimal filter block.
• If throughput drops, reduce expensive operations and test with representative sample volume.

References

• GitHub package: logstash-filter-xml (opens in a new tab)
• Canonical catalog: /log-management/ingestion-pipeline/logstash-filters-reference