OpenTelemetry Collector GeoIP Processor

Overview

The GeoIP processor reads an IP address from a configured attribute, looks it up in a local MaxMind database, and writes geographic data back as geo.* attributes on the same record. It supports traces, logs, and metrics. Use these attributes for geographic filtering, dashboards, and alerts in SigNoz.

For processor source and changelog, see the geoipprocessor upstream repository.

Prerequisites

• OpenTelemetry Collector Contrib Distribution: the GeoIP processor ships only in the otelcol-contrib distribution

• MaxMind City database: the processor requires a local .mmdb file. Two options:

  • GeoLite2-City (free): requires a MaxMind account to download. Use the geoipupdate tool to automate downloads.
  • GeoIP2-City (commercial): download from your MaxMind account portal.
  Info

  Only City-type databases work. GeoLite2-Country, GeoIP2-Country, and ASN databases are not supported and will cause a startup error.

  Once downloaded, note the absolute path to the .mmdb file, you'll need it in the config below.

Configure the processor

Configuration has two parts: adding the geoip processor block with a MaxMind database path, and enabling it in each pipeline where you want enrichment. The diagram below shows how data flows through the processor.

Step 1: Add the processor config

Add the following snippet to your existing otel-collector-config.yaml:

processors:
  geoip:
    providers:
      maxmind:
        database_path: /var/lib/GeoLite2-City.mmdb
    context: record      # optional; default is "resource"
    attributes:          # optional; defaults to [client.address, source.address]
      - client.address
      - source.address

Replace /var/lib/GeoLite2-City.mmdb with the path to your .mmdb file.

For a public IP address like 8.8.8.8, the processor writes geo.city_name, geo.country.iso_code, geo.location.lat, geo.location.lon, and more onto the record.

Step 2: Enable in pipelines

Add geoip to the processors list in each pipeline you want to enrich. Place it after memory_limiter and before batch:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, geoip, batch]
      exporters: [otlp/signoz]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, geoip, batch]
      exporters: [otlp/signoz]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, geoip, batch]
      exporters: [otlp/signoz]

Attributes added

When a geo lookup succeeds, the processor writes the following attributes. It skips any field the database doesn't have for that IP, so your record won't contain empty strings.

The processor writes geo.location.lat and geo.location.lon together or not at all.

All names are in English. There is no language configuration option.

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 1000
  geoip:
    providers:
      maxmind:
        database_path: /var/lib/GeoLite2-City.mmdb
    context: record   # use "resource" only if the IP is in a resource attribute
    attributes:
      - client.address
      - source.address
  batch:

exporters:
  otlp/signoz:
    endpoint: "ingest.<region>.signoz.cloud:443"
    tls:
      insecure: false
    headers:
      signoz-ingestion-key: "<your-ingestion-key>"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, geoip, batch]
      exporters: [otlp/signoz]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, geoip, batch]
      exporters: [otlp/signoz]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, geoip, batch]
      exporters: [otlp/signoz]

Validate

Restart your collector after updating the config:

# systemd
sudo systemctl restart otelcol-contrib

# Docker
docker restart <container-name>

Send a trace or log with a known public IP in client.address or source.address. In SigNoz, open the trace or log and check that geo.country.iso_code and related attributes appear on the record.

In the Traces view, select a span and look for geo.* attributes in the span details panel:

In the Logs view, open a log record and confirm the same geo.* attributes are present:

ls -la /var/lib/GeoLite2-City.mmdb

Next Steps

• Collector configuration reference: review receivers, processors, and exporters.
• Switch to Collector: route application telemetry through a central Collector before adding processors.
• Routing Connector: route telemetry to different destinations by service or attribute.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack.

If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.