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.

Prerequisites

Set up GeoIP enrichment on your rtcstats-server first if you haven't already. The full setup (MaxMind account, database download, server configuration) is covered in How to enrich rtcstats-server with GeoIP data.

Querying geolocation data

Once GeoIP enrichment is active, you can query your database to verify it's working and start slicing data geographically.

Verify geolocation data

After a call completes and the data is processed, 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;

Slice by geography

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.