scarf-cpp

A small modern C++ client for sending telemetry events to Scarf.

Requirements

• C++17 or newer
• CMake 3.20+
• libcurl

Install

This initial v0 can be consumed from source with CMake:

include(FetchContent)
FetchContent_Declare(
  scarf_cpp
  GIT_REPOSITORY https://github.com/scarf-sh/cpp-sdk.git
  GIT_TAG v0.1.0
)
FetchContent_MakeAvailable(scarf_cpp)

target_link_libraries(your_target PRIVATE scarf::scarf-cpp)

Or install and use the generated CMake package:

cmake -S . -B build -DSCARF_CPP_BUILD_TESTS=ON
cmake --build build
cmake --install build --prefix /your/install/prefix

find_package(scarf-cpp CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE scarf::scarf-cpp)

Usage

#include "scarf/event_logger.hpp"

int main() {
  scarf::EventLogger logger("https://your-scarf-endpoint.com");

  scarf::LogResult result = logger.log_event({
      {"sdk", "scarf-cpp"},
      {"release", "v0.1.0"},
      {"source", "my-application"},
      {"metadata", scarf::PropertyValue::Object{{"channel", "stable"}, {"feature", "install"}}},
  });

  return result.success ? 0 : 1;
}

log_event sends a POST request to the configured endpoint with Content-Type: application/json. Event properties are encoded as a JSON request body so strings, numbers, booleans, arrays, objects, and nulls round-trip without query-string encoding.

When sending events through the Scarf gateway, use metadata-style property names that describe your client or integration. Avoid overloading common event-processing names such as event and package unless your Scarf endpoint is configured to expect them.

Scarf analytics are processed asynchronously. A successful gateway response means the event was accepted, but it can take a couple of hours before the event appears in analytics exports or dashboard views.

Configuration

The client follows the same defaults as the other Scarf SDKs:

• Default timeout: 3 seconds
• DO_NOT_TRACK=1: disable analytics
• SCARF_NO_ANALYTICS=1: disable analytics
• SCARF_VERBOSE=1: print debug information to stderr
• User-Agent format: scarf-cpp/<version> (platform=<platform>; arch=<arch>; cpp=<standard>)

You can also inject an HTTP transport for tests or controlled environments:

scarf::LoggerOptions options;
options.endpoint_url = "https://your-scarf-endpoint.com";
options.timeout = std::chrono::milliseconds(1000);
options.transport = my_transport;
scarf::EventLogger logger(options);

Development

cmake -S . -B build -DSCARF_CPP_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

The test suite does not make network calls; it uses an injected transport to validate request construction, opt-out behavior, errors, and the User-Agent format.

CI currently validates Linux and macOS builds. Windows/MSVC support is intended by the CMake configuration but is not yet covered by CI.

License

Apache 2.0