Topology & Visitor Stats
The Topology page in kuploy.app shows where your kuploy-cloud instances are running and how much visitor traffic they are serving. Use it to confirm your clusters are reporting, compare reach across instances, and export snapshots for your own reporting.
It rolls up three things for the tenant account you're currently signed in as:
- Clusters — one row per licensed instance, with city/country, coordinates, the last time it checked in, and the number of organizations it hosts.
- Visitor reach — top countries and top cities for the last 30 days, aggregated across all of your instances.
- Sessions over time — a daily line chart for the last 7, 30, or 90 days.
All data is tenant-scoped. You only ever see rows for the instances linked to your own license.
How the data gets there
Each kuploy-cloud instance reports two things during its hourly license sync:
- Cluster location — the city / country / coordinates of the cluster, auto-detected on startup from the cluster's public IP. Stored once per instance and updated if the location changes.
- Visitor summary — pre-aggregated top-countries, top-cities, and session totals for the last 30 days.
The payload is aggregated before it leaves your cluster. Raw IPs and per-user data never leave the instance — only the top-N buckets and counts.
You don't need to configure anything: once a kuploy-cloud instance is licensed and reachable, the data appears in the Topology page after the next sync.
Reading the Topology page
Totals
Four cards at the top:
| Card | What it shows |
|---|---|
| Instances | Number of your instances that have ever reported a location. |
| Organizations | Total orgs across all of your instances. |
| Sessions (30d) | Latest rolling 30-day session count, summed across your instances. |
| Countries reached | Distinct countries seen across all top-country buckets. |
Sessions over time
A line chart of daily visitor sessions. Each point is the latest snapshot reported by every instance on that day, summed. Switch the range with the 7d / 30d / 90d tabs.
If the chart shows "No data yet" for a range, it means no instance has reported visitor stats inside that window.
Top countries / Top cities
Aggregated from each instance's latest visitor summary. The bar length is relative to the largest bucket in the list.
Instances table
| Column | Description |
|---|---|
| Instance | Name you gave the instance at claim time, with its URL underneath. |
| Location | City, country, and lat/lng. "—" if the cluster couldn't geo-locate itself (no outbound internet, private range). |
| Orgs | How many organizations this instance currently hosts. |
| Sessions (30d) | Latest reported 30-day session count for this instance. |
| Last seen | When this instance last successfully reported its location. |
Exporting to CSV
Every table and the time-series chart has an Export CSV button. Files include a UTF-8 BOM so Excel / Numbers open them with correct encoding out of the box.
| Button | File |
|---|---|
| Instances table | topology-instances.csv |
| Sessions over time | topology-sessions-{range}.csv |
Use the CSVs for monthly reporting, board decks, or importing into your own BI tool.
Privacy and data boundaries
What is sent from your cluster to kuploy.app during license sync:
- City / country / coordinates of the cluster (the machine), not of end users.
- Aggregated top-N countries and top-N cities.
- Counts — total sessions, session count per country, per city.
What is not sent:
- Raw IP addresses
- User IDs, session IDs, or request paths
- Org-level breakdowns in the visitor payload
Your clusters' own databases (cloud_cluster_regions, cloud_session_locations) retain the full-resolution data for use inside your own instance (e.g. the landing-page globe). Only the aggregates are mirrored upstream.
Troubleshooting
My instance isn't showing up
- Check the instance is syncing: Settings → License on the kuploy-cloud instance should show a recent
Last synctimestamp. - Check it has a cluster location: on the instance's Postgres,
SELECT * FROM cloud_cluster_regions WHERE is_local = true;should return a row with non-null lat/lng. The location is resolved once at startup; a cluster with no outbound internet won't geo-locate and won't appear on the Topology page. - Wait one sync cycle (up to 1 hour) after a new instance is licensed.
Sessions are stuck at zero
Visitor data comes from cloud_session_locations, which is populated by the landing-page globe's geo-IP pipeline. If the globe isn't enabled or visitors haven't hit a geo-resolved endpoint yet, the sessions value will remain 0 — that's expected, it just means nothing has been aggregated for this instance yet.
Location is wrong
The cluster's geo-IP can look wrong if the egress IP belongs to a cloud region's edge POP (common with managed K8s). You can override the row in cloud_cluster_regions directly — the Topology page mirrors whatever is_local = true row is set. On the next sync the corrected values will appear upstream.