If you use Logtail to collect logs, you can use the processor_geoip plug-in to convert IP addresses in logs into geographical locations. A geographical location includes the following information: country, province, city, longitude, and latitude. This topic describes the parameters of the processor_geoip plug-in and provides examples on how to configure the plug-in.
Form configuration: You can use form configuration to add the plug-in when you collect text logs or container stdout and stderr.
Editor configuration in JSON: You cannot use editor configuration in JSON to add the plug-in when you collect text logs.
Entry point
If you want to use a Logtail plug-in to process logs, you can add a Logtail plug-in configuration when you create or modify a Logtail configuration. For more information, see Overview of Logtail plug-ins for data processing.
Configuration description
GeoIP databases are not included in the Logtail installation package. You must download and configure a GeoIP database on the server on which Logtail is installed. We recommend that you download a database that can provide the city information of an IP address. For more information, see GeoLite2 Free Geolocation Data.
Make sure that the database file is in the MMDB format.
Form configuration
Parameters
Set the Processor Type parameter to Convert IP Addresses. Then, configure other parameters based on the following table.
Parameter
Description
Original Field
The name of the original field from which you want to convert an IP address.
GeoIP Database Path
The full path of the GeoIP database. Example: /user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb.
Retain Original Field
Specifies whether to retain the original field in the new log that is obtained after parsing.
Report Original Field Missing Error
Specifies whether to report an error if the raw log does not contain the original field.
Report Parsing Failure Error
Specifies whether to report an error if the IP address is invalid or the IP address cannot be found in the database.
Language
The language. Default value: zh-CN.
ImportantMake sure that your GeoIP database can be displayed in the specified language.
Examples
The following example shows how to convert an IP address in a log to a geographical location.
Raw log
"source_ip" : "**.**.**.**"
Logtail plug-in configuration for data processing
Processing result
"source_ip" : "**.**.**.**" "source_ip_province_" : "Zhejiang" "source_ip_city_" : "Hangzhou" "source_ip_province_code_" : "ZJ" "source_ip_country_code_" : "CN" "source_ip_longitude_" : "120.********" "source_ip_latitude_" : "30.********"
Editor configuration in JSON
Parameters
Set the type parameter to processor_geoip. Then, configure other parameters in the detail section based on the following table.
Parameter
Type
Required
Description
SourceKey
String
Yes
The name of the original field from which you want to convert an IP address.
DBPath
String
Yes
The full path of the GeoIP database. Example: /user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb.
NoKeyError
Boolean
No
Specifies whether to report an error if the raw log does not contain the original field. Valid values:
true
false (default)
NoMatchError
Boolean
No
Specifies whether to report an error if the IP address is invalid or the IP address cannot be found in the database. Valid values:
true (default)
false
KeepSource
Boolean
No
Specifies whether to retain the original field in the new log that is obtained after parsing. Valid values:
true (default)
false
Language
String
No
The language. Default value: zh-CN.
ImportantMake sure that your GeoIP database can be displayed in the specified language.
Examples
The following example shows how to convert an IP address in a log to a geographical location.
Raw log
"source_ip" : "**.**.**.**"
Logtail plug-in configuration for data processing
{ "type": "processor_geoip", "detail": { "SourceKey": "source_ip", "NoKeyError": true, "NoMatchError": true, "KeepSource": true, "DBPath" : "/user/local/data/GeoLite2-City_20180102/GeoLite2-City.mmdb" } }
Processing result
"source_ip" : "**.**.**.**" "source_ip_city_" : "Hangzhou" "source_ip_province_code_" : "ZJ" "source_ip_country_code_" : "CN" "source_ip_longitude_" : "120.********" "source_ip_latitude_" : "30.********"