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.
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)
- Create the file
src/otel.hand paste this:
// 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- In the file with
main(for examplesrc/main.cpp), include the header, callSetupfirst andShutdownbeforemainreturns, and open a server span in each request handler:
#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
}- Install the package with vcpkg (on Windows in the same way, in PowerShell):
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]".
- In
CMakeLists.txt, add these lines afteradd_executableand build the service again with the vcpkg toolchain (cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake, thencmake --build build --config Release):
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}.
- Create the directory, then the file
/etc/spitfire-otel/<service-name>.env, and paste this:
sudo mkdir -p /etc/spitfire-otelIS_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>- Restrict its permission:
sudo chmod 600 /etc/spitfire-otel/<service-name>.env - Open
sudo systemctl edit <unit>and paste this:
[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env- Put the new binary in place and restart:
sudo systemctl daemon-reload && sudo systemctl restart <unit> - 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.
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.
- Install the package into the build folder:
conan install --requires=opentelemetry-cpp/1.26.0 -o "opentelemetry-cpp/*:with_otlp_http=True" \
-g CMakeDeps -g CMakeToolchain --build=missing --output-folder=build- Build with Conan's toolchain:
cmake -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release && cmake --build build
Docker
- 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,curlandprotobufinto the binary by default. - The final image must have CA certificates for
https://<spitfire>(on Debian/Ubuntu:RUN apt-get update && apt-get install -y ca-certificates). - Save the environment file (Linux step 5) on the Docker machine as
/etc/spitfire-otel/<service-name>.env. - Run:
docker run --env-file /etc/spitfire-otel/<service-name>.env …or, in compose, under the serviceenv_file: /etc/spitfire-otel/<service-name>.env. - When the environment file changes, recreate the container (
restartis not enough):docker compose up -d --force-recreate <service>
Kubernetes
- Prepare the image as in the Docker section.
- Save the environment file (Linux step 5) as
<service-name>.envand make it a Secret:
kubectl create secret generic <service-name>-otel --from-env-file=<service-name>.env \
--dry-run=client -o yaml | kubectl apply -f -- In the Deployment, add this under the container:
envFrom:
- secretRef:
name: <service-name>-otel- Restart:
kubectl rollout restart deployment/<deployment>
Windows (service)
- Make the code changes (Linux steps 1–4) and build the
.exeagain (vcpkg tripletx64-windows). - In an administrator PowerShell, write the service's name (Name in the
Get-Servicelist) in place of<windows-service>and run:
$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 -ForceFramework: 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.
- Make the code changes as in Linux steps 1–4; each handler opens its span with
otel::StartServerSpan, giving the route pattern andreq.get_header_value(step 2). - Check that the handlers open server spans (
<project>: the folder withCMakeLists.txt):
grep -q StartServerSpan <project>/src/otel.h && grep -rq 'otel::StartServerSpan' <project>/src && echo OKTurning off and removing
- Turning off: set
IS_OTEL_ENABLED=falseand restart the service (on Windows, run the script again). The code stays;Setupthen does nothing. - Removing: delete
src/otel.h, the#include "otel.h"andotel::lines and the threeCMakeLists.txtlines, and build again;sudo systemctl revert <unit>andsudo rm -r /etc/spitfire-otel; on Windows, delete the OTel lines from the service'sEnvironmentvalue.
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) |