New component: geonameprocessor

[antonjim-te]

The purpose and use-cases of the new component

New processor to map from geoname.id into geo location attributes.

• Similar to https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/geoipprocessor
• The generate geo attributes will follow semantic convention https://opentelemetry.io/docs/specs/semconv/attributes-registry/geo/

The geoname data can be accessible from http://www.geonames.org using two approaches:

• Store all the geoname data in memory extracted from a file. More info about the file
  

• Call API to get the geo location info of a geonameID

  • Public Rest API http://api.geonames.org/getJSON?geonameId=<GeoNameID>&username=<username>
    • Example result:

  "geonameId": 5128581,
  "name": "New York",
  "lat": "40.71427",
  "lng": "-74.00597",
  "countryName": "United States",
  "countryCode": "US",
  "population": 8175133,
  "adminName1": "New York",
  "adminCode1": "NY",
  "adminName2": "New York County",
  "timezone": {
    "timeZoneId": "America/New_York",
    "gmtOffset": -5,
    "dstOffset": -4
  },
  "fcode": "PPL",
  "fcl": "P",
  "continentCode": "NA",
  "elevation": null,
  "bBox": {
    "east": -73.7002721,
    "north": 40.9152555,
    "south": 40.496044,
    "west": -74.2557349
  

  • Require to cache geo location data

Example configuration for the component

processors:
    geonameprocessor:
      providers:
          file:
              geonames: /tmp/mygeodb
          api:
              geonames:
                  username: user1
              ttl: 1d
      context: record
      attributes: [geoname.id]

• providers: GeoNames location information providers. It can be configured by file or api
  • file: Access the data from a file
    • geonames: file with the GeoNames table. More info https://download.geonames.org/export/dump/readme.txt
  • api: Access the data from a API
    • geonames: Using the GeoNames API http://www.geonames.org//
      • username: Require username to make request. http://api.geonames.org/getJSON?geonameId=<GeoNameID>&username=<username>
    • ttl: expiration times for data
• 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: An array of attribute names, which contains the geoname.id value.

Telemetry data types supported

metrics, traces, logs

Code Owner(s)

No response

Sponsor (optional)

No response

Additional context

No response

[antonjim-te]

cc @andrzej-stencel @michalpristas @rogercoll as geoipprocessor owners

[jamesmoessis]

So the difference here is that instead of mapping IP address to a location it maps this specific geoname ID?

I wonder if in this case it might be worthwhile adding different keys to the existing geoipprocessor. Instead of using IP as source key you can use geoname ID. I suppose something the codeowners of geoipprocessor can comment on.

@antonjim-te you need an approver or maintainer to sponsor a new component as per: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#adding-new-components

Please reach out in CNCF slack #otel-collector if you need help finding one.

[iblancasa]

I wonder if in this case it might be worthwhile adding different keys to the existing geoipprocessor. Instead of using IP as source key you can use geoname ID. I suppose something the codeowners of geoipprocessor can comment on.

I was thinking about the same. Especially because it seems this processor will add the same kind of attributes than geoipprocessor.

I can see there is a difference between geoipprocessor and the proposed processor in the concept because the name itself contains what is the source of information. Maybe another approach can be proposing to rename the geoipprocessor to a more general name and add more features to it 🤷🏻 .

[michalpristas]

i'm with @iblancasa
i think configuring source of truth in geoip is more viable with less friction. let's just do the change in backwards compatibility friendly way.

[rogercoll]

Extending the geoipprocessor looks good to me too. We could add a new configuration option to let the user define which attributes to decorate the data with (similar to k8s extract::metadata).