Technical FAQ


How does the Countly platform work?

After you install the Countly SDK on your application, the users of this application will start sending event data to the Countly server. Countly gathers information from these events regarding their actions, how they behave, which operator they are on, etc.

With which language is Countly written?

We are using Node.js and MongoDB. Both the backend and frontend are completely written in JavaScript. You may take a look at the API code, which collects data from client SDKs and writes this data to the database.

How are event and session data sent to Countly?

As the user opens the application, the Countly SDK starts collecting data the way you define. Events and sessions are collected and then sent to the Countly (or your) servers using an HTTPS request every 60 seconds for mobile SDKs, and every 500 milliseconds for web SDKs.

Note that you should see session data on your dashboard as soon as the app launches. However, for custom events, you will need to wait for the next tick, which occurs every 60 seconds. If you record more than 10 different events inside the app, it won’t even wait for the next tick, instead sending them immediately.

Does Countly show my data in real time?

All reports and charts are shown in real time. There are no batch processes running in the background to visualize or collect data, so you won't have to wait for the next process to run.

Will Countly slow down my mobile application?

Our lightweight SDK works asynchronously and doesn't block any function calls inside your code. Profiling for iOS shows that SDK has a 2% overhead on total CPU usage. Compared to the high CPU and data consumption for services that send in-app video, this is clearly an advantage.

Our tests with an Android profiler prove Countly takes up less than 0.1% of your CPU time for a single CPU core in a typical usage scenario of a 5-minute session where 5 events and 8 requests are sent. This number will be lower than 0.1% for more CPU cores.

What happens if the SDK cannot send requests?

If your mobile application cannot send event information (mainly due to the fact that the device is not connected to the internet, the user is on a plane or currently underground in the metro), then this information is stored in non-volatile memory. As soon as the connection is established, it's sent to the server and the data is removed from the queue.

I integrated the SDK, but cannot see, or can only partially see, data on the dashboard

There are a few steps to check when you integrate your Countly SDK and have a problem viewing data.

1. Enable debug logging in the SDK

First, we need to understand if the SDK is working properly and whether it is sending data to the server and if the server is accepting it. Check if requests are being created - meaning check whether you are calling SDK methods to actually send information to the server and that the SDK has been implemented correctly.

Also check if requests fail or are successfully sent to the server, because if they fail, maybe the server is not reachable from this specific network, or you made a mistake when providing the URL to the server.

2. Check if the SDK requests are arriving to the server

Please check under Utilities > Request Logs to see that your server is indeed receiving data from the SDK and see if there are any errors/problems displayed alongside your requests. Should there be an issue, the request logs usually state what this problem is about, why the request was not processed, or why incoming data may be incorrect - such as sending data for the incorrect app type, sending duplicate requests, incorrectly set-up parameter tampering, etc.

You may also click on any button on the top right-hand side of the screen in the Request Logs to filter down different types of data, such as sessions, events, metrics, user details, and crashes.

3. Check the server for errors

Check countly/log/countly-api.log for errors. Chances are there is a problem/bug with a specific plugin processing information, so you should recheck if there are any new errors in the log.

4. Check host URL

You may be using the wrong host URL. Assure your host URL is in the form of http://SERVER_URL or https://SERVER_URL .

5. Check app key

You may be using the wrong App key. Assure you are using the App key in your application, and not the API key. If you use the API key, then you also won’t be able to see requests under Utilities > Request logs.

6. Check Filtering rules

Events or requests may be blocked. In this case, check Management > Filtering rules (previously named Blocking Rules) to see whether there are any rules that block events or any requests.

7. Check event limits

The event name limit may be exceeded (the limit is 500, by default), and may be adjusted under Management > Configurations > API > Max unique event key.

8. Check time zone

Your time zone may be different from the application’s time zone, explaining why it takes some time for you to be able to see events on the graph, something which should be available to you without delay.

How many users can a Countly server handle?

