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

• MaxMind GeoIP2 and GeoLite2 city databases >= 2 is required.

Configuration

• Common
• Advanced

• vector.toml
• vector.yaml
• vector.json

[transforms.my_transform_id]
  type = "geoip" # required
  inputs = ["my-source-or-transform-id", "prefix-*"] # required
  database = "/path/to/GeoLite2-City.mmdb" # required
  source = "ip_address" # required
  target = "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
• commonrequiredstring

  source

  The field name that contains the IP address. This field should contain a valid IPv4 or IPv6 address.

  • Syntax: literal
  • View examples
• commonoptionalstring

  target

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

  • Syntax: literal
  • Default: "geoip"
  • View examples

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
  • commonrequiredstring

    city_name

    The city name associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..

    • Syntax: literal
    • View examples
  • 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
  • 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
  • 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
  • commonrequiredstring

    latitude

    The latitude associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..

    • Syntax: literal
    • View examples
  • commonrequiredstring

    longitude

    The longitude associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..

    • Syntax: literal
    • View examples
  • optionalstring

    organization

    The name of the organization associated with the IP address. Available with the GeoIP2-ISP database.

    • Syntax: literal
    • View examples
  • commonrequiredstring

    postal_code

    The postal code associated with the IP address. Available with the GeoIP2-City or GeoLite2-City database..

    • Syntax: literal
    • View examples
  • 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

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 error

  • instance - 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 error

  • instance - 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.