Parameters of the processor_geoip plug-in and the examples on how to configure the plug-in - Simple Log Service

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.

Important

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

Note

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. Important Make 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. Important Make 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.********"