A high-end server can handle several hundreds of events per second. For more information, see the deployment scenarios for potential installation methods for different traffic levels. 

Are there any video tutorials for installing and configuring Countly?

There are several videos on the Countly YouTube channel. Click here to go directly to these videos.

Where should I put my Countly start code for Android?

In as many activities as you are able, preferably in each activity.

When I compare different analytics providers’ data, I see slight differences. What might be the reason for this?

There are a few reasons for data discrepancy among analytics providers:

  1. Users may download the application and open it when they do not have network access. In this case some analytics providers may choose to discard the events, while others choose to store it. Countly stores it, for example, and as soon as the user regains internet connection, the event is sent again.
  2. Users with jailbroken iPhones may have analytics disabled. In this case, the data is never sent. Also, if a user chooses not to send analytics feedback for his/her iOS device, it's not possible to report data to iTunes.
  3. A user may download the application once, but run it on multiple devices, or may download the app multiple times, but run it on the same device. In this case, Google Analytics and other analytics services may count that user differently.
  4. Some services (e.g. Google Analytics) may sample data, e.g. discard it if the traffic is over their internal limit.
  5. Countly counts new users as unique device IDs, meaning if a user downloads the same app to their iPhone and iPad, it's counted twice. Apple's iTunes service only counts it once.
  6. SDKs may have issues with running in different environments. For example, it may send improper encoding, resulting in the server not parsing it. We see such behavior especially in Asian markets with some Asian languages using different encoding types.
  7. Some of the iOS and Android platforms are old and unsupported by analytics providers. In this case, if a platform is supported by one provider and not other, then a discrepancy may occur as the SDK will gracefully fail on the unsupported platform.
  8. Different analytics services have different time-zone configurations. This directly affects how daily sessions, daily unique users, daily active users, and retention tables are calculated.

Other than the possibilities mentioned above, improper integration of the SDK may cause data discrepancy on the server side, as seen below:

  • If the SDK is integrated in a different way than what is shown in the official documentation,
  • If initialization of the SDK depends on any state on a device,
  • If the SDK is being used in a non-native application environment,
  • If the SDK’s original source code is modified,
  • If more than one instance of the SDK is attempted to run at the same time.

Unfortunately, we do not know how the backend and SDK side works for closed proprietary services. However, Countly's SDK, data collection, storage, and visualization methods and database model are completely open source, and it's possible to retrieve stored raw data either via REST API, or via MongoDB commands.

With that said, we have run several unit and stress tests to make sure no data is lost during transmission, and we are very confident with our codebase. In the event you would like to have a separate discussion about how we collect, store, and visualize data, we are always happy to hear from you.

In which situations does a device ID reset?

There are some cases in which a device ID may be reset. You can see a breakdown of the platform and when a device ID may reset below.

Does device id change? App upgrade App Reinstall App Reset Device Reset
Android Open UDID no sometimes sometimes yes
Android Advertising ID no if reset by the user in OS settings if reset by the user in OS settings yes
iOS IDFV no if it is the only app from developer N/A yes

What is the hostname meant to write inside the SDK?

Inside the SDK you'll see the API HOST directive that you need to fill in. This is the same as the IP or hostname of your server. For example, if you have Countly installed on, then inside the SDK you will need to write If there is a server name associated with your IP, the server name may also be used (e.g.

Why do events take time to appear on my dashboard, instead of appearing in real time?

Due to time-zone differences (the time zone in which the event takes place on a device and the time zone of the app setting in the dashboard), there may be cases while converting a timestamp to your app's time zone that the events are added in real time to the timelines, albeit with an hour delay. The delay may also depend on the devices and SDKs. For example, if a device is offline, the requests are queued and then synced with the Countly server. Since a recorded event’s timestamps will be in the past, new added events will count as past events in the dashboard.

What are some industry-specific custom events to track?

Most of the basic events in your mobile applications and websites are similar, but some events specifically for a domain may provide more insights for your product.

