doc/admin-guide/plugins/otel_tracer.en.rst

.. Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed
   with this work for additional information regarding copyright
   ownership.  The ASF licenses this file to you under the Apache
   License, Version 2.0 (the "License"); you may not use this file
   except in compliance with the License.  You may obtain a copy of
   the License at

      http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
   implied.  See the License for the specific language governing
   permissions and limitations under the License.

.. _admin-plugins-otel-tracer:


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 :term:`global plugin`.  Enable it by adding ``otel_tracer.so`` to your :file:`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.