lightstep-tracer-cpp

README

lightstep-tracer-cpp

The LightStep distributed tracing library for C++.

Installation

The library supports being built in several configurations to support a variety of uses. There are three transport options available:

1. Streaming HTTP transport (NEW in 0.9.x): This option uses multiple outbound HTTP 1.1 connections to send spans to LightStep. This transport option is optimized for concurrency and throughput, compared with the gRPC transport option. TLS is not currently supported in this configuration.
2. gRPC transport (DEFAULT): This option uses the gRPC library for transport. This transport option is not optimized for concurrency and throughput, compared with the the Streaming HTTP transport option.
3. User-defined transport: This option allows the user to supply custom logic for transporting span objects to LightStep. Users must implement one of the LightStep-supported transports themselves with this option.

The library also supports dynamic loading, for applications that support more than one OpenTracing-compatible tracer. To use the dynamic library, we recommend installing the binary plugin included with each release (e.g., the 0.9.0 plugin).

Requirements

To build and install the LightStep distributed tracing library, you will need to have several tools and libraries intalled.

1. cmake
2. protobuf
3. grpc (for gRPC transport)
4. c-ares (for Streaming HTTP transport)
5. libevent (for Streaming HTTP transport)
6. OpenTracing C++ library.

Building

Get and install the current 1.5.x release of OpenTracing as described in that repository's README. After installing the OpenTracing APIs, generate the Makefile with the desired build options.

1. For gRPC, use -DWITH_GRPC=ON
2. For Streaming HTTP, use -DWITH_LIBEVENT=ON -DWITH_CARES=ON -DWITH_GRPC=OFF
3. For Dynamic loading support, add -DWITH_DYNAMIC_LOAD=ON

Run these commands to configure and build the package.

$ mkdir .build
$ cd .build
$ cmake ..
$ make
$ sudo make install

OS X specific steps

Several packages are required to complete this build. To install all the dependencies on OS X using brew:

brew install cmake
brew install protobuf
brew install grpc         # for gRPC
brew install c-ares       # for Streaming HTTP
brew install libevent     # for Streaming HTTP
brew install pkg-config

Getting started

To initialize the LightStep tracer, configure the options and construct the object as shown below. The Tracer returned by lightstep::MakeLightStepTracer may be passed manually through the application, or it can be set as the opentracing::Global() tracer.

#include <opentracing/tracer.h>
#include <lightstep/tracer.h>

const bool use_streaming_tracer = true;

void initGlobalTracer() {
  lightstep::LightStepTracerOptions options;
  options.component_name = "c++ quickstart app";
  options.access_token = "hello";

  // Configure the tracer to send to the local developer satellite:
  options.collector_plaintext = true;
  if (use_streaming_tracer) {
    options.satellite_endpoints = {{"localhost", 8360}};
    options.use_stream_recorder = true;
  } else {
    options.collector_host = "localhost";
    options.collector_port = 8360;
    options.use_stream_recorder = false;
  }

  auto tracer = lightstep::MakeLightStepTracer(std::move(options));

  opentracing::Tracer::InitGlobal(tracer);
}

int main() {
  initGlobalTracer();

  auto span = opentracing::Tracer::Global()->StartSpan("demo");

  span->SetTag("key", "value");
  span->Log({{"logkey", "logval"},
             {"number", 1}});
  span->Finish();

  opentracing::Tracer::Global()->Close();
  
  return 0;
}

For instrumentation documentation, see the opentracing-cpp docs.

Dynamic loading

The LightStep tracer supports dynamic loading and construction from a JSON configuration. See the schema for details on the JSON format.