GeoIP Transform
The Vector geoip
transform
enrich events with geolocation data from the MaxMind GeoIP2-City,
GeoLite2-City, GeoIP2-ISP and GeoLite2-ASN databases.
Requirements
Configuration
- Common
- Advanced
- vector.toml
- vector.yaml
- vector.json
[transforms.my_transform_id]type = "geoip" # requiredinputs = ["my-source-or-transform-id"] # requireddatabase = "/path/to/GeoLite2-City.mmdb" # requiredsource = "ip_address" # requiredtarget = "geoip" # optional, default
- requiredstring
database
Path to the MaxMind GeoIP2 or GeoLite2 binary city database file (
GeoLite2-City.mmdb
). Other databases, such as the the country database, are not supported.- View examples
- requiredstring
source
The field name that contains the IP address. This field should contain a valid IPv4 or IPv6 address.
- View examples
- optionalstring
target
The default field to insert the resulting GeoIP data into. See output for more info.
- Default:
"geoip"
- View examples
- Default:
Output
This component outputs log events with the following fields:
{"geoip" : {"autonomous_system_number" : 701,"autonomous_system_organization" : "MCI Communications Services, Inc. d/b/a Verizon Business","city_name" : "New York","continent_code" : "AF","country_code" : "US","isp" : "Verizon Business","latitude" : "51.75","longitude" : "-1.25","organization" : "Verizon Business","postal_code" : "07094","timezone" : "America/New_York"}}
- requiredtable
geoip
The root field containing all geolocation data as subfields. Depending on the database used, either the city or the ISP field is populated. See Supported MaxMind databases for more info.
- optionaluint
autonomous_system_number
The Autonomous System (AS) number associated with the IP address. Zero if unknown. Available with the GeoIP2-ISP or GeoLite2-ASN database.
- View examples
- optionalstring
autonomous_system_organization
The organization associated with the registered autonomous system number for the IP address. Available with the GeoIP2-ISP or GeoLite2-ASN database.
- View examples
- requiredstring
city_name
The city name associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- View examples
- requiredstring
continent_code
The continent code associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- Enum, must be one of:
"AF"
"AN"
"AS"
"EU"
"NA"
"OC"
"SA"
- View examples
- Enum, must be one of:
- requiredstring
country_code
The ISO 3166-2 country codes associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- View examples
- optionalstring
isp
The name of the Internet Service Provider (ISP) associated with the IP address. Available with the GeoIP2-ISP database.
- View examples
- requiredstring
latitude
The latitude associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- View examples
- requiredstring
longitude
The longitude associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- View examples
- optionalstring
organization
The name of the organization associated with the IP address. Available with the GeoIP2-ISP database.
- View examples
- requiredstring
postal_code
The postal code associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- View examples
- requiredstring
timezone
The timezone associated with the IP address in IANA time zone format. A full list of time zones can be found here Available with the GeoIP2-City or GeoLite2-City database..
- View examples
Telemetry
This component provides the following metrics that can be retrieved through
the internal_metrics
source. See the
metrics section in the
monitoring page for more info.
- counter
processed_events_total
The total number of events processed by this component. This metric includes the following tags:
component_kind
- The Vector component kind.component_name
- The Vector component ID.component_type
- The Vector component type.file
- The file that produced the errorinstance
- The Vector instance identified by host and port.job
- The name of the job producing Vector metrics.
- counter
processed_bytes_total
The total number of bytes processed by the component. This metric includes the following tags:
component_kind
- The Vector component kind.component_name
- The Vector component ID.component_type
- The Vector component type.instance
- The Vector instance identified by host and port.job
- The name of the job producing Vector metrics.
How It Works
Supported MaxMind databases
The geoip
transform currently supports the following MaxMind
databases:
- GeoLite2-ASN.mmdb (free) — Determine the autonomous system number and organization associated with an IP address.
- GeoLite2-City.mmdb (free) — Determine the country, subdivisions, city, and postal code associated with IPv4 and IPv6 addresses worldwide.
- GeoIP2-City.mmdb (paid) — Determine the country, subdivisions, city, and postal code associated with IPv4 and IPv6 addresses worldwide.
- GeoIP2-ISP.mmdb (paid) — Determine the Internet Service Provider (ISP), organization name, and autonomous system organization and number associated with an IP address.
The database files should be in the MaxMind DB file format.