README.md in fluent-plugin-rename-key-0.1.3 vs README.md in fluent-plugin-rename-key-0.1.4
- old
+ new
@@ -1,21 +1,22 @@
-# fluent-plugin-rename-key
+# fluent-plugin-rename-key, a plugin for [Fluentd](http://fluentd.org)
## Status
[](http://badge.fury.io/rb/fluent-plugin-rename-key)
[](https://travis-ci.org/shunwen/fluent-plugin-rename-key)
[](https://coveralls.io/r/shunwen/fluent-plugin-rename-key?branch=master)
+[](https://bitdeli.com/free "Bitdeli Badge")
## Overview
-Fluentd Output filter plugin. It goes through each record, rename keys matching the given regular expressions, and re-emit the event with a new tag. This plugin resembles the implementation of [fluent-plugin-rewrite-tag-filter](https://github.com/y-ken/fluent-plugin-rewrite-tag-filter).
+Fluentd output plugin. Renames keys matching the given regular expressions, assign new tags, and re-emits. This plugin resembles the implementation of [fluent-plugin-rewrite-tag-filter](https://github.com/y-ken/fluent-plugin-rewrite-tag-filter).
-This plugin is created to resolve the invalid record problem while converting to BSON document before inserting to MongoDB, see [Restrictions on Field Names](http://docs.mongodb.org/manual/reference/limits/#Restrictions on Field Names) and [MongoDB Document Types](http://docs.mongodb.org/meta-driver/latest/legacy/bson/#mongodb-document-types).
+This plugin is created to resolve the invalid record problem while converting to BSON document before inserting to MongoDB, see [Restrictions on Field Names](http://docs.mongodb.org/manual/reference/limits/#Restrictions on Field Names) and [MongoDB Document Types](http://docs.mongodb.org/meta-driver/latest/legacy/bson/#mongodb-document-types) for more information.
## Installation
-install with gem or fluent-gem command as:
+Install with gem or fluent-gem command as:
```
# for fluentd
$ gem install fluent-plugin-rename-key
@@ -29,56 +30,57 @@
## Configuration
### Syntax
```
-# <num> is a integer, used to sort and apply the rules
+# <num> is an integer, used to sort and apply the rules
# <key_regexp> is the regular expression used to match the keys, whitespace is not allowed, use "\s" instead
# <new_key> is the string with MatchData placeholder for creating the new key name, whitespace is allowed
rename_rule<num> <key_regexp> <new_key>
# Optional: remove tag prefix
remove_tag_prefix <string>
-# Optional: append additional name to the original tag, default **key_renamed**
+# Optional: append additional name to the original tag, default is "key_renamed"
append_tag <string>
-# Optional: dig into the hash structures and rename every matched key or rename only keys at the first level
-# default is true
+# Optional: dig into the hash structure and rename every matched key, or rename only keys at the first level,
+# default is "true"
deep_rename <bool>
```
### Example
Take this record as example: `'$url' => 'www.google.com', 'level2' => {'$1' => 'option1'}`.
To successfully save it into MongoDB, we can use the following config to replace the keys starting with dollar sign.
```
-# At rename_rule1, it matches the key starting the `$`, say `$url`,
+# At rename_rule1, it matches the key starting the '$', say '$url',
# and puts the following characters into match group 1.
-# Then uses the content in match group 1, `url`, to generate the new key name `x$url`.
+# Then uses the content in match group 1, ${md[1]} = 'url', to generate the new key name 'x$url'.
<match input.test>
type rename_key
remove_tag_prefix input.test
append_tag renamed
rename_rule1 ^\$(.+) x$${md[1]}
rename_rule2 ^l(.{3})l(\d+) ${md[1]}_${md[2]}
</match>
```
-The resulting record becomes `'x$url' => 'www.google.com', 'eve_2' => {'x$1' => 'option1'}`
+The resulting record is `'x$url' => 'www.google.com', 'eve_2' => {'x$1' => 'option1'}` with new tag `renamed`.
### MatchData placeholder
This plugin uses Ruby's `String#match` to match the key to be replaced, and it is possible to refer to the contents of the resulting `MatchData` to create the new key name. `${md[0]}` refers to the matched string and `${md[1]}` refers to match group 1, and so on.
-**Note:** Range expression ```${md[0..2]}``` is not supported.
+**Note:** Range expression `${md[0..2]}` is not supported.
## TODO
Pull requests are very welcome!!
## Copyright
Copyright : Copyright (c) 2013- Shunwen Hsiao (@hswtw)
License : Apache License, Version 2.0
+