C++ servisini OTel ile bağlamak
C++'ta ajan yok: servise bir header ve birkaç satır ekler, opentelemetry-cpp'yi derlemeye katar ve
yeniden derlersiniz. Servisin istekleri bundan sonra Spitfire'a trace olarak gider (gelen
traceparent'ı sürdüren server span'leri). Bu rehber yalnız trace gönderir; ortam dosyasındaki
LOGS ve METRICS satırları servis ileride log ya da metrik gönderirse diye kalır.
Gerekenler: CMakeLists.txt'li kaynak kod, derleme makinesinde
vcpkg (ya da
Conan) ve genel sayfadaki değerler.
APM → Servisler → Servisler → Servis ekle sihirbazı bu adımları sizin değerlerinizle doldurur; her adım kopyalayıp yapıştıracağınız tek komut olur. Sihirbazla bağlayın.
Sürüm tablosu
| C++ | Paket | Not |
|---|---|---|
| C++14 ve sonrası, CMake 3.16+ | otlp-http özelliğiyle opentelemetry-cpp 1.30.0 (vcpkg); 1.26.0 (Conan Center) |
OTLP HTTP exporter'ı curl ve protobuf çeker; vcpkg ve Conan bunları da derler |
| C++11 ve öncesi | desteklenmiyor | opentelemetry-cpp C++14 ister |
Sürümünüz: CMakeLists.txt'teki CMAKE_CXX_STANDARD (ya da -std= bayrağı). Örnek cpp-httplib
için; başka bir HTTP sunucusunda (Boost.Beast, Drogon, Crow) handler aynı şekilde yazılır:
StartServerSpan'e isteğin bir başlığını döndüren fonksiyonu ve route kalıbını verin.
Doğrulandı: 2026-11-10. Kaynak: OTLP HTTP örneği, OTLP exporter ortam değişkenleri, vcpkg port'u, Conan Center.
Linux (systemd)
src/otel.hdosyasını oluşturun, şunu yapıştırın:
// 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 otelmain'in olduğu dosyada (örneğinsrc/main.cpp) header'ı ekleyin, önceSetup'ı,maindönmeden önceShutdown'ı çağırın ve her istek handler'ında bir server span açın:
#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
}- Paketi vcpkg ile kurun (Windows'ta da aynı şekilde, PowerShell'de):
vcpkg install "opentelemetry-cpp[otlp-http]" Projede vcpkg.json varsa (manifest modu) bunun yerine oraya ekleyin:
vcpkg add port "opentelemetry-cpp[otlp-http]".
CMakeLists.txt'teadd_executable'dan sonra bu satırları ekleyin ve servisi vcpkg toolchain'iyle yeniden derleyin (cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake, ardındancmake --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}) Çalıştırılabilir dosyanın target'ı projenin adını taşımıyorsa ${PROJECT_NAME} yerine onun
adını yazın.
- Klasörü, ardından
/etc/spitfire-otel/<service-name>.envdosyasını oluşturun, şunu yapıştırın:
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>- İzni kısın:
sudo chmod 600 /etc/spitfire-otel/<service-name>.env sudo systemctl edit <unit>açın, şunu yapıştırın:
[Service]
EnvironmentFile=/etc/spitfire-otel/<service-name>.env- Yeni binary'yi yerine koyup yeniden başlatın:
sudo systemctl daemon-reload && sudo systemctl restart <unit> - Kontrol edin: servise birkaç istek gönderin; bir dakika içinde
<service-name>servisi APM → Servisler → Servisler altında, span'leri (GET /items/:id) trace'lerinde görünür.
Özel CA varsa CA dosyasını makineye koyup ortam dosyasına
OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/spitfire-otel/ca.pem ekleyin; C++ exporter'ı bunu okur.
Conan ile kurmak
Conan Center'da opentelemetry-cpp 1.26.0 var (OTLP HTTP exporter'ı varsayılan olarak açık); kod ve
CMakeLists.txt satırları aynı kalır.
- Paketi derleme klasörüne kurun:
conan install --requires=opentelemetry-cpp/1.26.0 -o "opentelemetry-cpp/*:with_otlp_http=True" \
-g CMakeDeps -g CMakeToolchain --build=missing --output-folder=build- Conan'ın toolchain'iyle derleyin:
cmake -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release && cmake --build build
Docker
- Kod değişikliklerini yapın (Linux 1–4. adım) ve binary'yi image'da bugünkü gibi derleyin; vcpkg
ve Conan varsayılan olarak
opentelemetry-cpp,curlveprotobuf'u binary'ye bağlar. - Son image'da
https://<spitfire>için CA sertifikaları olmalı (Debian/Ubuntu'da:RUN apt-get update && apt-get install -y ca-certificates). - Ortam dosyasını (Linux 5. adım) Docker makinesinde
/etc/spitfire-otel/<service-name>.envolarak kaydedin. - Çalıştırın:
docker run --env-file /etc/spitfire-otel/<service-name>.env …ya da compose'da servisin altınaenv_file: /etc/spitfire-otel/<service-name>.env. - Ortam dosyası değişince konteyneri yeniden oluşturun (
restartyetmez):docker compose up -d --force-recreate <service>
Kubernetes
- Image'ı Docker bölümündeki gibi hazırlayın.
- Ortam dosyasını (Linux 5. adım)
<service-name>.envolarak kaydedip Secret yapın:
kubectl create secret generic <service-name>-otel --from-env-file=<service-name>.env \
--dry-run=client -o yaml | kubectl apply -f -- Deployment'ta container'ın altına ekleyin:
envFrom:
- secretRef:
name: <service-name>-otel- Yeniden başlatın:
kubectl rollout restart deployment/<deployment>
Windows (servis)
- Kod değişikliklerini yapın (Linux 1–4. adım) ve
.exe'yi yeniden derleyin (vcpkg triplet'ix64-windows). - Yönetici PowerShell'de
<windows-service>yerine servisin adını (Get-Servicelistesindeki Name) yazıp çalıştırın:
$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 | Enstrümantasyon | Server span |
|---|---|---|
| 0.14+ | src/otel.h içindeki otel::StartServerSpan / otel::EndServerSpan |
GET /items/:id (http.route) |
Doğrulandı: 2026-11-10. Kaynak: cpp-httplib, opentelemetry-cpp http server örneği.
- Kod değişikliklerini Linux 1–4. adımlardaki gibi yapın; her handler span'ini route kalıbı ve
req.get_header_valueileotel::StartServerSpan'den açar (2. adım). - Handler'ların server span açtığına bakın (
<project>:CMakeLists.txt'in olduğu klasör):
grep -q StartServerSpan <project>/src/otel.h && grep -rq 'otel::StartServerSpan' <project>/src && echo OKKapatma ve kaldırma
- Kapatmak:
IS_OTEL_ENABLED=falseyapıp servisi yeniden başlatın (Windows'ta betiği yeniden çalıştırın). Kod kalır,Setupo zaman hiçbir şey yapmaz. - Kaldırmak:
src/otel.hdosyasını,#include "otel.h"veotel::satırlarını veCMakeLists.txt'e eklenen üç satırı silip yeniden derleyin;sudo systemctl revert <unit>vesudo rm -r /etc/spitfire-otel; Windows'ta servisinEnvironmentdeğerinden OTel satırlarını silin.
Sık karşılaşılan sorunlar
Hiç trace gelmiyorsa önce Doğrulama adımlarını uygulayın. En sık karşılaşılan hata tablonun ilk satırı: CMake'in vcpkg toolchain'i olmadan çalıştırılması.
| Belirti | Neden | Çözüm |
|---|---|---|
Could not find a package configuration file provided by "opentelemetry-cpp" |
CMake vcpkg'nin (ya da Conan'ın) toolchain'ini kullanmıyor | Linux 4. adımdaki gibi -DCMAKE_TOOLCHAIN_FILE=… ekleyin |
opentelemetry/exporters/otlp/otlp_http_exporter_factory.h: No such file |
Paket OTLP HTTP exporter'ı olmadan kurulmuş | vcpkg install "opentelemetry-cpp[otlp-http]" (özellik köşeli parantezde) |
undefined reference to opentelemetry::… |
Kütüphanelerin yalnız bir kısmı bağlanmış | ${OPENTELEMETRY_CPP_LIBRARIES} bağlayın (Linux 4. adım) |
| Span'lerin Spitfire testinden parent'ı yok | Span StartServerSpan ile açılmıyor ya da başlık fonksiyonu başka başlık döndürüyor |
İsteğin kendi başlık aramasını verin (Linux 2. adım) |