. . .

Analytics Installation

Introduction

With Analytics you will get functionality to track different actions from users of your app. These tracking methods will be automatically in your SDKs (see the supported SDKs below). When the Analytics feature is activated the Analytics module will be automatically added to your application. Using the Analytics module you have a complete dashboard only for analytics purposes.

Prerequisites

Open the following port in the firewall:

Port

Transport

Service

Host

Client

80/443

TCP

 

Webserver

Application Server

Outside World

Install MongoDB [optional]

If your are installing Analytics with a package, MongoDB (version 3.4 or 3.6) has to be installed first. If MongoDB is already installed, you don't need to do the following step:

System requirements

The following instance configurations are recommended.

Size

CPU

Memory

Disk

Typical Cloud Instance Types

Small

(One Server)

2 core

4 GB RAM

min. 50 GB

AWS: t2.medium

Azure: Standard_A2_V2

Medium

4 core

8 GB RAM

min. 100 GB

AWS: c5.xlarge

Azure: Standard_A4_v2

Large

8 core

16 GB RAM

500 GB

AWS: c5.2xlarge

Azure: Standard_A8_v2

Installation

USERNAME, PASSWORD, and TOKEN values are provided per customer from ApiOmat, if needed.

The ApiOmat Analytics packages aren't available in our repository yet. Contact us, so that we can provide the latest version to you. Use the RPM-Package for CentOS and DEB for Debian and Ubuntu. The described systems below are tested. There is no guarantee that this packages will work on other systems.

After you got the package and put it into a temporary folder, you need to follow the specific installation guide.

Debian/Ubuntu
sudo dpkg -i ApiomatAnalytics-<ANALYTICS_VERSION>.deb
sudo add-apt-repository universe
 
 
#install dependencies
sudo apt-get install -f -y --no-install-recommends
Centos/Oracle/RedHat
sudo yum --nogpgcheck localinstall -y apiomat-Analytics-<ANALYTICS_VERSION> .rpm
Suse
sudo zypper --no-gpg-checks install -y apiomat-Analytics-suse-<ANALYTICS_VERSION>.rpm
Docker Compose

Before you can run ApiOmat Analytics in Docker, you should check the requirements here.

The following script will start up the Analytics docker container.

# Docker login
docker login -u <USERNAME> -p <PASSWORD>
 
# Store the following file and execute:
docker-compose -f analytics.yml up

After running those startup commands, it could take a while until ApiOmat Analytics is started and reachable. It is completely started when you reach the ApiOmat Analytics website with your browser (e.g. over localhost:8001).

The analytics.yaml is a typical docker compose yaml file and could be configured like this:

analytics.yml
version: '3.5'
services:
aomanalytics:
image: apiomat/analytics:<VERSION>
user: root
environment:
analytics_aomDashboardUrl: http://localhost/dashboard_2.0/apiomat
analytics_mongodb_host: mongo
analytics_mongodb_db: countly
analytics_mongodb_port: 27017
ports:
- 8001:80
depends_on:
- mongo
mongo:
image: mongo:3.4
command: --smallfiles

Configuration

Linux systems

Analytics Config

You have to configure the MongoDB settings and the aomDashboardUrl parameter which should be the ApiOmat Dashboard URL.

The application.yaml is placed in the /etc/apiomat/aom-analytics directory. To use the properties below, you simply have to uncomment those specific lines. It uses the yaml syntax.

application.yaml
production:
# analytics:
# aomDashboardUrl: "https://address.to.my.apiomat.dashboard"
#
#### configure a single mongo instance
# mongodb:
# host: localhost
# db: countly
# port: 27017
##### define username, password and dbOptions only when mongo auth is configured
# username: test
# password: test123
# dbOptions:
# authSource: admin
#### configure a mongo replica set
# mongodb:
# replSetServers:
# - 192.168.3.1:27017
# - 192.168.3.2:27017
# replicaName: test
##### define username, password and dbOptions only when mongo auth is configured
# username: test
# password: test123
# dbOptions:
# authSource: admin
#
#### configure consul
# consul:
# host: 127.0.0.1
# port: 8500
# secure: false
# healthCheck:
# hostname: http://192.168.178.96
# port: 80
# timeout: 2
# interval: 5
# deregistercriticalserviceafter: 60

