cppkin is an instrumentation client library for zipkin written in C++. meant to be used by distributed services in order to measure latency across clusters.

• c++14.
• Cmake version > 3.8.
• OpenSSL-dev.

• Runtime support and tool chain of Visual Studio 2013.
• Cmake version > 3.8.
• Flex and Bison (e.g. the WinFlexBison package)

cppkin uses the following 3rd party dependencies -

1. boost.
2. spdlog.
3. thrift.

In order to start run the following script:

. INSTALL.bash

The script will:

1. Retrieve all 3rd party dependecies, compiling them and installing them locally (under cppkin directory structure).
2. Compile cppkin into shared object.

cppkin shared object will be available under the bin dir.

In order to start run the following script:

INSTALL.bat

The script will:

1. Retrieve all 3rd party dependecies, compiling them and installing them locally (under cppkin directory structure).
2. Compile cppkin into shared object.
3. Will create msbuild project structure for all the different components.

cppkin dll will be available under the bin dir.

In order to use cppkin include cppkin interface file - cppkin.h.

#include "cppKin/src/cppkin.h"

The file publish the following capabilities:

1. Initialization.
2. Create Trace.
3. Create/Join Span.
4. Trace simple events.
5. Serialize/Deserialize span header.

All capabilities are provided in Macro method style (semicolon is in need), for example:

CREATE_TRACE("Resource_Offer");

In order to initialize cppkin (the first step you would like to take) two operations are in need:

1. Composing cppkin configuration.
2. Providing the config object to the Init routine.

cppkin supports the following policies:

A full example:

cppkin::GeneralParams cppkinParams;
cppkinParams.AddParam(cppkin::ConfigTags::HOST_ADDRESS, string("127.0.0.1"));
cppkinParams.AddParam(cppkin::ConfigTags::PORT, 9410);
cppkinParams.AddParam(cppkin::ConfigTags::SERVICE_NAME, string("Index_Builder"));
cppkinParams.AddParam(cppkin::ConfigTags::DEBUG, false);
cppkinParams.AddParam(cppkin::ConfigTags::SAMPLE_COUNT, 1000);
INIT(cppkinParams);

Each new span (acting as the new context), is referenced by using the current thread TLS, all operation are acted upon the current context.

by creating a new span in the context of the current thread, it will be elected as the new context.

In order to trace use the CREATE_TRACE command:

CREATE_TRACE("Scheduling tasks");

CREATE_TRACE takes a single argument - the "Operation name" which needs to be provided as const char* argument type.

In order to create a child span use the CREATE_SPAN command:

CREATE_SPAN("Processing Task", spanHeader.TraceID, spanHeader.ID);

CREATE_SPAN takes the following arguments:

• Operation name - const char* type.
• The current trace id - retrieved from the previous span header.
• Parent span id - retrieved from the previous span header.

In order to trace an event use the TRACE_EVENT command:

TRACE_EVENT("Trace an event");

TRACE_EVENT takes a single argument - the "Event value" which needs to be provided as const char* argument type.

cppkin contains a specified transportation layer, providing the following capabilities:

• Serializing the received data.
• Transporting it to a specific zipkin collector out stream.

As of now only scribe collector is supported in the transportation layer, which uses Thrift for both serializing and as a RPC solution.

Outstream communication is done by using a single simple command - `SUBMIT_SPAN'.

SUBMIT_SPAN();

once called the current span in context will be out streamed to the designated collector. the context will be cleared after the completion of the command.

Collector type and collector address are set by using cppkin configuration during the init step.