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", "prefix-*"] # requireddatabase = "/path/to/GeoLite2-City.mmdb" # requiredsource = "ip_address" # requiredtarget = "geoip" # optional, default
- commonrequiredstring
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.- Syntax:
literal
- View examples
- Syntax:
- commonrequiredstring
source
The field name that contains the IP address. This field should contain a valid IPv4 or IPv6 address.
- Syntax:
literal
- View examples
- Syntax:
- commonoptionalstring
target
The default field to insert the resulting GeoIP data into. See output for more info.
- Syntax:
literal
- Default:
"geoip"
- View examples
- Syntax:
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"}}
- commonrequiredtable
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.
- Syntax:
literal
- View examples
- Syntax:
- commonrequiredstring
city_name
The city name associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- Syntax:
literal
- View examples
- Syntax:
- enumcommonrequiredstring
continent_code
The continent code associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- Syntax:
literal
- Enum, must be one of:
"AF"
"AN"
"AS"
"EU"
"NA"
"OC"
"SA"
- View examples
- Syntax:
- commonrequiredstring
country_code
The ISO 3166-2 country codes associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- Syntax:
literal
- View examples
- Syntax:
- optionalstring
isp
The name of the Internet Service Provider (ISP) associated with the IP address. Available with the GeoIP2-ISP database.
- Syntax:
literal
- View examples
- Syntax:
- commonrequiredstring
latitude
The latitude associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- Syntax:
literal
- View examples
- Syntax:
- commonrequiredstring
longitude
The longitude associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- Syntax:
literal
- View examples
- Syntax:
- optionalstring
organization
The name of the organization associated with the IP address. Available with the GeoIP2-ISP database.
- Syntax:
literal
- View examples
- Syntax:
- commonrequiredstring
postal_code
The postal code associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..
- Syntax:
literal
- View examples
- Syntax:
- commonrequiredstring
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..
- Syntax:
literal
- View examples
- Syntax:
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
processing_errors_total
The total number of processing errors encountered 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.error_type
- The type of the errorinstance
- The Vector instance identified by host and port.job
- The name of the job producing Vector metrics.
- counter
events_in_total
The total number of events accepted 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.instance
- The Vector instance identified by host and port.job
- The name of the job producing Vector metrics.
- 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
events_out_total
The total number of events emitted 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.instance
- 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
State
This component is stateless, meaning its behavior is consistent across each input.
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.