How to integrate and configure geolocation services

Enrich rtcStats sessions with geographic data to understand where quality issues are happening.

Geolocation enrichment adds geographic context to your WebRTC sessions, enabling you to answer questions like "Are users in Southeast Asia experiencing worse quality than users in Europe?" and to visualize your deployment's health on a map.

Why geolocation matters

WebRTC quality is heavily influenced by network conditions, which vary by geography. Geolocation data lets you:

Identify regional issues - spot quality degradation in specific countries
Optimize TURN server placement - see where users are connecting from and whether your relay infrastructure covers them
Support investigations - quickly understand a user's network context when troubleshooting
Dashboard visualizations - build geographic heatmaps of call quality in your BI tools

How geolocation works in rtcStats

Geolocation is handled on rtcstats-server. When data is received from rtcstats-js, the server searches for all IP addresses in order to anonymize them. Right before the anonymization process takes place, the IP address gets geolocated and the resulting data gets added to the rtcstats file.

The actual database used is left for you to deploy and manage. Our own approach is to use MaxMind's GeoIP database loaded locally to the same machine of rtcstats-server. This reduces network use and ensures availability of the geolocation service.

Geolocation tries to return back enrichment data for the IP address that includes the country and city. Note that city may be associated with specific users so it is up to you whether to include that field in queries.

Setting up geolocation for rtcstats

Here's how to setup geolocation in your rtcstats-server instance, step by step:

Step 1: Obtain a geolocation database or API key

Currently only Maxmind is supported. You can create a free API key for the GeoLite2 database here which is usually sufficient: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/

Step 2: Configure rtcstats-server

The configuration YAML file (or the JSON passed in via environment variables should have a maxmind entry specifying the path:

maxmind:
    path: GeoLite2-City.mmd

For deployment the file should be either part of any Docker files you build or downloaded on deployment, e.g. using

wget \
--user=$MAXMIND_ACCOUNT_ID \
--password=$MAXMIND_LICENSE_KEY \
https://download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz -O GeoLite-City.mmdb.tgz && tar -xzf GeoLite-City.mmdb.tgz && mv GeoLite2-City*/GeoLite2-City.mmdb .

Step 3: Verify geolocation data

After configuring geolocation and starting the server, make a call and end it so the data is processed. Then query your database using

SELECT 
  server.created_at, 
  server.blob_url, 
  server.id,
  features_metadata.location_city, 
  features_metadata.location_country, 
  features_metadata.location_continent
FROM "rtcstats-server" AS server
JOIN features_metadata ON features_metadata.dump_id = server.id
ORDER BY server.created_at DESC;

to show the city, country and continent of the call.

You can also group calls by country

SELECT 
  COUNT(*), 
  location_country
FROM "rtcstats-server" AS server
JOIN features_metadata ON features_metadata.dump_id = server.id
GROUP BY location_country;

Step 4: Use geolocation in queries

Once geolocation is active, you can slice your data geographically:

Connection time in a single country, split by type:

SELECT 
  AVG(connection.connection_time) AS connection_time,
  (first_candidate_pair_local_type, first_candidate_pair_remote_type) AS type
FROM "rtcstats-server" AS server
JOIN features_metadata AS metadata ON metadata.dump_id = server.id
JOIN features_connection AS connection ON connection.dump_id = metadata.id
WHERE 
  connection.connection_time IS NOT NULL 
  AND first_candidate_pair_local_type IS NOT NULL 
  AND first_candidate_pair_remote_type IS NOT NULL
  AND location_country = 'DE'
GROUP BY type
ORDER BY connection_time ASC;

This gives you the time to establish the connection split by direct and relayed connections.

Find TURN usage by country

SELECT 
  COUNT(connection.first_candidate_pair_local_type = 'relay' OR connection.first_candidate_pair_remote_type = 'relay') AS relayed,
  COUNT(*) AS total,
  metadata.location_country
FROM "rtcstats-server" AS server
JOIN features_metadata AS metadata ON metadata.dump_id = server.id
JOIN features_connection AS connection ON connection.dump_id = metadata.id
WHERE connection.connection_time IS NOT NULL
GROUP BY metadata.location_country;

This gives you the total and relayed connections grouped by country.

Alternatively you can query the number of sessions using a relay server in a particular country and the country of their public ip address (if known):

SELECT 
  COUNT(*),
  connection.rtcstats_location_country,
  connection.rtcstats_relay_location_country
FROM "rtcstats-server" AS server
JOIN features_metadata AS metadata ON metadata.dump_id = server.id
JOIN features_connection AS connection ON connection.dump_id = metadata.id
WHERE 
  connection.rtcstats_location_country IS NOT NULL 
  AND connection.rtcstats_relay_location_country IS NOT NULL
GROUP BY 
  connection.rtcstats_location_country, 
  connection.rtcstats_relay_location_country;

This allows you to find out if users from a particular country get routed to a TURN server in a different country. Which might be normal e.g. if you only have TURN servers in Frankfurt in Germany and users from France get routed there.

Keeping the database up to date

Geolocation databases change as IP blocks are reassigned. We recommend downloading the database on deployment of rtcstats-server.