Countly Documentation

Countly Resources

Here you'll find comprehensive guides to help you start working with Countly as quickly as possible.

Technical FAQ

How does Countly platform work?

After your install Countly SDK in your application, users of this application start sending event data to Countly server. From these events, Countly gathers information about what they do, how they behave, which operator they are on, etc.

Which language is Countly written with?

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

How are event and session data sent to Countly?

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

Note that you should see session data on your dashboard as soon as the app launches. But for custom events, you need to wait for the next tick which occurs in every 60 seconds. If, inside the app, you record more than 10 different events, it even does not wait for the next tick and sends 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 don'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 high CPU and data consumption for services that send in-app video, this is clearly an advantage.

Our tests with Android profiler shows Countly takes less than 0,1% of CPU time for single CPU core, in a typical usage scenario for 5 minute session with 5 events and 8 requests sent. For more CPU cores this number will be lower than 0,1%.

What happens if SDK cannot send requests?

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

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

There are a few steps to check when you integrate Countly SDK but there is a problem viewing data.

1. Enable debug logging in SDK

First we need to understand if SDK is working correctly and whether it sends data to server and server accepts it. Check if requests are being created - which means check whether you are calling SDK methods to actually send information to server and that SDK has been implemented correctly.

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

2. Check if SDK requests are arriving to server

Please check under Management > Event Logs to see that your server is indeed receiving data from SDK and see if there are any errors/problems displayed there with your requests. In the case of a problem, Event logs usually states what this problem is about, why request was not processed, or why incoming data may be incorrect - like sending data for incorrect app type, or sending duplicate requests, or incorrectly setup parameter tampering, etc.

In Event Logs, you can also click on any button on top right hand side of the screen to filter down different types of data like sessions, events, metrics, user details or crashes.

3. Check server for errors

Check countly/log/countly-api.log for errors. Chances are there is a problem/bug with 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 wrong host URL. Make sure host URL is in the form of http://SERVER_URL or https://SERVER_URL

5. Check app key

You may be using wrong App key. Make sure you use App key in your application, and not API key. If you use API key, then you also cannot see requests under Management > Event 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

Event name limit may be exceeded, which by default is 500 and can be adjusted under Management > Configurations > API > Max unique event key.

8. Check time zone

Your time zone may be different from the time zone of the application, hence you don't see events on the graph immediately, but after some time.

How many users can a Countly server handle?

In our tests, a high end server can handle several hundreds of events per per second, which is roughly 20.000 concurrent mobile users. For more information, see deployment scenarios for potential installation alternatives. However, do not take this number as a reference as it depends a lot on number of events, network load, configuration, disk speed, RAM size and many other criteria.

Note that these numbers are for Countly Community Edition. In order to get more performance, sharding and replica sets are used for Countly Enterprise Edition.

Are there any video tutorials for installing and configuring Countly?

There are several videos on Countly channel at Youtube. Click here to go directly to videos.

Where should I put my Countly start code for Android?

In as much activity as you can, preferably in each activity.

When I compare different analytics provider's data, I see slight differences. What would be the reason?

There are a few reasons with 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, and some store it. Countly stores it for example, and when there is internet connection, it re-sends.

  2. Users with jailbroken iPhone phones may have analytics disabled. In this case data is never sent. Also, if user chooses not to send analytics feedback for his/her iOS device, it's not possible to report data to iTunes.

  3. User may download the application once, but run it on multiple devices, or may download the app multiple times but run it on same device. In this case Google Analytics and other analytics services may count that user differently.

  4. Some services (eg. Google Analytics) may sample data, e.g discard it if the traffic is over internal their limit.

  5. Countly counts new user as unique device IDs, that is, if a user downloads the same app to iPhone and iPad, it's counted twice. Apple's iTunes service counts it once.

  6. SDKs may have issues with running in different environments. For example, it may send improper encoding and server wouldn't parse it. We see such behaviour 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 a provider and not by other, then a discrepancy may occur as SDK will gracefully fail on unsupported platform.

  8. Different analytics services have different timezone configurations. This directly affects how daily sessions, daily unique users, daily active users and retention tables are calculated.

  9. Some of the iOS and Android platforms are old and unsupported by analytics providers. In this case, if a platform is supported by a provider and not by other, then a discrepancy may occur as SDK will gracefully fail on unsupported platform.

