enrich

GeoIP Transform

The Vector geoip transform accepts and outputs log events, allowing you to enrich events with geolocation data from the MaxMind GeoIP2 and GeoLite2 city databases.

Configuration

vector.toml
[transforms.my_transform_id]
  type = "geoip" # required
  inputs = ["my-source-or-transform-id"] # required
  database = "/path/to/GeoLite2-City.mmdb" # required
  source = "ip_address" # required
  target = "geoip" # optional, default
3 items
  • stringcommonrequired

    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.

    • No default
    • View examples
  • stringcommonrequired

    source

    The field name that contains the IP address. This field should contain a valid IPv4 or IPv6 address. See Field Notation Syntax for more info.

    • No default
    • View examples
  • stringcommonoptional

    target

    The default field to insert the resulting GeoIP data into. See output for more info. See Field Notation Syntax for more info.

    • Default: "geoip"
    • View examples

Fields

example log event
{
  // ...
  "geoip": {
    "city_name": "New York",
    "continent_code": "AF",
    "country_code": "US",
    "latitude": "51.75",
    "longitude": "-1.25",
    "postal_code": "07094",
    "timezone": "America/New_York"
  }
  // ...
}
  • structoptional

    geoip

    The root field containing all geolocation data as sub-fields. See Complex Processing for more info.

    • stringcommonrequired

      city_name

      The city name associated with the IP address.

      • No default
      • View examples
    • stringenumcommonrequired

      continent_code

      The continent code associated with the IP address.

      • No default
      • Enum, must be one of: "AF" "AN" "AS" "EU" "NA" "OC" "SA"
      • View examples
    • stringcommonrequired

      country_code

      The ISO 3166-2 country codes associated with the IP address.

      • No default
      • View examples
    • stringcommonrequired

      latitude

      The latitude associated with the IP address.

      • No default
      • View examples
    • stringcommonrequired

      longitude

      The longitude associated with the IP address.

      • No default
      • View examples
    • stringcommonrequired

      postal_code

      The postal code associated with the IP address.

      • No default
      • View examples
    • stringcommonrequired

      timezone

      The timezone associated with the IP address in IANA time zone format. A full list of time zones can be found here.

      • No default
      • View examples
    • No default

How It Works

Complex Processing

If you encounter limitations with the geoip transform then we recommend using a runtime transform. These transforms are designed for complex processing and give you the power of full programming runtime.

Environment Variables

Environment variables are supported through all of Vector's configuration. Simply add ${MY_ENV_VAR} in your Vector configuration file and the variable will be replaced before being evaluated.

You can learn more in the Environment Variables section.

Field Notation Syntax

The source and target options support Vector's field notation syntax, enabling access to root-level, nested, and array field values. For example:

vector.toml
[transforms.my_geoip_transform_id]
  # ...
  source = "ip_address"
  source = "x-forwarded-for"
  source = "parent.child"
  source = "array[0]"
  # ...

You can learn more about Vector's field notation in the field notation reference.

Support
Contents
Resources