> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Geoip

> OpenTelemetry processor for Geoip

# Geoip Processor

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@andrzej-stencel](https://github.com/andrzej-stencel), [@michalpristas](https://github.com/michalpristas), [@rogercoll](https://github.com/rogercoll)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/geoipprocessor)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-alpha-blue) ![Metrics](https://img.shields.io/badge/metrics-alpha-green) ![Traces](https://img.shields.io/badge/traces-alpha-orange)

## Overview

## Configuration

To add geographical information, the IP address must be included in the attributes specified by the `attributes` configuration option (e.g., [`client.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/general/attributes.md#client-attributes) and [`source.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/general/attributes.md#source) by default). By default, only the resource attributes will be modified. Please refer to [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/geoipprocessor/config.go) for the config spec.

### Geographical location metadata

The following [resource attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/geoipprocessor/internal/convention/attributes.go) will be added if the corresponding information is found:

* geo.city\_name
* [geo.postal\_code](https://github.com/open-telemetry/semantic-conventions/blob/v1.34.0/model/geo/registry.yaml#L71)
* geo.country\_name
* [geo.country.iso\_code](https://github.com/open-telemetry/semantic-conventions/blob/v1.34.0/model/geo/registry.yaml#L53)
* geo.continent\_name
* [geo.continent.code](https://github.com/open-telemetry/semantic-conventions/blob/v1.34.0/model/geo/registry.yaml#L19)
* geo.region\_name
* [geo.region.iso\_code](https://github.com/open-telemetry/semantic-conventions/blob/v1.34.0/model/geo/registry.yaml#L78)
* geo.timezone
* [geo.location.lat](https://github.com/open-telemetry/semantic-conventions/blob/v1.34.0/model/geo/registry.yaml#L65)
* [geo.location.lon](https://github.com/open-telemetry/semantic-conventions/blob/v1.34.0/model/geo/registry.yaml#L59)

## Configuration

The following settings can be configured:

* `providers`: A map containing geographical location information providers. These providers are used to search for the geographical location attributes associated with an IP. Supported providers:
  * [maxmind](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/geoipprocessor/internal/provider/maxmindprovider/README.md)

* `context` (default: `resource`): Allows specifying the underlying telemetry context the processor will work with. Available values:
  * `resource`: Resource attributes.
  * `record`: Attributes within a data point, log record or a span.

* `attributes` (default: `[client.address, source.address]`): An array of attribute names, which are used for the IP address lookup.

* `error_mode` (default: `propagate`): Determines how the processor reacts to errors that occur while looking up geolocation data for an IP address. Available values:
  * `propagate`: Log the error and return it, halting processing of the telemetry item.
  * `ignore`: Log the error and continue processing (the geolocation attributes are simply not added).
  * `silent`: Continue processing without logging the error.

## Examples

```yaml theme={null}
processors:
    # processor name: geoip
    geoip:
      providers:
        maxmind:
          database_path: /tmp/mygeodb
      context: record
      attributes: [client.address, source.address, custom.address]
```

## Configuration

### Example Configuration

```yaml theme={null}
geoip:
geoip/maxmind:
  providers:
    maxmind:
      database_path: /tmp/db
geoip/maxmind_record_context:
  context: record
  providers:
    maxmind:
      database_path: /tmp/db
geoip/invalid_providers_config:
  providers: "this should be a map"
geoip/invalid_source:
  providers:
    maxmind:
      database_path: /tmp/db
  context: not.an.otlp.context
geoip/invalid_source_attributes:
  providers:
    maxmind:
      database_path: /tmp/db
  attributes: []
geoip/custom_source_attributes:
  providers:
    maxmind:
      database_path: /tmp/db
  attributes: [client.address, source.address, custom.address]
geoip/error_mode_ignore:
  providers:
    maxmind:
      database_path: /tmp/db
  error_mode: ignore
geoip/invalid_error_mode:
  providers:
    maxmind:
      database_path: /tmp/db
  error_mode: not_a_mode
```

***

*Last generated: 2026-07-06*