This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation.

Skip to end of metadata
Go to start of metadata

By default, end-users' locations are resolved using public geographic databases. You can host an alternate geo server for your countries, regions, and cities instead of using the default geo server hosted by AppDynamics.

You may prefer to host your own geo server because:

    • you have intranet applications where the public IP address does not provide meaningful location information but the user's private IP does.
    • you have a hybrid application where some users access the application from a private location and some access it from a public one. If a user doesn't come from a specific private IP range mapped by the custom geo server, the system can be set to default to the public geo server.

To host a custom geo server:

  1. Download the Geo Server File
  2. Set the Location of the Geo Server
  3. Create the IP Mapping File


The 4.2 release of the EUM Geo Server adds significant improvements to the installation and functioning of the geo server, reflected in this document. As a result of these changes, the legacy xml mapping file format introduced in 3.6 is no longer supported. You can continue to use the 4.1 version of the geo server if you need to support this format.

Download and Install the Geo Server File

Download the GeoServer.zip file from AppDynamics at https://appdynamics.com/download.

Uncompress the zip to a GeoServer folder with the following structure:

 ├── GeoServer
   ├── schema.xsd                    <-- schema for geo-ip-mapping.xml configuration
   ├── geo
   │   ├── WEB-INF
   │   │   ├── classes
   │   │   │   ├── logback.xml       <-- configure logging in here
   │   │   │   └── ...
   │   │   ├── web.xml               <-- other configurations here
   │   │   └── ...
   |   ├── geo-ip-mappings.xml       <-- configure geo ip mapping here
   └── ...

To install the geo server, copy the geo folder to the TOMCAT_HOME/webapps of your Tomcat server. Do not deploy the server in the same container as the controller.  

(info) The geo server host needs around 2G of memory.

Set the Location of the Geo Server

Enter the URL, including the context root, of your hosted geo server in the Geo Server URL field in the Browser RUM configuration screen in the Controller UI. In the following configuration the context root is "/geo".  

For more information, see Customize Your Browser RUM Deployment.

(warning) If you are using manual injection for your JavaScript agent, you must make sure that the copy of the script that you use is one that you have downloaded after this URL is set.

Create the IP Mapping File

The geo-ip-mappings.xml IP mapping file specifies the locations for which Browser RUM provides geographic data. It maps IP addresses to geographic locations.

Use the sample file in the geo subdirectory as a template. Any modifications at runtime are reloaded without a restart.

This file contains a <mapping> element for every location to be monitored. The file has the following format.

		<subnet from="" mask=""/>
		<location country="United States" region="California" city="San Francisco"/>

	<default country="United States" region="California" city="San Francisco"/>

You can also use IP-range-based mapping instead of subnet-based:

    <ip-range from="" to="" /> 
    <location country="France" region="Nord-Pas-de-Calais" city="ENGLOS" /> 

This data is visible in browser snapshots and can be used to filter browser snapshots for specific locations:The <country>, <region>, and <city> elements are required. If the values of <country> and <region> do not correspond to an actual geographic location already defined in the geographic database, map support is not available for the location in the map panel, but Browser RUM metrics are displayed for the location in the grid view of the geographic distribution, end user response time panel, trend graphs, browser distribution panel, and in the Metric Browser. The <city> element can be a string that represents the static location of the end-user. You will notice a <default> element. If there is an IP address that is not covered by your IP mapping file this is the value that is used. To use a public geo server for non-covered IP addresses, see Using a Hybrid Custom-Public Geo Server Setup.

The valid names for country and region are those used in the map in the geo dashboard. You can hover over a region in the dashboard to see the exact name (including spelling and case) of the region. See The Browser Geo Dashboard View.

Using a Hybrid Custom-Public Geo Server Setup

If you want Browser RUM to evaluate any non-mapped IP address using the public geo server, remove the <default> element.  In this case locating any non-mapped IP address is done in the EUM cloud, not locally.  

Customize File Locations

You can customize where certain files are stored in the GeoServer directory.

Change Log Location

By default logs are written to TOMCAT_HOME/logs, but you can configure this using TOMCAT_HOME/webapps/geo/WEB-INF/classes/logback.xml. Open the file with a text editor and edit the LOG_HOME property.

<property name="LOG_HOME" value="{path-to-file}/logs"/>

Change Mapping File Location

By default the geo server looks for geo-ip-mappings.xml  in TOMCAT_HOME/webapps/geo/.  To change the location, open TOMCAT_HOME/webapps/geo/WEB-INF/web.xml with a text editor and change value for AD_GEO_CONFIG_FILE.

<web-app ...>
    <!-- ... -->
        <!-- ... -->
    <!-- ... -->

(info) In previous versions of the geo server, the enclosing tag was a <context-param>.  This has now been changed to an <init-param>.

For On-Premises EUM Servers Only: Use geo-ip-mappings.xml

If your installation uses an on-premises EUM Server and you have internal browsers from the same network as the Server that you want to identify, instead of setting up a separate custom geo-server, you can choose to simply modify the EUM Server's geo-ip-mappings.xml file as described above.  The sample is in the bin directory of the Server .  The Server automatically reads the file and uses it first to try and resolve the location, before using the MaxMind IP database.  

Precedence in Resolving Locations

The custom geo server resolves locations based on the following precedence, from highest to lowest:

  • An IP address set by customizing the JavaScript agent.  For more information, see Set User-Specified Location Programmatically.
  • An explicit query parameter: for example, http://mycompany.com/geo/resolve.js?ip= 
  • An IP provided using the AD-X-Forwarded-For header
  • An IP provided using the X-Forwarded-For header
  • The remote address of the HTTP request


(info) Because this debugging feature has a small performance impact, it should be turned off before putting the geo server into production. 

To aid in debugging, the geo server ships with a debugging web interface enabled.  You can reach this interface by going to http://host:port/geo/debug with a web browser.

The first tab, Configuration, displays the contents of the mapping file currently in use.

The second tab, History, shows the last few geo resolutions that have been performed.

By default, the last 20 resolutions are shown, but this can be configured in TOMCAT_HOME/webapps/geo/WEB-INF/web.xml.

<web-app ..>
    <!-- ... -->
        <!-- ... -->
    <!-- ... -->

The third tab, Test, can be used to test the mapping file by trying to resolve an arbitrary IP address.

When you first navigate to this tab, it shows the geo resolution for your browser's IP address. The form in this tab can be used to try the resolution of another IP address.

Disabling debug

Open  TOMCAT_HOME/webapps/geo/WEB-INF/web.xml and set DEBUG_ENABLED to false.

<web-app ..>
    <!-- ... -->
        <!-- ... -->
    <!-- ... -->