We have created predefined events and shown you what kind of insights those events will give you:

How can I see how many datapoints our platform consumes?

Datapoints include sessions, custom events, information sent when a crash occurs, or when a user responds back to a push notification. Those datapoints are automatically calculated and reported under Utilities > Data Points.

You may view the sample screenshot below. Clicking on each of the months will give you the number of datapoints consumed by each application as well as all datapoints under the title "All apps".

What is the average disk-data usage per event?

As a simple example, a request carrying 10 events, where each event has 10 segments, will total around 8KB. If this is a single event with 10 segments in a single request, it totals around 1KB. The size depends on various factors, such as the length of the event keys, the length of the segment keys, and the values. Basically, a reasonable event request will total around 1KB.

Other than that,

  • A request to change/add user properties would total around 1KB for 10 properties.
  • A standard begin session request will also total around 1KB.

Basically, any extra event segment and user property will affect the data transfer volume, but to which amount is dependent on the size of the segment and user property. Roughly speaking, each 1M requests will cause a data transfer of 1GB, however we have customers storing less than that, and significantly more than that.

By default, SDKs send data over to the server every minute or whenever the internal queue size reaches 10 (may vary based on the SDK), and these values are configurable. In a scenario where it is okay to get data with a delay and you’d like to save bandwidth, we recommend increasing these numbers, as the HTTP request itself has an overhead, thus sending the results in bulk in bandwidth savings. Obviously, keeping numbers of events, segments, and user properties low will lower the volume.

I enable a plugin, but can't see its effect on the dashboard

You will still see the old (previous) dashboard when caching services (CloudFlare, for example), cache pages, and when you make a change to the server code (e.g. by enabling plugin). If this is the case for you, simply flush your cache service and you will be able to see the new plugin functionality.

I reinstalled Countly and need to create an app using the previous key. How can I do this?

If you reinstalled Countly and need the app key in order to create another application with the same key used by your previous applications, follow the steps below:

  1. Login to your server shell
  2. Connect to mongodb as follows: mongo countly
  3. Execute db.apps.find()
  4. Find the ID of the application that you want to modify
  5. Execute the update as follows: db.apps.update({id: "ID_YOU_GOT_FROM_PREVIOUS_STEP"},{"$set": {"app_key": "NEW_APP_KEY"}});

How can I increase the max size of data stored in the events logger?

It's possible to increase the max size of data stored in the event logger plugin. You will need SSH access to your server for this.

First, go to Management > Applications and note down your APP ID. Then, SSH to your server, and with root or sudo credentials, run the following:

mongo countly
db.runCommand( { convertToCapped: 'logs{app_id}', size: 10000000, max: 1000 } )

where logs{app_id} should be replaced with your app_id, such as logs53ef75bg5c1ba8237a2d05 and the max should show the new limit, such as max: 2000. Here size denotes the default document size, which has a 16M maximum.

Does Countly use all the cores in my server?

Countly uses a cluster mechanism in api.js to fork itself according to the number of cores in the server in order to increase utilization. This may also be configured from api/config.js by changing the "worker" count.

Are there any limits on data collected?

Both yes and no. In some cases, we limit the data sent to make Countly perform better and be able to handle difficult conditions:

  • For Events View: 500 events - 100 segmentations for each event - 1000 unique values for each segmentation
  • For Drill: 500 events (together with Events View) - No limit on segmentations or values
  • For Funnels: 8 steps (configurable fromManagement > Configurations)
  • There are no limits on the server’s CPU or RAM and there are no limits on the number of accounts, applications, or users.

Note that those limits are defaults and may be reconfigured under Management > Configurations in both the Community Edition (where applicable) and the Enterprise Edition.

How do I remove all users and define a new user?

  1. Login to your server terminal with root credentials
  2. Type mongo countly
  3. Type db.members.drop()

