SpitfireLoad Testing & APMWhat's new

Connecting a C++ service with OTel

C++ has no agent: you add one header and a few lines to the service, add opentelemetry-cpp to the build and build it again. The service's requests then go to Spitfire as traces (server spans that continue an incoming traceparent). This guide sends traces only; the LOGS and METRICS lines of the environment file stay for when the service sends logs or metrics later.

You need the source code with a CMakeLists.txt, vcpkg (or Conan) on the build machine, and the values from the overview.

Tip

The APM → Services → Services → Add a service wizard fills these steps with your values; each step becomes one command you copy and paste. Connect with the wizard.

Version table

C++ Package Note
C++14 and later, CMake 3.16+ opentelemetry-cpp 1.30.0 with the otlp-http feature (vcpkg); 1.26.0 (Conan Center) The OTLP HTTP exporter pulls in curl and protobuf; vcpkg and Conan build them too
C++11 and earlier not supported opentelemetry-cpp needs C++14

Your version: CMAKE_CXX_STANDARD in CMakeLists.txt (or the -std= flag). The example is for cpp-httplib; with another HTTP server (Boost.Beast, Drogon, Crow) the handler works the same way: give StartServerSpan a function that returns a request header, and the route pattern.

Verified: 2026-11-10. Source: OTLP HTTP example, OTLP exporter environment variables, vcpkg port, Conan Center.

Linux (systemd)

  1. Create the file src/otel.h and paste this:
cpp
// OpenTelemetry for the service: traces over OTLP HTTP (opentelemetry-cpp).
// IS_OTEL_ENABLED=true turns it on; any other value leaves it off. Addresses,
// tokens, sampling and the service name come from the OTEL_* environment values.
#pragma once

#include <cstdlib>
#include <map>
#include <memory>
#include <string>
#include <utility>

#include "opentelemetry/context/propagation/global_propagator.h"
#include "opentelemetry/context/propagation/text_map_propagator.h"
#include "opentelemetry/context/runtime_context.h"
#include "opentelemetry/exporters/otlp/otlp_http_exporter_factory.h"
#include "opentelemetry/exporters/otlp/otlp_http_exporter_options.h"
#include "opentelemetry/sdk/resource/resource.h"
#include "opentelemetry/sdk/trace/batch_span_processor_factory.h"
#include "opentelemetry/sdk/trace/batch_span_processor_options.h"
#include "opentelemetry/sdk/trace/provider.h"
#include "opentelemetry/sdk/trace/samplers/parent_factory.h"
#include "opentelemetry/sdk/trace/samplers/trace_id_ratio_factory.h"
#include "opentelemetry/sdk/trace/tracer_provider.h"
#include "opentelemetry/sdk/trace/tracer_provider_factory.h"
#include "opentelemetry/trace/propagation/http_trace_context.h"
#include "opentelemetry/trace/provider.h"

namespace otel {

namespace api = opentelemetry::trace;
namespace sdk = opentelemetry::sdk::trace;
namespace prop = opentelemetry::context::propagation;
namespace nostd = opentelemetry::nostd;

inline std::string Env(const char *name, const char *def) {
  const char *v = std::getenv(name);
  return v && *v ? v : def;
}

inline std::shared_ptr<sdk::TracerProvider> &Provider() {
  static std::shared_ptr<sdk::TracerProvider> p;
  return p;
}

// Call first in main.
inline void Setup() {
  if (Env("IS_OTEL_ENABLED", "") != "true") return;
  // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, _HEADERS and _CERTIFICATE are read here
  opentelemetry::exporter::otlp::OtlpHttpExporterOptions opts;
  auto processor = sdk::BatchSpanProcessorFactory::Create(
      opentelemetry::exporter::otlp::OtlpHttpExporterFactory::Create(opts), sdk::BatchSpanProcessorOptions{});
  // service.name; OTEL_RESOURCE_ATTRIBUTES (version, environment) is added by Create
  auto resource = opentelemetry::sdk::resource::Resource::Create(
      {{"service.name", Env("OTEL_SERVICE_NAME", "<service-name>")}});
  // parentbased_traceidratio: a caller's decision is kept, new traces by OTEL_TRACES_SAMPLER_ARG
  std::shared_ptr<sdk::Sampler> ratio =
      sdk::TraceIdRatioBasedSamplerFactory::Create(std::strtod(Env("OTEL_TRACES_SAMPLER_ARG", "1").c_str(), nullptr));
  Provider() = sdk::TracerProviderFactory::Create(std::move(processor), resource, sdk::ParentBasedSamplerFactory::Create(ratio));
  std::shared_ptr<api::TracerProvider> global = Provider();
  sdk::Provider::SetTracerProvider(global);
  prop::GlobalTextMapPropagator::SetGlobalPropagator(
      nostd::shared_ptr<prop::TextMapPropagator>(new api::propagation::HttpTraceContext()));
}

// Call before main returns: sends the spans that are left.
inline void Shutdown() {
  if (Provider()) {
    Provider()->ForceFlush();
    Provider()->Shutdown();
  }
}

inline nostd::shared_ptr<api::Tracer> Tracer() {
  return api::Provider::GetTracerProvider()->GetTracer("otel");
}

// The request's headers as the propagator reads them; get(name) returns a header ("" when absent).
template <class Fn>
class Headers : public prop::TextMapCarrier {
 public:
  explicit Headers(Fn get) : get_(std::move(get)) {}
  nostd::string_view Get(nostd::string_view key) const noexcept override {
    auto &v = seen_[std::string(key.data(), key.size())];
    v = get_(std::string(key.data(), key.size()));
    return v;
  }
  void Set(nostd::string_view, nostd::string_view) noexcept override {}

