C++ Analytics for Snowplow

Snowplow is a scalable open-source platform for rich, high quality, low-latency data collection. It is designed to collect high quality, complete behavioral data for enterprise business.

To find out more, please check out the Snowplow website and our documentation.

Snowplow C++ Tracker Overview

Snowplow C++ tracker enables you to add analytics to your C++ applications, servers and games when using a Snowplow pipeline.

Quick Start

The tracker supports macOS, Windows, and Linux.

Installation

There are three ways to install the tracker in your app:

1. By adding the project into your CMakeLists.txt as a subdirectory.
2. By installing the project and importing it into your app using CMake's find_package command.
3. By copying source files inside the include folder into your codebase.

As a subdirectory in your CMake project

CMake version 3.15 or greater is required. You may add the library to your project target (your-target) using FetchContent like so:

include(FetchContent)
FetchContent_Declare(
    snowplow
    GIT_REPOSITORY https://github.com/snowplow/snowplow-cpp-tracker
    GIT_TAG        1.0.0
)
FetchContent_MakeAvailable(snowplow)
target_link_libraries(your-target snowplow)

As an imported target in your CMake project

First build and install the project. Make sure the project uses the external JSON and SQLite3 libraries (SNOWPLOW_USE_EXTERNAL_JSON=ON and SNOWPLOW_USE_EXTERNAL_SQLITE=ON). Use BUILD_SHARED_LIBS=ON to build a shared library. Depending on how you're providing the dependencies for which there are find-modules (sqlite3, libcurl, uuid) you might need to set CMAKE_FIND_PACKAGE_PREFER_CONFIG=ON to prevent linking to the system libraries.

cmake [...] -DCMAKE_INSTALL_PREFIX=[...]
    -DSNOWPLOW_USE_EXTERNAL_JSON=ON -DSNOWPLOW_USE_EXTERNAL_SQLITE=ON \
    -DCMAKE_FIND_PACKAGE_PREFER_CONFIG=ON \
    -DSNOWPLOW_BUILD_TESTS=0 -DSNOWPLOW_BUILD_EXAMPLE=0 -DSNOWPLOW_BUILD_PERFORMANCE=0

After building and installing the project you can use find_package to import it into your CMakeLists.txt:

find_package(snowplow REQUIRED CONFIG)
...
target_link_libraries(your-target snowplow::snowplow)

Copying files to your project

Download the most recent release from the releases section. Everything in the include folder will need to be included in your application.

The project has two dependencies that need to be included in your project: nlohmann/json and the amalgamated version of sqlite3. You will need to update the include paths in headers include/snowplow/thirdparty/json.hpp and include/snowplow/thirdparty/sqlite3.hpp.

Additional requirements under Linux

The following libraries need to be installed:

• curl (using apt install libcurl4-openssl-dev on Ubuntu)
• uuid (using apt install uuid-dev on Ubuntu)

Using the tracker

Import using the snowplow/snowplow.hpp header file and initialize the tracker with your Snowplow collector endpoint and tracker configuration:

#include "snowplow/snowplow.hpp"

using namespace snowplow;

// Initialize tracker with namespace, collector URI, HTTP method, and SQLite database path (see docs for other options)
auto tracker = Snowplow::create_tracker("ns", "https://collector.com", POST, "sp.db");

Track custom events (see the documentation for the full list of supported event types):

// structured event
StructuredEvent se("category", "action");
tracker->track(se);

// screen view event
ScreenViewEvent sve;
string name = "Screen ID - 5asd56";
sve.name = &name;
tracker->track(sve);

Check the tracked events in a Snowplow Micro or Snowplow Mini instance.

Find out more

Technical Docs	API Docs	Contributing
Technical Docs	API Docs	Contributing

Maintainer Quick Start

Building on macOS and Linux

 host> git clone https://github.com/snowplow/snowplow-cpp-tracker
 host> cd snowplow-cpp-tracker
 host> cmake -D SNOWPLOW_BUILD_TESTS=1 -D SNOWPLOW_BUILD_EXAMPLE=1 -B build .
 host> cd build
 host> make

This will create two executables - the first is the test suite. To run the test suite, first start a Snowplow Micro instance and run:

 host> ./snowplow-tests

The other is an example program which will send one of every type of event to an endpoint of your choosing like so:

 host> ./snowplow-example {{ your collector uri }}

If you make changes only to a header file there is a chance it won't be picked up by make in which case you will need to:

 host> make clean
 host> make

Performance testing

The project also provides performance tests to measure changes in performance of the tracker. The tests measure performance under a few scenarios in which they vary the emitter and session.

Build and run the performance using the following steps from the root of the project:

 host> cmake -D SNOWPLOW_BUILD_PERFORMANCE=1 -B build .
 host> cd build && make && cd ..
 host> ./build/snowplow-performance

To compare with historical performance measurements (logged in the performance/logs.txt file), run the following Python script that will output a table with the performance comparison:

 host> ./performance/stats.py                                       

 Metric                                | Max     | Min     | Mean    | Last    |
--------------------------------------------------------------------------------
 mocked emitter and mocked session     | 5.27s   | 5.08s   | 5.18s   | 5.27s   |
 mocked emitter and real session       | 5.08s   | 5.04s   | 5.06s   | 5.07s   |
 mute emitter and mocked session       | 18.77s  | 17.29s  | 18.08s  | 18.77s  |
 mute emitter and real session         | 28.02s  | 22.61s  | 25.06s  | 22.61s  |

Building on Windows

git clone https://github.com/snowplow/snowplow-cpp-tracker

In the cloned directory two Visual Studio 2015 project files are available:

• snowplow-cpp-tracker.sln This is required to compile the tracker and run the tests (you'll need this one to edit the tracker itself)
• snowplow-cpp-tracker-example.sln This is a demo project showing use of this tracker

To run the tests under windows, you need to open the snowplow-cpp-tracker.sln solution, build it for your target platform and run the resulting executable.

Copyright and license

The Snowplow C++ Tracker is copyright 2022 Snowplow Analytics Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.