GeoIP

Adds geographical location attributes (such as city, country, and coordinates) to telemetry by looking up IP addresses against a MaxMind GeoLite2 or GeoIP2 database file on the collector host. Lookups read IP addresses from attributes you specify and write the resulting geo attributes to either the resource or the individual record.

Supported Telemetry Types

Logs	Metrics	Traces
✓	✓	✓

Select one or more signals; the same configuration enriches every selected signal. The Database Path, Context, and Attributes settings are shared across all selected signals, not configured per signal.

Prerequisites

This processor requires a MaxMind database file on the collector host:

• A MaxMind GeoLite2 (free) or GeoIP2 (commercial) database in .mmdb format. City databases provide attributes like city, country, and coordinates; ASN databases provide network attributes.
• The .mmdb file must be present on every collector host that runs the processor, at a path the collector process can read.
• Note the absolute path to the file; you will supply it as the Database Path parameter.

Free GeoLite2 databases require a MaxMind account and license key. See the MaxMind documentation linked under Related Resources for downloading and updating database files.

Configuration

Basic Configuration

Selection

Parameter	Type	Required	Default	Description
Choose Telemetry Type	Telemetry Selector	Yes	Logs, Metrics, Traces	The signals this instance enriches. Select one or more; the same configuration applies to each selected signal.
Database Path	String	Yes	—	Absolute path to the MaxMind GeoLite2 or GeoIP2 database file (.mmdb) on the collector host.

Advanced

Parameter	Type	Required	Default	Description
Context	Enum: resource, record	No	resource	Where the GeoIP attributes are written. resource adds them to the resource; record adds them to each individual record.
Attributes	Strings	No	client.address, source.address	Attribute names that hold the IP addresses to look up. Each listed attribute is checked for an IP address to enrich.

Examples

Enrich records with a custom IP attribute and record context

This example reads the IP address from a custom attribute and writes the geo attributes onto each individual record rather than the resource. It sets the advanced Context to record and replaces the default Attributes list with a single custom attribute, network.peer.address. The Database Path points at a GeoLite2 City database on the collector host.

With this configuration, every selected signal whose records carry a network.peer.address attribute is enriched with location attributes resolved from that IP, written directly onto the record.

Configuration Tips

• The Attributes list is checked in order; the first listed attribute that holds a valid IP address is used for the lookup. Keep the most specific or most reliable address attribute first.
• Use record context when different records in the same batch can come from different IP addresses (for example per-request logs). Use resource context when the IP identifies the whole source, such as a host or agent.
• Keep the database file up to date. MaxMind publishes regular updates, and a stale database returns outdated or missing locations.

Troubleshooting

No location attributes are added

Symptoms: telemetry passes through unchanged with no city, country, or coordinate attributes.

Solutions:

1. Confirm the .mmdb file exists at the configured Database Path on every collector host and is readable by the collector process.
2. Verify that at least one of the configured Attributes is present on the telemetry and holds a routable, public IP address. Private and loopback addresses do not resolve to a location.
3. Confirm the database type matches the attributes you expect (a City database for city/country, an ASN database for network attributes).

The collector fails to start or reports a database error

Symptoms: the collector logs an error opening or reading the GeoIP database.

Solutions:

1. Check the path is correct and absolute, and that the file is a valid MaxMind .mmdb database.
2. Ensure the file was fully downloaded and decompressed (.mmdb, not a .tar.gz archive).

Standalone Processor

apiVersion: bindplane.observiq.com/v1
kind: Processor
metadata:
  name: geoip
spec:
  type: geoip
  parameters:
    - name: telemetry_types
      value:
        - Logs
        - Metrics
        - Traces
    - name: database_path
      value: /etc/otel/geoip/GeoLite2-City.mmdb
    - name: context
      value: record
    - name: attributes
      value:
        - network.peer.address

Related Resources

• MaxMind GeoIP2 and GeoLite2 documentation
• Downloading and updating GeoLite2 databases
• GeoIP Processor — OpenTelemetry Collector reference

Bindplane Resources

These enrichment processors add or derive attributes on your telemetry. Chain them to enrich and reshape records:

• Lookup Fields
• Add Fields
• Parse JSON