This Quick Start will have you configure your tracer to communicate with the Lightstep Satellites and create a single span on your service. You install both the OpenTracing API and Lightstep tracer and then use the OpenTracing and Lightstep APIs to instrument your code.

While Lightstep offers tracers and APIs specific to its tracing software, you will still use the OpenTracing API to fully instrument your code. Be sure you have read and are familiar with both Lightstep tracers and the OpenTracing specification in your application’s language.

C++ Instrumentation for OpenTracing

  1. Follow the instructions in the lightstep-tracer-c++ README for prerequisites and to build and install the OpenTracing library on your machine.

  2. Find your access token in Lightstep. You’ll need this to configure your Lightstep tracer.

    • Click the Project Settings button.

    • In the Access Tokens table, click the Copy icon to copy your access token to the clipboard.

  3. In your application code, add a reference to the Lightstep C++ Tracer and to the OpenTracing API.

    1
    2
    
    #include <opentracing/tracer.h>
    #include <lightstep/tracer.h>
    
  4. Early in your application’s initialization, configure the Lightstep tracer and register it as the OpenTracing Global Tracer. As part of the configuration, you need to add your access token and add a tag to hold the value of your service’s name.

    Use the right code for your environment!
    When initializing the tracer, you pass in properties to the Lightstep Satellites that collect the span data. Be sure to use the code for your Lightstep Satellite environment - On-Premise, Lightstep Public Satellite pool, or Developer Mode Satellite.

    Start tabs

    On-Premise Satellites

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    const bool use_streaming_tracer = true; //Set to false if not using streaming HTTPvoid initGlobalTracer()
    
    void initGlobalTracer() {
      lightstep::LightStepTracerOptions options;
      options.component_name = "YOUR_SERVICE_NAME";
      options.access_token = "YOUR_ACCESS_TOKEN";
    
      // Configure the tracer to send to on-premise satellite pool:
      options.collector_plaintext = true;
      if (use_streaming_tracer) {
        options.satellite_endpoints = your_load_balancer_DNS_name_or_IP_address;//enter the port your pool uses
        options.use_stream_recorder = true;
      } else {
        options.collector_host = "your_load_balancer_DNS_name_or_IP_address";
        options.collector_port = 8360;//enter the port your pool uses
        options.use_stream_recorder = false;
      }
    
      auto tracer = lightstep::MakeLightStepTracer(std::move(options));
    
      opentracing::Tracer::InitGlobal(tracer);
    }
    

    Public Satellites

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    const bool use_streaming_tracer = true; //Set to false if not using streaming HTTPvoid initGlobalTracer()
    
    void initGlobalTracer() {
      lightstep::LightStepTracerOptions options;
      options.component_name = "YOUR_SERVICE_NAME";
      options.access_token = "YOUR_ACCESS_TOKEN";
    
      // Configure the tracer to send to on-premise satellite pool:
      options.collector_plaintext = true;
      if (use_streaming_tracer) {
        options.satellite_endpoints = ingest.lightstep.com;
        options.use_stream_recorder = true;
      } else {
        options.collector_host = "ingest.lightstep.com";
        options.collector_port = 443;
        options.use_stream_recorder = false;
      }
    
      auto tracer = lightstep::MakeLightStepTracer(std::move(options));
    
      opentracing::Tracer::InitGlobal(tracer);
     }   
    

    Developer Mode

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    const bool use_streaming_tracer = true; //Set to false if not using streaming HTTPvoid initGlobalTracer()
    
    void initGlobalTracer() {
      lightstep::LightStepTracerOptions options;
      options.component_name = "YOUR_SERVICE_NAME";
      options.access_token = "developer";
    
      // Configure the tracer to send to on-premise satellite pool:
      options.collector_plaintext = true;
      if (use_streaming_tracer) {
        options.satellite_endpoints = localhost;
        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);
     }      
    

    End code tabs

  5. Test that everything is connected by sending a test span. Annotate the span by adding a tag and logs, then flush the tracer.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    
       
    int main() {
     initGlobalTracer();
    
     auto span = opentracing::Tracer::Global()->StartSpan("test_span");
    
     span->SetTag("key", "value");
     span->Log({{"logkey", "logval"},
              {"number", 1}});
     span->Finish();
    
     opentracing::Tracer::Global()->Close();
    
     return 0;
     }
         
    
  6. Build the app. Depending on the operating system and the compiler toolchain’s default settings, you may need several compiler flags for your compiler to locate the OpenTracing and Lightstep include and library paths. See the lightstep-tracer-c++ README for detailed instructions on installing the library for your operating system.

    The library installs by default to /usr/local/, so it may be necessary to add -I/usr/local/include to the compile and link command line (or using CXXFLAGS and LDFLAGS).

    For example, place the two snippets above into the file test.cpp, then run: c++ -std=c++11 -I/usr/local/include -L/usr/local/lib -lopentracing -llightstep_tracer -o test test.cpp

  7. Run the ./test binary to send a span to Lightstep.

  8. Open Lightstep. You should see your service in the Service directory list.

It may take a few moments for your service to display in the Service Directory. To see data immediately, click the Explorer tab to view data in the histogram.

Read the OpenTracing C++ README on GitHub to learn how to continue instrumentation in your service.