Configure the processor_geoip plug-in to convert IP addresses - Simple Log Service

If you use Logtail to collect logs, you can use the processor_geoip plug-in to convert IP addresses in logs to 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. This topic also provides examples on how to configure the plug-in.

Important

Form configuration: Available when collecting text logs and container stdout and stderr.
Editor configuration in JSON: Not available when collecting 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.

Usage notes

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 Processor Type 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.

Configuration example

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

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 type to processor_geoip. Then, configure other parameters in detail 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.

Configuration example

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"
    }
}

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