Custom geographic details
Instana maps end-user IP addresses to geographic details, e.g., city and country names. This is done by inspecting various HTTP headers to retrieve the end-user IP addresses. These IP addresses are then translated to geographic details with the help of Maxmind's geographic databases.
This page describes how to configure custom mapping rules from IP address ranges to geographic details. The main use case for these custom mapping rules are private networks. For example, when accessing (self-hosted) Instana installations through private networks. In such cases, public geographic databases will never contain relevant information and as such the translation process will provide either no results or only wrong/unhelpful results.
For self-hosted Instana installations, make sure that the configurations for end-user monitoring are completed.
Data format
Rules for custom geographic details are always expressed through comma-separated values (CSV). This section describes the technical details of data format as required by both the user-interface and the Web REST API.
CSV format
- Column delimiter:
,
- Quoting character:
"
- Record separator:
\r\n
- The first line must be a header record
- Empty lines are allowed
- Up to 512 rules
Supported columns
network
(required): Either a single IPv4/IPv6 address or an IPv4/IPv6 address range expressed through CIDR notation. Example:84.119.41.64/26
latitude
: Latitude part of the geographic coordinates in decimal degrees. Example:51.5900204
longitude
: Longitude part of the geographic coordinates in decimal degrees. Example:6.1974817
accuracy_radius
: An estimation how accurate the coordinates are in kilometers around latitude/longitude. Example:8
city_name
: Name of the city. Example:Kevelaer
subdivision_1_name
: Name of the least specific subdivision. Commonly used to express information about states. In case of countries containing countries this might also contain the name of contained countries, e.g., England is a country within the country United Kingdom. Example:North Rhine-Westphalia
subdivision_1_iso_code
: Code representation of the subdivision 1. Example:NW
subdivision_2_name
: A more specific subdivision than subdivision 1. Example:Kreis Kleve
subdivision_2_iso_code
: Code representation of subdivision 2. Example:KLE
country_name
: Name of the country. Example:Germany
country_iso_code
: Code representation of the country. ExampleDE
continent_name
: Name of the continent. Example:Europe
continent_code
: Code representation of the continent. Example:EU
Example
network,latitude,longitude,accuracy_radius,city_name,subdivision_1_name,subdivision_1_iso_code,subdivision_2_name,subdivision_2_iso_code,country_name,country_iso_code,continent_name,continent_code
84.119.41.64/26,51.5900204,6.1974817,8,Kevelaer,North Rhine-Westphalia,NW,Kreis Kleve,KLE,Germany,DE,Europe,EU
Configuration through the Web REST API
Get configuration
curl -H "Authorization: apiToken $API_TOKEN" \
-H "Accept: text/csv" \
"https://$UNIT-$TENANT.instana.io/api/website-monitoring/config/$WEBSITE_ID/geo-mapping-rules"
Set configuration
curl -X PUT \
-H "Authorization: apiToken $API_TOKEN" \
-H "Accept: text/csv, application/json" \
-H "Content-Type: text/csv" \
"https://$UNIT-$TENANT.instana.io/api/website-monitoring/config/$WEBSITE_ID/geo-mapping-rules" \
-d 'network,latitude,longitude,accuracy_radius,city_name,subdivision_1_name,subdivision_1_iso_code,subdivision_2_name,subdivision_2_iso_code,country_name,country_iso_code,continent_name,continent_code
84.119.41.64/26,51.5900204,6.1974817,8,Kevelaer,North Rhine-Westphalia,NW,Kreis Kleve,KLE,Germany,DE,Europe,EU'
Configuration through the user interface
The Instana user interface provides means to interact with the Web REST API. It supports downloads and uploads of the aforementioned CSV files for your convenience. The specific view can be found within a website's configuration tab under Custom Geographic Details.