OpenTelemetry Tracer Plugin

Description

This plugin allows ATS to participate in OpenTelemetry distributed tracing system. The plugin attaches B3 headers to the transaction and sends trace information to an OTLP HTTP endpoint, typically provided through a OpenTelemetry collector.

See the documentation on OpenTelemetry at https://opentelemetry.io/docs/.

How it Works

This plugin checks incoming requests for the B3 headers. If they are present, the plugin will participate in the same trace and generate a new span ID. If the header is not present, the plugin will generate new trace ID and span ID. These information will be added as request headers for transaction going upstream. Also together with transaction information such as incoming URL, method, response code, etc, it will be sent to a OTLP HTTP endpoint.

Sample B3 headers:

X-B3-Sampled: 1
X-B3-SpanId: 2e56605382810dc9
X-B3-TraceId: b9e48850a375247c2c416174648844f4

Compiling the Plugin

To compile this plugin, we need nlohmann-json, protobuf and opentelemetry-cpp

nlohmann-json:

cd
wget https://github.com/nlohmann/json/archive/refs/tags/v3.9.1.tar.gz
tar zxvf v3.9.1.tar.gz
cd json-3.9.1
mkdir build
cd build
cmake .. -DCMAKE_CXX_STANDARD=17 -DCMAKE_CXX_STANDARD_REQUIRED=ON
make
make install

protobuf:

cd
wget https://github.com/protocolbuffers/protobuf/archive/refs/tags/v3.19.4.tar.gz
tar zxvf v3.19.4.tar.gz
cd protobuf-3.19.4
./autogen.sh
./configure --enable-shared=no --enable-static=yes CXXFLAGS="-std=c++17 -fPIC" CFLAGS="-fPIC"
make
make install

opentelemetry-cpp

cd
wget https://github.com/open-telemetry/opentelemetry-cpp/archive/refs/tags/v1.3.0.tar.gz
tar zxvf v1.3.0.tar.gz
cd opentelemetry-cpp-1.3.0
mkdir build
cd build
cmake .. -DBUILD_TESTING=OFF -DWITH_EXAMPLES=OFF -DWITH_JAEGER=OFF -DWITH_OTLP=ON -DWITH_OTLP_GRPC=OFF -DWITH_OTLP_HTTP=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_CXX_STANDARD=17 -DCMAKE_CXX_STANDARD_REQUIRED=ON
cmake --build . --target all
cmake --install . --config Debug --prefix /usr/local/

Installation

The OpenTelemetry Tracer plugin is a global plugin. Enable it by adding otel_tracer.so to your plugin.config.

Configuration

The plugin supports the following options:

  • -u=[OTLP HTTP url endpoint] (default: http://localhost:4317/v1/traces)

This is the OTLP HTTP url endpoint, typically provided by a OpenTelemetry collector.

  • -s=[service name] (default: otel_tracer)

This is the service name that will be sent as part of the information to the OTLP HTTP url endpoint.

  • -r=[sampling rate] (default: 1.0)

The value can be between 0.0 to 1.0. It controls the sampling rate of the trace information.