README.md in fluent-plugin-geoip-0.6.1 vs README.md in fluent-plugin-geoip-0.7.0
- old
+ new
@@ -16,17 +16,20 @@
```bash
# for RHEL/CentOS
$ sudo yum group install "Development Tools"
$ sudo yum install geoip-devel --enablerepo=epel
+$ sudo yum install libmaxminddb-devel --enablerepo=epel
# for Ubuntu/Debian
$ sudo apt-get install build-essential
$ sudo apt-get install libgeoip-dev
+$ sudo apt-get install libmaxminddb-dev
# for OS X
$ brew install geoip
+$ brew install libmaxminddb
```
## Installation
install with `gem` or td-agent provided command as:
@@ -46,11 +49,11 @@
### For GeoipOutput
```xml
<match access.apache>
- type geoip
+ @type geoip
# Specify one or more geoip lookup field which has ip address (default: host)
# in the case of accessing nested value, delimit keys by dot like 'host.ip'.
geoip_lookup_key host
@@ -87,11 +90,11 @@
#### Tips: how to geolocate multiple key
```xml
<match access.apache>
- type geoip
+ @type geoip
geoip_lookup_key user1_host, user2_host
<record>
user1_city ${city["user1_host"]}
user2_city ${city["user2_host"]}
</record>
@@ -105,24 +108,24 @@
It is a sample to get friendly geo point recdords for elasticsearch with Yajl (JSON) parser.<br />
```
<match access.apache>
- type geoip
+ @type geoip
geoip_lookup_key host
<record>
# lat lon as properties
# ex. {"lat" => 37.4192008972168, "lon" => -122.05740356445312 }
- location_properties { "lat" : ${latitude["host"]}, "lon" : ${longitude["host"]} }
+ location_properties '{ "lat" : ${latitude["host"]}, "lon" : ${longitude["host"]} }'
# lat lon as string
# ex. "37.4192008972168,-122.05740356445312"
location_string ${latitude["host"]},${longitude["host"]}
# GeoJSON (lat lon as array) is useful for Kibana's bettermap.
# ex. [-122.05740356445312, 37.4192008972168]
- location_array [${longitude["host"]},${latitude["host"]}]
+ location_array '[${longitude["host"]},${latitude["host"]}]'
</record>
remove_tag_prefix access.
tag geoip.${tag}
# To avoid get stacktrace error with `[null, null]` array for elasticsearch.
@@ -132,11 +135,11 @@
On the case of using td-agent2 (v1-config), it have to quote `{ ... }` or `[ ... ]` block with quotation like below.
```
<match access.apache>
- type geoip
+ @type geoip
geoip_lookup_key host
<record>
location_properties '{ "lat" : ${latitude["host"]}, "lon" : ${longitude["host"]} }'
location_string ${latitude["host"]},${longitude["host"]}
location_array '[${longitude["host"]},${latitude["host"]}]'
@@ -192,20 +195,20 @@
#### configuration
```xml
<source>
- type forward
+ @type forward
</source>
<match test.geoip>
- type copy
+ @type copy
<store>
- type stdout
+ @type stdout
</store>
<store>
- type geoip
+ @type geoip
geoip_lookup_key host
<record>
lat ${latitude["host"]}
lon ${longitude["host"]}
country ${country_code["host"]}
@@ -214,11 +217,11 @@
tag debug.${tag}
</store>
</match>
<match debug.**>
- type stdout
+ @type stdout
</match>
```
#### result
@@ -273,10 +276,12 @@
For more details of geoip data format is described at the page below in section `GeoIP City Edition CSV Database Fields`.<br />
http://dev.maxmind.com/geoip/legacy/csv/
## Placeholders
+### GeoIP legacy
+
Provides these placeholders for adding field of geolocate results.<br />
For more example of geolocating, you can try these websites like [Geo IP Address View](http://www.geoipview.com/) or [View my IP information](http://www.geoiptool.com/en/).
| placeholder attributes | output example | type | note |
|--------------------------------|-------------------|--------------|------|
@@ -289,9 +294,43 @@
| ${dma_code[lookup_field]} | 555 | unsigned int | **only for US** |
| ${area_code[lookup_field]} | 607 | char(3) | **only for US** |
| ${region[lookup_field]} | "NY" | char(2) | A two character ISO-3166-2 or FIPS 10-4 code |
Further more specification available at http://dev.maxmind.com/geoip/legacy/csv/#GeoIP_City_Edition_CSV_Database_Fields
+
+### GeoIP2
+
+You can get any fields in the
+[GeoLite2](http://dev.maxmind.com/geoip/geoip2/geolite2/) database and
+[GeoIP2 Downloadable Databases](http://dev.maxmind.com/geoip/geoip2/downloadable/).
+
+For example(geoip2_c backend):
+
+| placeholder attributes | output example | note |
+|------------------------------------------|--------------------|------|
+| ${city.names.en[lookup_field]} | "Mountain View" | - |
+| ${location.latitude[lookup_field]} | 37.419200000000004 | - |
+| ${location.longitude[lookup_field]} | -122.0574 | - |
+| ${country.iso_code[lookup_field]} | "US" | - |
+| ${country.names.en[lookup_field]} | "United States" | - |
+| ${postal.code[lookup_field]} | "94043" | - |
+| ${subdivisions.0.iso_code[lookup_field]} | "CA" | - |
+| ${subdivisions.0.names.en[lookup_field]} | "California" | - |
+
+For example(geoip2_compat backend):
+
+| placeholder attributes | output example | note |
+|-------------------------------|--------------------|------|
+| ${city[lookup_field]} | "Mountain View" | - |
+| ${latitude[lookup_field]} | 37.419200000000004 | - |
+| ${longitude[lookup_field]} | -122.0574 | - |
+| ${country_code[lookup_field]} | "US" | - |
+| ${country_name[lookup_field]} | "United States" | - |
+| ${postal_code[lookup_field]} | "94043" | |
+| ${region[lookup_field]} | "CA" | - |
+| ${region_name[lookup_field]} | "California" | - |
+
+**NOTE**: geoip2_compat backend supports only above fields.
## Parameters
### GeoipOutput