 private:
  Fn get_;
  mutable std::map<std::string, std::string> seen_;
};

// A server span for a request, continuing an incoming traceparent (Spitfire's test).
// route is the route pattern ("/items/:id"), so spans group by route, not by path.
template <class Fn>
nostd::shared_ptr<api::Span> StartServerSpan(const std::string &method, const std::string &route, Fn get) {
  Headers<Fn> headers(std::move(get));
  auto current = opentelemetry::context::RuntimeContext::GetCurrent();
  auto parent = prop::GlobalTextMapPropagator::GetGlobalPropagator()->Extract(headers, current);
  api::StartSpanOptions o;
  o.kind = api::SpanKind::kServer;
  o.parent = parent;
  return Tracer()->StartSpan(method + " " + route, {{"http.request.method", method}, {"http.route", route}}, o);
}

// Ends a server span with the response status (5xx marks it as an error).
inline void EndServerSpan(const nostd::shared_ptr<api::Span> &span, int status) {
  span->SetAttribute("http.response.status_code", status);
  if (status >= 500) span->SetStatus(api::StatusCode::kError);
  span->End();
}

}  // namespace otel
  1. In the file with main (for example src/main.cpp), include the header, call Setup first and Shutdown before main returns, and open a server span in each request handler:
cpp
#include "otel.h"

int main() {
  otel::Setup();  // first in main
  httplib::Server svr;
  svr.Get("/items/:id", [](const httplib::Request &req, httplib::Response &res) {
    auto span = otel::StartServerSpan(req.method, "/items/:id", [&](const std::string &h) { return req.get_header_value(h); });
    auto scope = otel::Tracer()->WithActiveSpan(span);
    res.set_content("item " + req.path_params.at("id"), "text/plain");
    otel::EndServerSpan(span, 200);
  });
  svr.listen("0.0.0.0", 8080);
  otel::Shutdown();  // before main returns: sends the spans that are left
}
  1. Install the package with vcpkg (on Windows in the same way, in PowerShell):
bash
vcpkg install "opentelemetry-cpp[otlp-http]"

With a vcpkg.json in the project (manifest mode), add it there instead: vcpkg add port "opentelemetry-cpp[otlp-http]".

  1. In CMakeLists.txt, add these lines after add_executable and build the service again with the vcpkg toolchain (cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake, then cmake --build build --config Release):
cmake
find_package(opentelemetry-cpp CONFIG REQUIRED)
target_include_directories(${PROJECT_NAME} PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
target_link_libraries(${PROJECT_NAME} PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})

If the executable's target is not named after the project, write its name in place of ${PROJECT_NAME}.

  1. Create the directory, then the file /etc/spitfire-otel/<service-name>.env, and paste this:
bash
sudo mkdir -p /etc/spitfire-otel
bash
IS_OTEL_ENABLED=true
OTEL_SERVICE_NAME=<service-name>
OTEL_RESOURCE_ATTRIBUTES=service.version=<service-version>,deployment.environment=<environment>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://<spitfire>/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=authorization=sfotlp_…
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://<spitfire>/otlp/v1/logs
OTEL_EXPORTER_OTLP_LOGS_HEADERS=authorization=sfotlp_…
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://<tower>:4318/v1/metrics
OTEL_EXPORTER_OTLP_METRICS_HEADERS=authorization=sfcol_…
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
NO_PROXY=<tower>,<spitfire>
  1. Restrict its permission: sudo chmod 600 /etc/spitfire-otel/<service-name>.env
  2. Open sudo systemctl edit <unit> and paste this:
