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        2.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 libraries (SNOWPLOW_USE_EXTERNAL_JSON=ON). If you're building a static library (SNOWPLOW_USE_EXTERNAL_SQLITE=ON) you also need to use SQLite3 as an external library (SNOWPLOW_USE_EXTERNAL_SQLITE=ON).

If you have SQLite3, CURL or LibUUID available as system libraries but you need to use them from a different package (e.g. from Conan) you 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)

Make sure your project finds the same dependencies what was visible for Snowplow when you were building and installing it. For example, if you have both system and local SQlite3 installations and CMAKE_FIND_PACKAGE_PREFER_CONFIG was ON for Snowplow but OFF for your project, Snowplow will be built with the local SQLite3 while during find_package(snowplow) in your project it will find the system one.

See the example app for instructions how to build and install the tracker using this option.

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> ./examples/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

Use the CMake build tool to configure and generate the Visual Studio project files. Build and run the project using the Visual Studio IDE.

Copyright and license

The Snowplow C++ Tracker is copyright 2023 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.