Other than those, improper integration of SDK can cause data discrepancy on server side, like below:

  • If the SDK is integrated in a different way than shown in official documentation,
  • If initialization of the SDK depends on any state on device,
  • If the SDK is being used in a non-native application environment,
  • If original source code of the SDK 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 is completely open source, and it's possible to retrieve stored raw data either via REST API, or via MongoDB commands.

That said, we have run several unit and stress tests to make sure no data is lost during transmission, and we are a lot confident with our codebase. In case 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 device ID reset?

There are some cases that device ID may be reset. Below you can see a breakdown of platform and when a device ID may reset.

What's the hostname to write inside SDK?

Inside SDK, you'll see API HOST directive you need to fill in. This is the same as IP or hostname of your server. For example, if you have countly installed on 192.168.1.1, then inside SDK, you need t owrite https://192.168.1.1. If there is a server name associated with your IP, you can also use it (e.g https://analytics.mycompany.com).

Why does events appear on my dashboard some time later, and not appear real-time?

Due to timezone difference (timezone in which event happens on device and timezone of app setting in dashboard), there can be a case, that converting timestamp to app's timezone, events are added realtime to the time lines but with times like hour ago. The delay also may depend on the devices and SDKs, for example if device is offline, requests are queued and then synced with Countly server. Since recorded event timestamps will be in the past, new added events will count as past events in 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 can provide more insights for your product.

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

How can I see how many datapoints our service consumes?

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

You can view a sample screenshot below. Clicking on each of the months will give you number of datapoints each application consumes, 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 that has 10 events in it, each event with 10 segments will be around 8KB. If this is a single event with 10 segments in a single request, it is around 1KB. The size depends on various factors such as length of event keys, length of segment keys and values. But basically a reasonable event request will be around 1KB.

Other than that,

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

Basically, any extra event segment and user property will affect the data transfer volume but by how much depends 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 over data to the server every minute or whenever 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 since HTTP request itself has an overhead thus sending in bulk results in bandwidth savings. Obviously keeping number of events, segments and user properties low will lower the volume.

I enable a plugin, but cannot see its effect on dashboard

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

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

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

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

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

It's possible to increase max size of data stored in 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

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

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

Does Countly use all cores in my server?

Countly uses a cluster mechanism in api.js to fork itself according to number of cores in the server in order to increase utilisation. This can also be configured from api/config.js by changing "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 handle absurd 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 from Management)

There are no limits on CPU or RAM of the server and there are no limits on number of accounts, applications or users.

Note that those limits are default and can be reconfigured under Manage > Configurations in both Community Edition (where applicable) and 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 so that you will be redirected to the setup screen again.

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

You can use a module like node-inspector if you want to go into detail.

How do you calculate online users?

Online users are unique users that we received a begin_session for and has 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 him or 60 seconds passed since last request received.

This feature is available only for Enterprise Edition.

What are the roles of each user type?

This document explains each Countly menu item and which ones can be accessed by which user type.

Sometimes I see "unknown" cities on dashboard, why ?

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

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

2) Some IP addresses might not be in GeoIP database or they are not city/country specific, thats why it can't determine the originating city/country.

How do you calculate live users barchart?

When you login to the dashboard, the live users chart on top right of the page shows you how many users have opened your app for the last 10 seconds. So if you read "80" there, that means your app has been opened by 80 users for last 10 second time frame.

This feature is available only for Enterprise Edition.

I see differences in total users

By default, 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 total users.

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

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

I am getting "Countly cannot be reinitialized with different values" for Android SDK

You are using different configuration options: server URL, api key, 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 in each activity onStart & onStop. For more information, see this documentation

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

Under countly/frontend/express/public/localization there are three folders;

  1. dashboard
  2. help
  3. pre-login

There are also three translation files on Transifex. In order to test your translation you can upload your translation file like dashboard_ru.properties, help_ru.properties, pre-login_ru.properties to the corresponding folder. In order to be able to switch between languages you 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 doesn't work

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

# bash bin/upgrade/16.12/upgrade.sh

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.

Technical FAQ


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.