Qmonix is a flexible analytics SDK. It allows you to collect events from any digital device that supports HTTP [6] connections. It also provides dashboard to visualize the collected data and API to query for collected events.

In this tutorial we will see how to use the provided c++ client. We will submit events to Qmonix server [1] and review the results in the Qmonix dashboard [2].

Step 1: Example Scenario

As an example I chose specific scenario that I want to track. I want to know how many of my applications terminated abnormally, e.g. were killed with a SIGTERM. This is a simple scenario, all we need is two events: application started event and application exited event. Based on Qmonix event naming rules [3] let’s give tags to our events:

"exit_app/started"
"exit_app/exited"

We’ll be using these tags to query collected data from server. The interesting measures are:

how many times our application was started;
ratio of how many times application was started and exited normally.

Using those two events we can get the desired information. E.g. we want to know how many percent of our started applications exited normally. We would simply divide the number of exit_app/started byt the number of exit_app/exited events.

Using such information we could tell how well our application behaves. Although, we do not have enough info to tell the reasons why our application crashed. This requires more events. But for now let’s stick to those two.

Step 2: Environment

For this example we will be using Debian 7.x system. Build prerequisites:

g++;
make, cmake;
libcurl;
libqmonix [1].

Step 3: Sample Project

Let’s build a sample project that implements our simple scenario. You can get the sample from github [4].

Sample project structure is pretty simple. We have couple of build scripts, symbolic link to Qmonix c++ client and a single source file:

.
|__ CMakeLists.txt
|__ Makefile
|__ lib
|  |__ qmonix -> ../../../
|__ src
   |__ main.cpp

1. CMakeLists.txt:

cmake_minimum_required (VERSION 2.6)
project (AppExitTracking CXX)
set (CMAKE_BUILD_TYPE "Release")
set (CMAKE_CXX_FLAGS "-Wall -Wextra -Werror -pedantic -ggdb -std=c++98")
set (SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src")
file (GLOB_RECURSE SRC_FILES "${SRC_DIR}/*.cpp")
set (EXIT_APP "exit_app")
add_executable (${EXIT_APP} ${SRC_FILES})
target_link_libraries ("${EXIT_APP}" "curl" "qmonix")
add_subdirectory ("lib/qmonix")
include_directories ("${CMAKE_CURRENT_SOURCE_DIR}/lib/qmonix/include")

2. Makefile:

BUILD_DIR = build
all: cmake
.PHONY: all
cmake: $(BUILD_DIR)
        cd $(BUILD_DIR); cmake $(CURDIR); make
.PHONY: cmake
$(BUILD_DIR):
        mkdir -p $@
run:
        $(BUILD_DIR)/exit_app
.PHONY: run
clean:
        rm -rf $(BUILD_DIR)
.PHONY: clean

3. main.cpp:

#include <iostream>

#include <qmonix/qmonix.hpp>
#include <qmonix/tracker.hpp>
#include <qmonix/event_dispatcher.hpp>
using namespace std;
using namespace qmonix;
int
main(void)
{
        tracker *qtrack = new tracker(
                new event_dispatcher("http://localhost:8337/event/"));
        qtrack->fire("exit_app/started");
        qtrack->dispatch();
        string command = "";
        while (command != "exit")
        {
                cout << "Qmonix client version: " <<
                        qmonix::version << endl;
                cout << "Type 'exit' to quit." << endl;
                cin >> command;
        }
        qtrack->fire("exit_app/exited");
        qtrack->dispatch();
        delete qtrack;
        return 0;
}

This simple application tracks when the program is started and gracefully terminated. Once it is started it enters the loop until you type “exit”. This allows us to kill the program e.g. with “ctrl+c”. In such case event exit_app/exited will not be fired.

Step 4: Executing Sample and Reviewing the Results

Let’s execute the sample couple of times and checkout what information we can get from it. Firstly let’s build the example:

$ make

Exit normally
Let’s run the executable and exit it normally:

$ make run
build/exit_app
Qmonix client version: 0.1.0
Type 'exit' to quit.
exit

The program should send both events: exit_app/started and exit_app/exited. Now let’s see the event report. Openhttp://localhost:8337 in your Web browser, this opens Qmonix dashboard.

Step 5: Open Dashboard

By default there’s a single dashboard window that displays all events. You should see this window if you have not used dashboard before because it saves the changes you make in your cookies.

Step 6: Add Pie Chart

To better visualise how our application was terminated, let’s create a pie chart which displays both events separately.

Qmonix has specific query language to select events [5]. Our query exit_app/[*] means that we want to get all tags that start with prefix exit_app/. The [*] part tells that event values should not be summed but returned separately.

So this works pretty well and we get a nice pie chart that tells us that our application was terminated as expected as many times as it ran:

Step 7: Terminate With Signal

This time let’s run the application and terminate it abnormally (ctr+c):

$ make run
build/exit_app
Qmonix client version: 0.1.0
Type 'exit' to quit.
^Cmake: *** [run] Interrupt

In this scenario we should receive exit_app/started but not exit_app/exited event. Let’s refresh our pie chart.

Step 8: Pie Chart After Application Was Terminated.

And now it’s obvious that our application was started more times than it exited gracefully. Such information could tell us whether we should be concerned about our software stability or not.

Well this is just a basic example and there are many more other events that you might want to track. Qmonix let’s you do that with no sweat.