ini
[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env
  1. Put the new binary in place and restart: sudo systemctl daemon-reload && sudo systemctl restart <unit>
  2. Check: send the service a few requests; within a minute the service <service-name> appears under APM → Services → Services, and its spans (GET /items/:id) under its traces.
Note

With a private CA, put the CA file on the machine and add OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/spitfire-otel/ca.pem to the environment file; the C++ exporter reads it.

Installing with Conan

Conan Center has opentelemetry-cpp 1.26.0 (its OTLP HTTP exporter is on by default); the code and the CMakeLists.txt lines stay the same.

  1. Install the package into the build folder:
bash
conan install --requires=opentelemetry-cpp/1.26.0 -o "opentelemetry-cpp/*:with_otlp_http=True" \
  -g CMakeDeps -g CMakeToolchain --build=missing --output-folder=build
  1. Build with Conan's toolchain: cmake -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release && cmake --build build

Docker

  1. Make the code changes (Linux steps 1–4) and build the binary in the image as you do now; vcpkg and Conan link opentelemetry-cpp, curl and protobuf into the binary by default.
  2. The final image must have CA certificates for https://<spitfire> (on Debian/Ubuntu: RUN apt-get update && apt-get install -y ca-certificates).
  3. Save the environment file (Linux step 5) on the Docker machine as /etc/spitfire-otel/<service-name>.env.
  4. Run: docker run --env-file /etc/spitfire-otel/<service-name>.env … or, in compose, under the service env_file: /etc/spitfire-otel/<service-name>.env.
  5. When the environment file changes, recreate the container (restart is not enough): docker compose up -d --force-recreate <service>

Kubernetes

  1. Prepare the image as in the Docker section.
  2. Save the environment file (Linux step 5) as <service-name>.env and make it a Secret:
bash
kubectl create secret generic <service-name>-otel --from-env-file=<service-name>.env \
  --dry-run=client -o yaml | kubectl apply -f -
  1. In the Deployment, add this under the container:
yaml
envFrom:
  - secretRef:
      name: <service-name>-otel
  1. Restart: kubectl rollout restart deployment/<deployment>

Windows (service)

  1. Make the code changes (Linux steps 1–4) and build the .exe again (vcpkg triplet x64-windows).
  2. In an administrator PowerShell, write the service's name (Name in the Get-Service list) in place of <windows-service> and run:
powershell
$Service = "<windows-service>"
$IS_OTEL_ENABLED = "true"
$Otel = @(
  "IS_OTEL_ENABLED=$IS_OTEL_ENABLED",
  "OTEL_SERVICE_NAME=<service-name>",
  "OTEL_RESOURCE_ATTRIBUTES=service.version=<service-version>,deployment.environment=<environment>",
  "OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf",
  "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://<spitfire>/otlp/v1/traces",
  "OTEL_EXPORTER_OTLP_TRACES_HEADERS=authorization=sfotlp_…",
  "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://<spitfire>/otlp/v1/logs",
  "OTEL_EXPORTER_OTLP_LOGS_HEADERS=authorization=sfotlp_…",
  "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://<tower>:4318/v1/metrics",
  "OTEL_EXPORTER_OTLP_METRICS_HEADERS=authorization=sfcol_…",
  "OTEL_TRACES_SAMPLER=parentbased_traceidratio",
  "OTEL_TRACES_SAMPLER_ARG=0.1",
  "NO_PROXY=<tower>,<spitfire>"
)
$Key = "HKLM:\SYSTEM\CurrentControlSet\Services\$Service"
$Keep = @((Get-ItemProperty $Key).Environment | Where-Object { $_ -and $_ -notmatch '^(IS_OTEL_ENABLED|OTEL_|NO_PROXY)=' })
Set-ItemProperty $Key -Name Environment -Type MultiString -Value ($Keep + $Otel)
Restart-Service -Name $Service -Force

Framework: cpp-httplib

cpp-httplib Instrumented by Server span
0.14+ otel::StartServerSpan / otel::EndServerSpan of src/otel.h GET /items/:id (http.route)

Verified: 2026-11-10. Source: cpp-httplib, opentelemetry-cpp http server example.

  1. Make the code changes as in Linux steps 1–4; each handler opens its span with otel::StartServerSpan, giving the route pattern and req.get_header_value (step 2).
  2. Check that the handlers open server spans (<project>: the folder with CMakeLists.txt):
bash
grep -q StartServerSpan <project>/src/otel.h && grep -rq 'otel::StartServerSpan' <project>/src && echo OK

Turning off and removing

  1. Turning off: set IS_OTEL_ENABLED=false and restart the service (on Windows, run the script again). The code stays; Setup then does nothing.
  2. Removing: delete src/otel.h, the #include "otel.h" and otel:: lines and the three CMakeLists.txt lines, and build again; sudo systemctl revert <unit> and sudo rm -r /etc/spitfire-otel; on Windows, delete the OTel lines from the service's Environment value.

Common problems

If no traces arrive at all, follow the Verifying steps first. The most common failure is the first row: CMake run without the vcpkg toolchain.

Symptom Cause Fix
Could not find a package configuration file provided by "opentelemetry-cpp" CMake does not use the vcpkg (or Conan) toolchain Add -DCMAKE_TOOLCHAIN_FILE=… as in Linux step 4
opentelemetry/exporters/otlp/otlp_http_exporter_factory.h: No such file The package was installed without the OTLP HTTP exporter vcpkg install "opentelemetry-cpp[otlp-http]" (with the feature in brackets)
undefined reference to opentelemetry::… Only part of the libraries is linked Link ${OPENTELEMETRY_CPP_LIBRARIES} (Linux step 4)
Spans have no parent from Spitfire's test The span is not opened with StartServerSpan, or the header function returns another header Give the request's own header lookup (Linux step 2)