For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Bindplane docs - GeoIP - image 1

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.

Bindplane docs - GeoIP - image 2

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

Bindplane Resources

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

Last updated

Was this helpful?