C++ analytics - Qmonix

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 (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 #include #include

    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 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

    C++ analytics - Qmonix

    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

    C++ analytics - Qmonix
    C++ analytics - Qmonix

    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.

    C++ analytics - Qmonix

    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.

    Step 9: References

    [1] https://github.com/qmonix/client-cpp

    [2] http://demo.qmonix.com

    [3] http://docs.qmonix.com/latest/#event-naming-expla...

    [4] https://github.com/qmonix/client-cpp/tree/master/...

    [5] http://docs.qmonix.com/latest/#analytics-query-la...

    [6] http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol


    Tag cloud

    make build easy simple arduino making homemade solar laser printed portable cheap mini building custom cardboard wooden create super lego turn paracord chocolate your paper light intel