The ipLocation() function adds geolocation data for IPv4 or IPv6 addresses. It adds the following 4 fields (attributes) to the events (ip prefix is default): ip.country, ip.city, ip.lon, and ip.lat.

LogScale includes GeoLite2 data created by MaxMind. By default, the database is automatically updated if the cluster is running with a valid LogScale license.

Note

Updates to the MaxMind database are checked every 5 minutes.

Only the paid version of the MaxMind database includes city information as well as country information. Some IP addresses only show country information regardless of the MaxMind database version used, in case the city information is unknown.

Note

For self-hosted customers, in order to use your own MaxMind database, place it in the LogScale data directory as IpLocationDb.mmdb and run LogScale with environment variable AUTO_UPDATE_IP_LOCATION_DB set to false. Ensure that the database includes city information (for example, GeoLite2 City). For more information, see MaxMind Configuration.

ParameterTypeRequiredDefault ValueDescription
asstringoptional[a]   Name the prefix to add to fields added by the ipLocation function. Defaults to . (the name of the field from which to get the IP address).
field[b]stringoptional[a] ip The field from which to get the IP address.

[a] Optional parameters use their default value unless explicitly set.

[b] The parameter name field can be omitted.

Hide omitted argument names for this function

Show omitted argument names for this function

ipLocation() Syntax Examples

Based on the field ip, the attributes ip.country, ip.city, ip.lon and ip.lat are added to the event. The default field is ip.

logscale
ipLocation()

Based on the field address, the attributes address.country, address.city, address.lon and address.lat are added to the event. The field parameter is used in the following example:

logscale
ipLocation(field=address)

Based on the field ip, the attributes address.country, address.city, address.lon and address.lat are added to the event. The as parameter is used in the following example:

logscale
ipLocation(as=address)

ipLocation() Examples

Click + next to an example below to get the full details.

Retrieve Location Data From Specified Field

Retrieve location data from a specified field using the ipLocation() function

Query
logscale
ipLocation(field=@rawstring)
Introduction

In this example, the ipLocation() function is used with the field parameter to retrieve location data from the @rawstring field. The default prefix value in the field parameter is ip, but with the field parameter

defined as @rawstring, then the prefix will be @rawstring.

Example incoming data might look like this:

@rawstring
165.225.194.1
1.2.3.4
4.3.2.1
8.8.8.8
Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    ipLocation(field=@rawstring)

    Retrieves location data from the @rawstring field, and adds the fields @rawstring.country, @rawstring.city, @rawstring.lon, and @rawstring.lat to the event.

  3. Event Result set.

Summary and Results

The query is used to retrieve location data from the @rawstring field also adding more geolocation information to the events, such as Country, City, Longitude, and Latitude. The function automatically enriches the events with standardized location data, which enables consistent geographic analysis across the logs. This is, for example, useful for detection of suspicious access patterns from unexpected locations.

Sample output from the incoming example data:

@rawstring@rawstring.city@rawstring.country@rawstring.lat@rawstring.lon
165.225.194.1CopenhagenDK55.67412.5696
1.2.3.4<no value>AU-33.494143.2104
4.3.2.1<no value>US37.751-97.822
8.8.8.8<no value>US37.751-97.822