Geo Dashboard and Geographic location identification in EUM - FAQ

[Gaurav.Soni]

In this article...

• What are the Geo Server and the Geo Dashboard?
• How does it work?
• How do I customize the JavaScript Agent?
• Why do I see "Unknown" for country and region?
• Why do I see all requests resolving to the same Geo location?
• How do I map internal IPs with location?
• What Geo IP database is used by the AppDynamics EUM/Geo Server?
• Why do I need the Geo Server when EUM Server itself can handle Geo mapping?
• Why don't I see some regions of the country?
• How can we increase the brightness of the circle or change the color in the Geo Dashboard?

What does the Geo Server do?

AppDynamics hosts a Geo Server that resolves the user's geographic location based on the IP address reported in the request. See the following documentation for further information:

• Host a Geo Server
• Install and Host a Custom Geo Server for Browser RUM
• The Browser Geo Dashboard View  

NOTE | The Geo Server is not available as an executable at the moment. It's packaged as a web application and needs to be deployed in the TOMCAT_HOME/webapps directory on all the platforms. Because the Geo Server includes war files, it requires the Java servlet and an application server to run them. Tomcat provides this environment.

How does it work?

Both the custom Geo Server and the EUM Server resolve 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.
  If you programmatically modified the Agent, see How do I customize the JavaScript Agent?

• An explicit query parameter.
  For example, http://mycompany.com/geo/resolve.js?ip=196.166.2.1
• An IP provided using the AD-X-Forwarded-For header.
• An IP provided using the X-Real-IP header.
• An IP provided using the X-Forwarded-For header.
• The remote address of the HTTP request.

Once the IP is resolved, the EUM Server fetches the location of the IP by querying the Geo IP database and stores it. The default Geo IP database is Neustar.

How do I customize the JavaScript Agent?

You modify the JavaScript Agent to configure the origin of the request. You can configure the snippet in multiple ways and can use it in conjunction with a custom Geo Server to resolve the location. The following table summarizes different combinations in which you use the JavaScript Agent and a custom Geo Server, and how the EUM Server performs geo resolution in each case.

EUM COMPONENTS	FIELDS IN THE SNIPPET
JavaScript Agent | Populates custom geo from the snippet in the beacon with all the fields configured. EUM Server | Uses the custom geo passed in the beacon to do the geo resolution. Custom Geo server configured? No Description | If all the fields are present, the snippet configuration overrides the custom Geo Server configuration. Implies, the request location is set by the script and is not resolved by the Geo Server.	IP: Yes Country: Yes Region: Yes City: Yes
JavaScript Agent | Populates custom geo from the snippet in the beacon with all the fields configured. EUM Server | Uses the custom geo passed in the beacon to do the geo resolution. Custom Geo server configured? Yes Description | If all the fields are present, the snippet configuration overrides the custom Geo Server configuration. Implies, the request location is set by the script and is not resolved by the Geo Server.	IP: Yes Country: Yes Region: Yes City: Yes
JAVASCRIPT AGENT | No action is taken EUM SERVER | Uses AD-X-Forwarded-For header, X-Forwarded-For header, remote address to do the geo resolution. CUSTOM GEO SERVER CONFIGURED? No DESCRIPTION | If all the fields are present, the snippet configuration overrides the custom Geo Server configuration. Implies, the request location is set by the script and is not resolved by the Geo Server.	IP: Yes Country: Yes Region: Yes City: Yes
JavaScript Agent Uses the response from the custom Geo Server to populate custom geo fields in the beacon. EUM SERVER  will use the response the custom geo passed in the beacon to do the geo resolution. Custom Geo server configured? Yes Description | If all the fields are present, the snippet configuration overrides the custom Geo Server configuration. Implies, the request location is set by the script and is not resolved by the Geo Server.	Some, not all, custom geo fields are configured. NOTE | If only IP is configured, see the corresponding columns below.

Fields in the Snippet				EUM Components			Descripion
IP	Country	Region	City	Custom Geo Server Configured	JavaScript Agent	EUM Server
Yes	Yes	Yes	Yes	No	Populates custom geo from the snippet in the beacon with all the fields configured.	The EUM Server uses the custom geo passed in the beacon to do the geo resolution.	If all the fields are present, the snippet configuration overrides the custom Geo Server configuration. Implies, the request location is set by the script and is not resolved by the Geo Server.
Yes	Yes	Yes	Yes	Yes	Populates custom geo from the snippet in the beacon with all the fields configured.	The EUM Server uses the custom geo passed in the beacon to do the geo resolution.
Some, not all, custom geo fields are configured. Note: If only IP is configured, see the corresponding columns below.				No	No action is taken	The EUM Server uses AD-X-Forwarded-For header, X-Forwarded-For header, remote address to do the geo resolution.	If custom Geo Server is not deployed and not all the fields are configured in the snippet, the header information is used for geo resolution.
Some, not all, custom geo fields are configured. Note: If only IP is configured, see the corresponding columns below.				Yes	Uses the response from the custom Geo Server to populate custom geo fields in the beacon.	The EUM Server will use the response the custom geo passed in the beacon to do the geo resolution.	If custom Geo server is deployed but not all the fields are configured, custom Geo Server configuration overrides the snippet configuration.
Yes	No	No	No	No	Passes the IP address in the beacon.	The EUM Server will use the local IP field to do the geo resolution.
Yes	No	No	No	Yes	Passes the IP address from the snippet to the custom Geo server. The agent uses the response from the Geo Server to populate custom geo field in the beacon.	The EUM Server will: 1. Use the response from the Geo Server to do geo resolution if present. 2. If the response is missing, it uses the local IP field to do the geo resolution. The order is local IP, AD-X-Forwarded-For header, X-Forwarded-For header, and remote address.
No custom geo configuration is  present				No	No action is taken	The EUM Server uses local IP, AD-X-Forwarded-For header, X-Forwarded-For header, and remote address to do geo resolution.	If custom Geo server is not deployed and not all the fields are configured in the snippet, the header information is used for geo resolution.

