Enabling Geo Aggregation and Geo Maps

Edge for Private Cloud v. 4.17.05

Geo aggregations lets you collect analytics data for API calls based on geographical attributes such as region, continent, country, and city. From this analytics data, you can view a GeoMap in the Edge UI that shows the location of API requests:

Geo aggregations work by extracting geographical data from a third-party database and adding it to the analytics data collected by Edge. The geographical information can contain the city, country, continent, time zone, and region of a request made to an API proxy.

To use geo aggregation, you must purchase the Maxmind GeoIp2 database that contains this geographical information. See https://www.maxmind.com/en/geoip2-databases for more information.

Enabling geo aggregation

By default the geo aggregations are not enabled. To enable geo aggregations, you must:

• On all Qpid servers, install the MaxMind database and configure the Qpid server to use it.
• Enable the Geo Map display in the Edge UI.

Install the MaxMind database on all Edge Qpid servers

Use the following procedure to install the MaxMind database on all Edge Qpid servers:

1. Obtain the Maxmind GeoIp2 database.
   Note: Geo aggregations work by adding geographical data from a third-party database to the analytics data collected by Edge. To use geo aggregation, you must purchase the Maxmind GeoIp2 database that contains this information. See https://www.maxmind.com/en/geoip2-databases for more information.
2. Create the following folder on the Qpid server node:
   /opt/apigee/maxmind
3. Download the Maxmind GeoIp2 database to /opt/apigee/maxmind.
4. Change the ownership of the database file to the 'apigee' user:
   > chown apigee:apigee /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb
5. Set the permissions on the database to 744:
   > chmod 744 /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb
6. Set the following tokens in /opt/apigee/customer/application/qpid-server.properties. If that file does not exist, create it:
   conf_ingestboot-service_vdim.geo.ingest.enabled=true
   conf_ingestboot-service_vdim.geo.maxmind.db.path=/opt/apigee/maxmind/GeoIP2-City_20160127.mmdb
   
   If you stored the Maxmind GeoIp2 database in a different location, edit the path property accordingly.
   
   Note that this database file contains a version number. If you later receive an updated database file, it might have a different version number. As an alternative, create a symlink to the database file and use the symlink in qpid-server.properties.
   
   For example, create a symlink for "GeoIP2-City-current.mmdb" to "GeoIP2-City_20160127.mmdb". If you later receive a new database with a different file name, you only have to update the symlink rather than having to reconfigure and restart the Qpid server.
7. Change ownership of the qpid-server.properties file to the 'apigee' user:
   > chown apigee:apigee /opt/apigee/customer/application/qpid-server.properties
8. Restart the Qpid server:
   > /opt/apigee/bin/apigee-service/bin/apigee-service edge-qpid-server restart
9. Repeat this process on every Qpid node.
10. To validate that geo aggregation is working:
    1. Trigger several API proxy calls on a sample API proxy.
    2. Wait about 5 - 10 mins for the aggregations to complete.
    3. Open a console and connect to the Edge Postgres server:
       > psql -h /opt/apigee/var/run/apigee-postgresql/ -U apigee -d apigee
    4. Perform a SELECT query on the table analytics.agg_geo to show the rows with geographical attributes:
       apigee=# select * from analytics.agg_geo;
       
       You should see the following columns in the query results which are extracted from the Maxmind GeoIp2 database: ax_geo_city, ax_geo_country, ax_geo_continent, ax_geo_timezone, ax_geo_region.
       
       If the agg_geo table is not getting populated, check the Qpid server logs at /opt/apigee/var/log/edge-qpid-server/logs/ to detect any potential exceptions.

Enable Geo Maps in the Edge UI

Use the following procedure to enable Geo Maps in the Edge UI:

1. Set the following token in /opt/apigee/customer/application/ui.properties to enable Geo Maps. If that file does not exist, create it:
   conf_apigee_apigee.feature.disablegeomap=false
2. Change ownership of the ui.properties file to the 'apigee' user:
   > chown apigee:apigee /opt/apigee/customer/application/ui.properties
3. Restart the Edge UI:
   > /opt/apigee/bin/apigee-service/bin/apigee-service edge-ui restart
4. In the Edge UI, select Analytics > GeoMap to display the geo aggregation data.

Updating the MaxMind GeoIp2 database

MaxMind issues periodic updates to the Maxmind GeoIp2 database. If you receive an updated database, use the following procedure to install it on Edge:

1. Obtain the updated Maxmind GeoIp2 database.
2. Download the Maxmind GeoIp2 database to /opt/apigee/maxmind.
3. Check the name of the database file. If it is the same as the old file, as defined in /opt/apigee/customer/application/qpid-server.properties, proceed to the next step. However, if the file has a different name, you have to edit the qpid-server.properties file to specify the name of the new database file and then restart the Qpid server, as described above.
   
   As an alternative, you can create symlink to the file. For example, create a symlink for "GeoIP2-City-current.mmdb" to "GeoIP2-City_20160127.mmdb". If you later receive a new database with a different file name, you only have to update the symlink rather than having to reconfigure the Qpid server.
4. Change the ownership of the database file to the 'apigee' user:
   > chown apigee:apigee /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb
5. Set the permissions on the database to 744:
   > chmod 744 /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb
6. Restart the Qpid server:
   > /opt/apigee/bin/apigee-service/bin/apigee-service edge-qpid-server restart
7. Repeat this process on every Qpid node.