README.md

grok

The grok library allows you to quickly parse and match potentially unstructured data into a structed result. It is especially helpful when parsing logfiles of all kinds. This Rust version is mainly a port from the java version which in turn drew inspiration from the original ruby version.

Usage

Add this to your Cargo.toml:

[dependencies]
grok = "2.0"

Here is a simple example which stores a pattern, compiles it and then matches a line on it:

use grok::Grok;

fn main() {
    // Instantiate Grok
    let mut grok = Grok::default();

    // Add a pattern which might be a regex or an alias
    grok.add_pattern("USERNAME", r"[a-zA-Z0-9._-]+");

    // Compile the definitions into the pattern you want
    let pattern = grok
        .compile("%{USERNAME}", false)
        .expect("Error while compiling!");

    //  Match the compiled pattern against a string
    match pattern.match_against("root") {
        Some(m) => println!("Found username {:?}", m.get("USERNAME")),
        None => println!("No matches found!"),
    }
}

Note that compiling the pattern is an expensive operation, so very similar to plain regex handling the compile operation should be performed once and then the match_against method on the pattern can be called repeatedly in a loop or iterator. The returned pattern is not bound to the lifetime of the original grok instance so it can be passed freely around. For performance reasons the Match returned is bound to the pattern lifetime so keep them close together or clone/copy out the containing results as needed.

Further Information

This library depends on onig for its regex execution, which itself is a Rust binding for the powerful Oniguruma regex library. If in doubt why a specific regex doesn't work, this is the best place to look for more information what patterns are supported and how to use advanced features.

License

grok is distributed under the terms of the Apache License (Version 2.0). See LICENSE for details.