Why do I see "Unknown" for country and region?

An unknown location occurs when the agent cannot determine the country from which the request originated. One of the most common reasons is that the remote address IP of the HTTP request (beacon) that the EUM server receives is a private IP. The location of the IP can't be resolved through public Geo databases, such as the Neustar GeoIP database. In such cases, you will see the location reported as 'Unknown'.

If your users are internal users and you want to map the internal IP's to geographic locations, you will have to add IP/IP ranges into the geo-ip-mappings.xml file. The file is located in the EUM/eum-processor/bin or the GeoServer/geo directory.

You may also see metrics reported for a location named "Anonymous Proxy". The data for anonymous proxy represents the aggregated metrics from one or more private IP addresses that the JavaScript Agent cannot identify.

Why do I see all requests resolving to the same Geo location when my users make requests from across the globe?

This mostly happens when you have an on-premise EUM fronted with a proxy server, but the proxy server does not forward end-users' IP addresses. Instead, it forwards its own IP along with the beacon request to the EUM Server.

Similarly, sometimes you might also see a group of users from a network reported from one location with one IP. This happens when a firewall/proxy or any network device is not forwarding the IP address of the end-user while passing the beacon. To resolve this, configure the X-Forwarded-For HTTP header field on the network devices that are on the path to the EUM Server.

How do I map internal IPs with location?

If you have internal users and you want to map the internal IPs to geographic locations, add IP or IP ranges to the geo-ip-mappings.xml file. The geo-ip-mappings.xml file is found in the EUM/eum-processor/bin or in the GeoServer/geo directory.

For more information, refer to the documentation listed in What does the Geo Server do?

What Geo IP database is used by the AppDynamics EUM/Geo Server?

The EUM Server by default uses the Neustar IP data file to resolve geographic regions based on IP addresses. This change is effective EUM version 4.4.4.

If you are using Maxmind for geo resolution, which is no longer supported, we recommend switching to Neustar. To switch your geo resolver from Maxmind to Neustar:

1. Download the Neustar data file, neustar.dat from the AppDynamics download site.
2. Copy  neustar.dat to eum-processor/bin.
3. Open eum.properties with a text editor and add the following properties:
   beaconReader.geoDataType=neustar
beaconReader.geoDataFile=bin/neustar.dat  
   
4. Increase the JVM max memory (-Xmx) for the server by at least 800M.
5. Restart the EUM Server.

Why do I need the Geo Server when EUM Server itself can handle Geo-mapping through its internal geo-ip-mappings.xml file?

NOTE | Applicable to only on-prem EUM deployments. SaaS installation does not use the geo-ip-mappings.xml file.

In terms of Geo-mapping functionality, there is not much of a difference between EUM Server and Geo Server. Use the Geo Server in the following instances: 

• 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 users access the application from both a private location and a public one. If a user doesn't come from a specific private IP range mapped by the custom Geo Server, the system can default to the public Geo Server.
• You would like to separate the responsibility and resources for Geo mapping.
• And most importantly, your Controller is on-premises, and you're using the EUM Cloud,  so it is not possible to update the geo-ip-mappings.xml file.

Why don't I see some regions of the country?

There is a definite set of countries and regions that can be mapped to the Geo Dashboard in the Controller. See the list of Browser RUM Countries and Regions. This list can also be used to map the IPs while customizing the geo-ip-mappings.xml file.

How do I adjust the brightness and color of the circle in the Geo Dashboard?

The Geo Dashboard has a map option that can be used to do some level of customization, including:

• Adjusting the range of response time to pick colors accordingly.
• Choosing a metric for circles.
• Setting size of the circle.Map Options

[Pär.Andersson]

Hi, in the docs it says "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."

Is this the only way to install geo server in a Windows enviromennt?

[Gaurav.Soni]

Hi Pär.Andersson,

The geo server is not available as executable at the moment. Its packaged as a web application and need to be deployed in TOMCAT_HOME/webapps, which remains the same for Windows as well.

Regards,

Gaurav Soni

[Alok.Sharma]

Hi,

We don't use TOMCAT in our environment, then how this custom geo application can be configured ? 

Do we have any other way such as installing this application on web servers(http/nginx/apache) ? 

If so, then please share the installation steps.

Regards,

Alok. 

============

As this is having war files, need the java servlet/containers, and hence need some kind of application server. Web server won't provide all the environment.

I have managed to get it installed on tomcat now.

[Gaurav.Soni]

Hi Alok,

"As this is having war files, need the java servlet/containers, and hence need some kind of application server. Web server won't provide all the environment.

I have managed to get it installed on tomcat now."

You are correct here. You will need to get it installed on tomcat.

Regards,

Gaurav