This way existing members will be deleted, meaning you will be redirected to the set-up screen once more.

How do I debug api.js when requesting servername/i URL?

You can use a module such as node-inspector if you would like to go further into detail.

How do you calculate online users?

Online users are unique users for which we received a begin_session and have an ongoing session extended by session_duration and/or event requests. We consider the user as offline as soon as we receive an end_session request for them, or after 60 seconds have passed since their last request was received.

This feature is available only with the Enterprise Edition.

What are the roles of each user type?

This document explains each Countly menu item as well as which ones may be accessed by which user type.

Sometimes I see "unknown" cities on the dashboard, why is that?

For determining cities/countries, Countly uses Geo IP Lite to determine the origin of the IP address from which the connection came. There are two reasons why Countly may not be able to determine this information:

1) Countly can't determine the IP address of the HTTP request. This information is usually provided in the HTTP header and if the sender does not include it, Countly cannot determine the IP address of the connection. In this case, you may try sending the IP address as a parameter along with the request.

2) Some IP addresses might not be in the GeoIP database or they are not city/country specific, which is why the originating city/county cannot be determined.

Sometimes I see wrong city names on the dashboard while I am testing; why is that?

If no location is provided by setting user location, it will be approximated by using GeoIP. In this case, Countly determines city names based on IP address as a default method. Some inaccuracy for city names may be observed for the below reasons:

  1. Some users may have used a VPN
  2. Some IP addresses are simply not correct
  3. Some inconsistencies in GeoIP database
  4. Firewalls stripping IP addresses from requests and setting local ones

For more accurate city name on your dashboard, you can provide country and city in SDK or provide longitude and latitude. For this method, please read our SDK documentations. 

Click for Windows SDK

Click for iOS SDK

Click for Android SDK

How do you calculate the live users bar chart?

When you login to the dashboard, the live users chart on the top right of the page displays how many users have opened your app in the last 10 seconds. For example, if you see the number "80" displayed there, that means your app has been opened by 80 users in the last 10-second time frame.

This feature is only available in the Enterprise Edition.

I see differences in total users

By default, the exact number of users will be shown for 7 days, 30 days, 60 days, and any period that contains today. When you exclude today in your time or provide a custom time, Countly estimates the total users.

What happens if my users send my application to the background?

As soon as your application is sent to the background, the session is over. Session calculation doesn't involve apps that are sitting in the background, so for a session to be live, the app should be running and sending data to the server.

I am receiving the notice "Countly cannot be reinitialized with different values" for the Android SDK

You are using different configuration options: server URL, API key, and device ID. One of those is changed in between two different Countly.init calls. This is why you are getting this error.

Where should I call Countly.sharedInstance().onStart(); & Countly.sharedInstance().onStop();?

You must call onStart & onStop in each activity. For more information, see this documentation.

How can I test my new translations and where do I put my files?

There are three folders under countly/frontend/express/public/localization:

  1. dashboard
  2. help
  3. pre-login

There are also three translation files on Transifex. In order to test your translation, you may upload your translation file, such as,, and, to the corresponding folder. In order to be able to switch between languages, you will need to edit:

  1. countly/frontend/express/views/dashboard.html and add Русский язык
  2. login.html and add Русский язык

Repeat step 2 for forgot.html, setup.html and reset.html under the same folder.

I upgraded my Linux to another version and Countly no longer works

When you upgrade a Linux box and a change has been made in your configuration files or how the underlying Linux works (e.g. switching from initd to systemd), then you will need to run (with root credentials) the following:

# bash bin/upgrade/16.12/

Replace 16.12 above with your current version.

Also, check if your nginx configuration file is backed up (/etc/nginx/nginx.conf.dpkg-old for Ubuntu and either .rpmnew or .rpmsave for CentOS/Red Hat). In this case, copy your customized nginx file on top of /etc/nginx/nginx.conf.

Was this article helpful?
0 out of 0 found this helpful

Looking for help?