When coming from an earlier version (when updating), you have to adjust the old config.js files: simply overwrite both config.js with the config.aom.js files, which are placed in the same directory (/api and /frontend/express). After this overwriting, you can use the application.yaml to configure Analytics. For fresh 1.5 (or higher) installations, you don't need this step.

Configure Graylog (Optional step)

When not using docker, the graylog integration needs further configuration. You first have to install the plugin for the nodejs server manager 'pm2' and then set the hostname and port via the following commands:

configure graylog plugin
# install plugin
sudo pm2 install pm2-gelf
 
 
# configure address
sudo pm2 set pm2-gelf:graylogHostname 127.0.0.1
sudo pm2 set pm2-gelf:graylogPort 12201
Docker

Environmental Variables

Required variables are printed in bold.

variable

description

example

analytics_path

URL path extension for analytics

/analytics

analytics_aomDashboardUrl

this is the public URL to your ApiOmat dashboard

http://mydashboard.address.com

analytics_mongodb_host

use this, when having a single mongo instance,

localhost

analytics_mongodb_replSetServers

use this and replicaName instead of "host" when configuring a mongo replicaset

in docker compose:

analytics_mongodb_replSetServers:

- 192.168.3.1:27017

- 192.168.3.2:27017

analytics_mongodb_replicaName

name of the replicaset

test

analytics_mongodb_db

name of the db to use,

countly

analytics_mongodb_port

mongodb port

27017

analytics_mongodb_username

if an authentication is configured for the mongodb, you have to set the username and password

superadmin

analytics_mongodb_password

password of the mongodb authentication

test123

analytics_mongodb_dbOptions_authSource

having an authentication configured, this is the name if the database

admin

consul_host

host address of consul

127.0.0.1

consul_port

port of consul

8500

consul_healthCheck_hostname

hostname of the analytics instance for consul to send health check requests

http://locahost

consul_healthCheck_port

port of analytics instance

80

consul_healthCheck_timeout

timeout for the health check request (in seconds)

2

consul_healthCheck_interval

interval for health checks (in seconds)

5

consul_healthCheck_deregistercriticalserviceafter

deregister analytics from consul, when it's unhealthy (in seconds)

60

graylog_host

host of graylog

locahost

graylog_port

port of graylog

12201

ApiOmat Configuration

After the installation, you can set the analytics host property in yambas.conf/apiomat.yaml to enable the ApiOmat-Analytics feature for your installation.

The following snippet shows the three lines to add to your config:

apiomat.yaml
common:
analytics:
hosts:
internal: http://localhost:8001/ # internal host target of the installation
public: http://www.yourdomain.yourhost.tld/ # external reachable address of the analytics instance
 
## add Analytics to the default Modules:
yambas:
## ...
defaultModules: Basics,Analytics
yambas.conf
analyticsHostInternal=http://localhost:8001/ # internal host target of the installation
analyticsHostPublic=http://www.yourdomain.yourhost.tld/ # external reachable address of the analytics instance
 
## add Analytics to the default Modules:
defaultModules: Basics,Analytics

Activate Analytics

A restart of the Tomcat server will not initialize your analytics instance anymore (since 3.0.1).

You have to log into the Dashboard via the SuperAdmin account, go to the configuration page and click the "Activate Analytics" button .

This will initialize the connection between Analytics and Yambas.

Logging

Linux

Logging is done to a separate logfolder: /var/log/apiomat/aom-analytics which is accessible using the following commands:

Linux
# for the api server log
tail -f /var/log/apiomat/aom-analytics/api.log
# for the frontend log
tail -f /var/log/apiomat/aom-analytics/dashboard.log
Docker

Please replace <ANALYTICS_CONTAINER_ID> with your running container ID. You can list your running containers using 'docker container list' command.

Docker
docker logs -f <ANALYTICS_CONTAINER_ID>

Process management

When being inside the docker container or having it installed on a linux system, the following commands are available:

sudo countly start
sudo countly stop
sudo countly status

Apiomat analytics is using pm2 as process manager. This provides more useful features, that you can access with following commands:

pm2 usage
# Process Monitoring
sudo pm2 list # List all processes started with PM2
sudo pm2 show [countly-api|countly-dashboard] # Show all information about application
 
# Log management
sudo pm2 logs # Display logs of all apps
sudo pm2 logs [countly-api|countly-dashboard] # Display logs for a specific app