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

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

    source

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

    • Syntax: literal
  • commonoptionalstring

    target

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

    • Syntax: literal
    • Default: "geoip"

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.

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

      city_name

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

      • Syntax: literal
    • 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"
    • 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
    • optionalstring

      isp

      The name of the Internet Service Provider (ISP) associated with the IP address. Available with the GeoIP2-ISP database.

      • Syntax: literal
    • commonrequiredstring

      latitude

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

      • Syntax: literal
    • commonrequiredstring

      longitude

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

      • Syntax: literal
    • optionalstring

      organization

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

      • Syntax: literal
    • commonrequiredstring

      postal_code

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

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

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.