Document deprecation/replacement of filters parameter with matches

I believe this commit should properly state that the filters parameter
is getting deprecated/replaced with the matches parameter. This includes
renaming the Filtering-Details.md document to Matching-Details.md, and
changing the wording to be accurate given the new parameter name.

Author: Joel Gerber

README.md

@@ -41,7 +41,7 @@ or
       @type systemd
       tag kube-proxy
       path /var/log/journal
-      filters [{ "_SYSTEMD_UNIT": "kube-proxy.service" }]
+      matches [{ "_SYSTEMD_UNIT": "kube-proxy.service" }]
       read_from_head true
       <storage>
         @type local
@@ -65,11 +65,15 @@ Path to the systemd journal, defaults to `/var/log/journal`
 
 **`filters`**
 
-Expects an array of hashes defining desired filters to apply to all log
-messages. When this property is not specified, this plugin will default to
-having no filters specified.
+_This parameter name is deprecated and should be renamed to `matches`_
 
-See [filtering details](docs/Filtering-Details.md) for a more exhaustive
+**`matches`**
+
+Expects an array of hashes defining desired matches to filter the log
+messages with. When this property is not specified, this plugin will default to
+reading all logs from the journal.
+
+See [matching details](docs/Matching-Details.md) for a more exhaustive
 description of this property and how to use it.
 
 **`pos_file`**

docs/Filtering-Details.md renamed to docs/Matching-Details.md

@@ -1,49 +1,52 @@
-# Filtering Details
+# Matching Details
 
 ## Overview
 
-This application takes an array of hashes passed to the `filters` parameter
+This application takes an array of hashes passed to the `matches` parameter
 within a `systemd` typed source definition in your `fluent.conf` configuration
 file and then parses them into a format understood by `libsystemd`'s journal
 API. The basis behind what `libsystemd`'s API expects can be found documented in
 the `journalctl` [man
 page](https://www.freedesktop.org/software/systemd/man/journalctl.html).
 
+The result of this is that only logs which match the defined set of matching
+rules will be further processed.
+
 ## Usage Information
 
-In order to utilize this plugin's filtering capabilities, you will need to
+In order to utilize this plugin's matching capabilities, you will need to
 understand how this plugin transforms the passed array of hashes into a format
 that is understood by `libsystemd`.
 
 The best way to describe this process is probably by example. The following
 sub-sections lists out various scenarios that you might wish to perform with
-this plugin's filtering mechanism and describes both how to configure them,
+this plugin's matching mechanism and describes both how to configure them,
 while also mapping them to examples from the `journalctl` [man
 page](https://www.freedesktop.org/software/systemd/man/journalctl.html).
 
 ### No Filters
 
-You can leave the `filters` property out altogether, or include a `filters`
-property with an empty array (as shown below) to specify that no filtering
+You can leave the `matches` property out altogether, or include a `matches`
+property with an empty array (as shown below) to specify that no matching
 should occur.
 
-    filters []
+    matches []
 
-Which matches this part of the `journalctl` man page:
+Which coincides with this part of the `journalctl` man page:
 
 > Without arguments, all collected logs are shown unfiltered:
 >
 > `journalctl`
 
 ### Single Filter
 
-You can pass a single hash map to the `filters` array with a single key/value
-pair specified to filter out all log entries that do not match the given
-field/value combination.
+You can pass a single hash map to the `matches` array with a single key/value
+pair specified to only process log entries that match the given field/value
+combination.
 
 For example:
 
-    filters [{"_SYSTEMD_UNIT": "avahi-daemon.service"}]
+    matches [{"_SYSTEMD_UNIT": "avahi-daemon.service"}]
 
 Which coincides with this part of the the `journalctl` man page:
 
@@ -54,17 +57,17 @@ Which coincides with this part of the the `journalctl` man page:
 
 ### Multi-Field Filters
 
-You can pass a single hash map to the `filters` array with multiple key/value
-pairs to filter out all log entries that do not match the combination of all of
-the specified key/value combinations.
+You can pass a single hash map to the `matches` array with multiple key/value
+pairs to only process log entries that match the combination of all of the
+specified key/value combinations.
 
 The passed key/value pairs are treated as a logical `AND`, such that all of the
 pairs must be true in order to allow further processing of the current log
 entry.
 
 For Example:
 
-    filters [{"_SYSTEMD_UNIT": "avahi-daemon.service", "_PID": 28097}]
+    matches [{"_SYSTEMD_UNIT": "avahi-daemon.service", "_PID": 28097}]
 
 Which coincides with this part of the the `journalctl` man page:
 
@@ -74,15 +77,15 @@ Which coincides with this part of the the `journalctl` man page:
 > `journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097`
 
 You can also perform a logical `OR` by splitting key/value pairs across multiple
-hashes passed to the `filters` array like so:
+hashes passed to the `matches` array like so:
 
-    filters [{"_SYSTEMD_UNIT": "avahi-daemon.service"}, {"_PID": 28097}]
+    matches [{"_SYSTEMD_UNIT": "avahi-daemon.service"}, {"_PID": 28097}]
 
 You can combine both `AND` and `OR` combinations together; using a single hash
 map to define conditions that `AND` together and using multiple hash maps to
 define conditions that `OR` together like so:
 
-    filters [{"_SYSTEMD_UNIT": "avahi-daemon.service", "_PID": 28097}, {"_SYSTEMD_UNIT": "dbus.service"}]
+    matches [{"_SYSTEMD_UNIT": "avahi-daemon.service", "_PID": 28097}, {"_SYSTEMD_UNIT": "dbus.service"}]
 
 This can be expressed in psuedo-code like so:
 
@@ -105,7 +108,7 @@ Fields with arrays as values are treated as a logical `OR` statement.
 
 For example:
 
-    filters [{"_SYSTEMD_UNIT": ["avahi-daemon.service", "dbus.service"]}]
+    matches [{"_SYSTEMD_UNIT": ["avahi-daemon.service", "dbus.service"]}]
 
 Which coincides with this part of the `journalctl` man page:
 
@@ -119,7 +122,7 @@ particularly helpful when you want to create aggregate logic
 
 For example:
 
-    filters [{"_SYSTEMD_UNIT": "avahi-daemon.service", "_PID": 28097}, {"_SYSTEMD_UNIT": "dbus.service"}]
+    matches [{"_SYSTEMD_UNIT": "avahi-daemon.service", "_PID": 28097}, {"_SYSTEMD_UNIT": "dbus.service"}]
 
 This can be expressed in psuedo-code like so: