Grafana Alloy IP Geolocation and Threat Enrichment for Loki with IPGeolocation.io

Overview

Grafana Alloy can attach IPGeolocation.io data to log lines before they reach Grafana Loki. A stage.geoip block inside loki.process matches the client address against a local IPGeolocation.io MMDB file, and later stages store the results as Loki labels or structured metadata. You then filter, chart and alert on country, VPN use or network owner with ordinary LogQL.

This guide pairs three databases. The IP Geolocation Database supplies country, region, city, coordinates and time zone. The IP Security Database supplies anonymity signals such as VPN, proxy and Tor flags, plus a threat score. The IP to ASN Database supplies the AS number and the organization that runs the network.

Alloy is not limited to those three. stage.geoip reads every IPGeolocation.io IP database: the IP to Country, IP to City and IP to ASN databases, the IP to Company Database, IP Abuse Contact Database, IP WHOIS Database, IP to Hosting Database and Residential Proxy Database, as well as combined databases that merge several of them into one file.

Because the databases are files on the Alloy host, enriching a line needs no network call and adds no usage charge, and client addresses stay in your environment. Comparing an IP geolocation API with a database explains when each one fits.

What you gain in Loki

• Queries by country, VPN use or network. Select streams with a country label, then narrow them with | is_vpn="true" or | asn="9009" on structured metadata.
• A small index. Only the country code becomes a label. Everything else travels as structured metadata, so the number of Loki streams barely grows.
• Panels and alerts straight from LogQL. Metric queries such as requests per country feed Grafana dashboards and alert rules with no extra processing.
• Room to grow. Location, security, ASN, company, ISP, abuse contact, WHOIS, hosting and residential proxy files all plug into the same stage.
• Both IP versions, twelve languages. Lookups accept IPv4 and IPv6 addresses. Place names are stored in Chinese, Czech, English, French, German, Italian, Japanese, Korean, Persian, Portuguese, Russian and Spanish.
• Updates while Alloy keeps running. A small pointer file lets Alloy move to a new database release without a restart.
• Nothing leaves your network. Addresses are matched on the Alloy host, with no API calls and no per-lookup fees.

What teams do with it

• Catch account takeover attempts. Alert when failed logins from VPN, proxy or Tor exits rise above normal.
• Investigate abuse. Pull every line from one AS number or hosting network during an incident, and look up the network's abuse contact in the IP Abuse Contact Database.
• Understand traffic. Build a Grafana panel of requests per country without touching your application.
• Answer data residency questions. Show auditors which countries your users connect from, using data that stays in your own Loki.

What is Grafana Alloy?

Grafana Alloy is Grafana Labs' open source telemetry collector. It is an OpenTelemetry Collector distribution with built-in Prometheus pipelines and native support for Grafana Loki, and it collects metrics, logs, traces and profiles. Grafana's documentation also describes Alloy as the migration path for Promtail and Grafana Agent users.

For logs, Alloy reads files, containers and other sources, processes each line in a loki.process component, and sends the result to Loki. Adding IP context to logs inside that component means every line arrives in Loki ready to filter, chart and alert on.

How it works

1. A stage such as stage.json or stage.regex extracts the client IP address from the log line into a named value, for example client_ip .
2. Each stage.geoip block opens one MMDB file, looks up the address in source , and stores one value for each entry in custom_lookups .
3. stage.labels turns chosen values into Loki labels, and stage.structured_metadata attaches the rest to the log line.
4. The line continues to loki.write , which sends it to Loki.

Each stage.geoip block reads one file, so you add one block per database file.

1{
2  "location": {
3    "city": {
4      "name": {
5        "en": "Secaucus",
6        "de": "Secaucus"
7      }
8    },
9    "coordinates": {
10      "latitude": "40.78834",
11      "longitude": "-74.05502"
12    },
13    "country": {
14      "code2": "US",
15      "name": {
16        "en": "United States"
17      }
18    },
19    "state": {
20      "name": {
21        "en": "New Jersey"
22      }
23    }
24  },
25  "time_zone": "America/New_York"
26}

Requirements

Quick start

This walkthrough runs Alloy in Docker against a one-line log file and prints the enriched entry, so you can see the enrichment working in a few minutes without Loki. The pipeline reads location, security and ASN data from three database files.

1databases/
2├── db-ip-asn.mmdb
3├── db-ip-location.mmdb
4└── db-ip-security.mmdb
5logs/
6└── app.log

mkdir -p logs
printf '{"remote_addr":"37.120.202.92","method":"POST","path":"/login"}\n' > logs/app.log

local.file_match "app" {
  path_targets = [{"__path__" = "/var/log/app/*.log", "job" = "app"}]
}

loki.source.file "app" {
  targets       = local.file_match.app.targets
  forward_to    = [loki.process.ipgeo.receiver]
  tail_from_end = false
}

loki.process "ipgeo" {
  forward_to = [loki.echo.out.receiver]

  stage.json {
    expressions = { client_ip = "remote_addr" }
  }

  stage.geoip {
    source = "client_ip"
    db     = "/usr/local/share/ipgeolocation/db-ip-location.mmdb"
    custom_lookups = {
      "country_code" = "location.country.code2",
      "country_name" = "location.country.name.en",
      "region"       = "location.state.name.en",
      "city"         = "location.city.name.en",
      "latitude"     = "location.coordinates.latitude",
      "longitude"    = "location.coordinates.longitude",
      "time_zone"    = "time_zone",
    }
  }

  stage.geoip {
    source = "client_ip"
    db     = "/usr/local/share/ipgeolocation/db-ip-security.mmdb"
    custom_lookups = {
      "threat_score" = "threat_score",
      "is_vpn"       = "is_vpn",
      "is_proxy"     = "is_proxy",
      "is_tor"       = "is_tor",
      "is_anonymous" = "is_anonymous",
    }
  }

  stage.geoip {
    source = "client_ip"
    db     = "/usr/local/share/ipgeolocation/db-ip-asn.mmdb"
    custom_lookups = {
      "asn"             = "asn.as_number",
      "as_organization" = "asn.organization",
    }
  }

  stage.labels {
    values = { country_code = "" }
  }

  stage.structured_metadata {
    values = {
      country_name    = "",
      region          = "",
      city            = "",
      latitude        = "",
      longitude       = "",
      time_zone       = "",
      threat_score    = "",
      is_vpn          = "",
      is_proxy        = "",
      is_tor          = "",
      is_anonymous    = "",
      asn             = "",
      as_organization = "",
    }
  }
}

loki.echo "out" { }

docker run --rm \
  -v "$PWD/databases":/usr/local/share/ipgeolocation:ro \
  -v "$PWD/logs":/var/log/app:ro \
  -v "$PWD/config.alloy":/etc/alloy/config.alloy:ro \
  grafana/alloy:v1.20.1 run /etc/alloy/config.alloy --storage.path=/tmp/alloy

1{country_code="US", filename="/var/log/app/app.log", job="app"}

1{
2  "as_organization": "M247 Europe SRL",
3  "asn": "9009",
4  "city": "Secaucus",
5  "country_name": "United States",
6  "is_anonymous": "true",
7  "is_proxy": "true",
8  "is_tor": "false",
9  "is_vpn": "true",
10  "latitude": "40.78834",
11  "longitude": "-74.05502",
12  "region": "New Jersey",
13  "threat_score": "50",
14  "time_zone": "America/New_York"
15}

Sending the data to Loki

Replace loki.echo with loki.write , and point forward_to at it:

loki.process "ipgeo" {
  forward_to = [loki.write.default.receiver]

  // ... the same stages as in the quick start ...
}

loki.write "default" {
  endpoint {
    url = "http://loki:3100/loki/api/v1/push"
  }
}

Change the URL to your Loki address. For Grafana Cloud, use the push URL and credentials from your stack.

Querying enriched logs in Loki

Once the data is in Loki, filter on the label and the structured metadata in LogQL. These queries work in Grafana Explore, in dashboards and in alert rules.

Requests from one country (label):

{job="app", country_code="US"}

Requests from VPN exits (structured metadata):

{job="app"} | is_vpn="true"

Requests from any anonymizing network, such as a VPN, proxy or Tor:

{job="app"} | is_anonymous="true"

Requests with a threat score of 50 or more:

{job="app"} | threat_score >= 50

Requests per country over the last hour, for a dashboard panel:

sum by (country_code) (count_over_time({job="app"}[1h]))

Anonymous requests per country over five minutes, for an alert rule:

sum by (country_code) (count_over_time({job="app"} | is_anonymous="true" [5m]))

Enriching a web server access log

Nginx and Apache write access logs as plain text, not JSON. Use stage.regex to pull the client IP out of each line. This configuration reads the Nginx access log, enriches each request and keeps the HTTP status:

local.file_match "nginx" {
  path_targets = [{"__path__" = "/var/log/nginx/access.log", "job" = "nginx"}]
}

loki.source.file "nginx" {
  targets    = local.file_match.nginx.targets
  forward_to = [loki.process.ipgeo.receiver]
}

loki.process "ipgeo" {
  forward_to = [loki.echo.out.receiver]

  stage.regex {
    expression = `^(?P<client_ip>\S+) \S+ \S+ \[[^\]]+\] "(?P<method>\S+) (?P<path>\S+) [^"]*" (?P<status>\d{3})`
  }

  stage.geoip {
    source = "client_ip"
    db     = "/usr/local/share/ipgeolocation/db-ip-location.mmdb"
    custom_lookups = {
      "country_code" = "location.country.code2",
      "city"         = "location.city.name.en",
    }
  }

  stage.labels {
    values = { country_code = "" }
  }

  stage.structured_metadata {
    values = { city = "", status = "" }
  }
}

loki.echo "out" { }

The expression uses a raw string (between backticks), so the backslashes need no escaping. For the line 37.120.202.92 - - [06/Oct/2026:10:15:32 +0000] "POST /login HTTP/1.1" 401 512 "-" "Mozilla/5.0" , the entry gets the label country_code="US" and the structured metadata city="Secaucus" and status="401" .

Behind a load balancer or CDN, Nginx records the proxy as the client unless you tell it otherwise. Enable the real_ip module, or your proxy's equivalent, so the first field holds the visitor's address. Finding the real client IP behind a proxy covers the headers involved.

Working with the values

Alloy hands every value to Loki as a string. LogQL can still compare numbers, as the threat score query above shows.

Lists. Provider names, such as vpn_provider_names , are lists. A path that points at a whole list or a group returns no value, without an error. Use a JMESPath expression to turn the list into a string:

    custom_lookups = {
      "vpn_provider"  = "vpn_provider_names[0]",
      "vpn_providers" = "join(', ', vpn_provider_names || `[]`)",
    }

vpn_provider_names[0] returns the first name. The join expression returns every name, separated by commas, and the || `[]` part keeps it from logging an error for addresses that are not in the database.

Other languages. Every name group holds translations keyed by language code. Swap en for cs , de , es , fa , fr , it , ja , ko , pt , ru or zh ; missing translations come back as empty strings.

Running in production

• Keep labels few. Make only low-cardinality values, such as country_code , into labels. Put everything else in structured metadata.
• Look up the visitor, not the proxy. Make sure the field you extract holds the address of the person or system that made the request.
• Keep a persistent storage path. Alloy records how far it has read each file under --storage.path . Keep that directory across restarts, and Alloy resumes where it stopped instead of reading files again.
• Kubernetes. Put the databases in a volume and mount it read-only at the same path in every Alloy pod.
• Plan for new releases. Pick one of the two update methods below before you go live.

Keeping the databases up to date

New database releases arrive daily or weekly, depending on your plan. Alloy opens each file when the stage starts and keeps reading that copy. A configuration reload ( POST /-/reload or SIGHUP ) does not reopen it while the configuration is unchanged. Use one of these two methods.

local.file "security_db" {
  filename = "/usr/local/share/ipgeolocation/db-ip-security.current"
}

loki.process "ipgeo" {
  // ...

  stage.geoip {
    source = "client_ip"
    db     = "/usr/local/share/ipgeolocation/" + string.trim_space(local.file.security_db.content)
    custom_lookups = {
      "is_vpn"       = "is_vpn",
      "is_anonymous" = "is_anonymous",
    }
  }

  // ...
}

#!/bin/sh
# Install a new IPGeolocation.io database release for Grafana Alloy without a restart.
set -eu

DB_DIR=/usr/local/share/ipgeolocation
DOWNLOAD_URL="<MMDB download link from your IPGeolocation.io account>"
STAMP=$(date +%Y%m%d%H%M%S)

# 1. Unpack the release in a temporary folder beside the live databases.
WORK=$(mktemp -d "$DB_DIR/.release.XXXXXX")
trap 'rm -rf "$WORK"' EXIT
curl -fsSL -o "$WORK/release.zip" "$DOWNLOAD_URL"
# -DD stamps the unpacked files with the current time, not the archive's.
unzip -q -DD "$WORK/release.zip" -d "$WORK"
rm "$WORK/release.zip"

# 2. Stop if any file fails its checksum or any database is damaged.
(cd "$WORK" && sha256sum --quiet -c checksum.txt)
for db in "$WORK"/*.mmdb; do
    mmdbio verify --db "$db"
done

# 3. Give each database a dated name and point Alloy at it.
for db in "$WORK"/*.mmdb; do
    name=$(basename "$db" .mmdb)
    mv "$db" "$DB_DIR/$name-$STAMP.mmdb"
    printf '%s\n' "$name-$STAMP.mmdb" > "$DB_DIR/.$name.current.new"
    mv "$DB_DIR/.$name.current.new" "$DB_DIR/$name.current"

    # 4. Delete older copies of this database, keeping the new one and the one before it.
    ls -1t "$DB_DIR/$name"-[0-9]*.mmdb | tail -n +3 | xargs -r rm -f
done

Troubleshooting

No values at all, and no errors. Check these in order:

• db_type is set. Remove it and use custom_lookups .
• A path is misspelled, or points at a group or a list instead of a single value. For example, location.country.name needs a language at the end: location.country.name.en . Alloy skips such lookups without an error.
• The source value is empty because the IP was not extracted. Check the stage.json or stage.regex expression. Alloy only reports this at debug level, as failed to convert source value to string .

Values for some lines but not others. The database has no entry for the missing addresses. The mmdbio tool prints the record a database holds for any address:

mmdbio read --db /usr/local/share/ipgeolocation/db-ip-location.mmdb --ip 37.120.202.92

source is not an ip . The extracted value is more than one address, such as the X-Forwarded-For value 203.0.113.7, 10.0.0.1 , or an address followed by a port. Adjust the extraction so it captures the client address alone.

failed to search JMES expression . A JMESPath function, such as join , received no value because the address is not in the database. Add a default, as in join(', ', vpn_provider_names || `[]`) .

Alloy fails to start with invalid stage config open ...: no such file or directory . Alloy cannot open the file named in db . Check the spelling and permissions, and when Alloy runs in a container, use the path as the container sees it.

New data does not show up after an update. Alloy still has the old file open, and a configuration reload does not reopen it. Restart Alloy, or switch files with a pointer file as described above.

FAQ

Related

• IPGeolocation.io MMDB field reference
• IP Geolocation Database documentation
• IP Security Database documentation
• IP to ASN Database documentation
• IP to Company Database documentation
• Enrich logs with IPGeolocation.io in Fluent Bit
• Enrich logs with IPGeolocation.io in Vector
• IPGeolocation.io Nginx module for MMDB databases
• All IPGeolocation.io integrations